Provider routing and sandboxes
What you'll do
Walk through provider selection, budget/quota gating, failover, optional MCP routing, sandbox selection, and the environment receipts that record each decision. Provider and sandbox routing are kept separate so policy can audit each boundary independently.
Two independent decisions.
Provider routing chooses model/runtime metadata. Sandbox routing chooses an execution environment. Keeping them separate lets policy, receipts, and redaction audit each boundary on its own terms.
Routing flow
- Select a model provider from Model providers.
- Check provider budget and quota before dispatch.
- Evaluate provider failover only when a configured fallback rule allows it.
- Use MCP client metadata for provider or tool routes that cross an MCP boundary.
- Select a sandbox backend for execution.
- Record environment receipts for allowed and denied provider or sandbox decisions.
Provider configuration
Provider id · family · modes · capabilities
Trust boundary
Config reference names
Secret reference names
Budget and quota refs
Runtime path
Docs links
Local model routing
Local model presets are provider records with a local trust boundary and no secret references by default. Use them when the model server is OpenAI-compatible and reachable on loopback:
provider_local_openai_compatible
Generic local OpenAI-compatible endpoint.
provider_local_ollama
Ollama OpenAI-compatible endpoint.
provider_local_lm_studio
LM Studio local server.
provider_local_vllm
vLLM OpenAI-compatible server.
Run craik provider local-presets to inspect preset metadata and
craik provider local-health <preset> to check /v1/models before
enabling live local routing. Local HTTP URLs must remain loopback
unless a future sandbox policy explicitly allows a wider boundary.
Secrets are references, not values.
Secret values never appear in provider records, CLI output, docs, receipts, or fixtures. Store raw credentials outside Craik and refer to them by secret reference name.
MCP integration
MCP export boundary
Decide which Craik surfaces can be exported as MCP tools.
MCP client
Client-side provider and tool routing.
MCP routes must remain:
Grant-required
Receipt-required
Redacted
Documented
When part of the compatibility surface.
Sandbox backends
The v0.9.0 sandbox surfaces:
Policy, grants, receipts, redaction — every backend.
All sandbox actions require explicit policy, capability grants, receipts, and redaction. Local and remote shell helpers use command references instead of inline shell strings. Docker requests require explicit network, mount, image, command, and environment references. Browser/tool results are redacted before receipt metadata is persisted.
Safe diagnostics
craik provider listcraik provider show <id>craik provider select <id> --mode runner --policy-envelope-id <id>craik demo persistent-agent --repo-path .Validation
uv run --extra dev pytest tests/test_model_providers.py tests/test_mcp_client.py tests/test_sandbox_backend.py tests/test_environment_receipts.py
Expected output: passing tests for provider metadata, MCP client routing, sandbox backend contracts, and environment receipts.
uv run --extra dev pytest tests/test_sandbox_policy_boundaries.py
Expected output: passing tests for allowed sandbox actions, denied missing-policy controls, denied unsafe isolation defaults, and redacted environment receipts.
Public boundary.
Do not include local filesystem paths, private hostnames, raw command payloads, environment maps, webhook secrets, bearer tokens, SSH keys, provider credentials, or unredacted tool outputs in public docs. Use stable fixture ids, config refs, and secret reference names instead.