Skip to content

Configuration ​

Everything is environment-driven, and nothing is required — with no configuration at all the Todo demo still runs end to end, using keyword search and a fixed program.

A copy of this lives in .env.example at the repository root.

Models ​

VariableValuesDefault
LLM_PROVIDERclaude, openaiwhichever key is set, Claude first
LLM_BASE_URLany compatible endpointthe vendor's
ANTHROPIC_API_KEY—
ANTHROPIC_MODELclaude-opus-5
ANTHROPIC_BASE_URLwins over LLM_BASE_URL—
OPENAI_API_KEY—
OPENAI_MODELgpt-5
OPENAI_BASE_URLwins over LLM_BASE_URL—

Generation settings ​

Shared by every provider. All optional.

VariableValuesDefault
LLM_MAX_TOKENSinteger16000, sized for thinking plus a program
LLM_TIMEOUTGo duration, e.g. 45sthe SDK's own
LLM_TEMPERATUREfloatunset — the provider's own default
LLM_TOP_Pfloatunset

Anything set in code wins over these, so an application can pin a value a deployment cannot override by accident. A base URL may be set without an API key, for endpoints that do not authenticate.

WARNING

LLM_TEMPERATURE and LLM_TOP_P turn Claude's extended thinking off — Anthropic rejects sampling parameters alongside it. Leave both unset unless you have a reason. See Models.

VariableValuesDefault
CAPABILITY_DBsqlite, postgressqlite
CAPABILITY_DB_DSNfile path, or connection URLunset — falls back to keyword search
SQLITE_VECTOR_EXTENSIONabsolute path to vector.dylib / vector.so—

Embeddings ​

VariableValuesDefault
EMBEDDING_MODELany embeddings modeltext-embedding-3-small
EMBEDDING_API_KEYfalls back to OPENAI_API_KEY
EMBEDDING_BASE_URLfalls back to OPENAI_BASE_URL, then LLM_BASE_URL

Always the OpenAI embeddings protocol, regardless of LLM_PROVIDER — Anthropic publishes no embeddings API. See Search.

Sandbox ​

VariableValuesDefault
SANDBOX_ENGINEthe language: goja, starlark, luagoja
SANDBOX_ISOLATIONinprocess, processinprocess
SANDBOX_TIMEOUTGo duration, e.g. 10s30s
SANDBOX_MAX_CALLSinteger50
SANDBOX_WORKERargv for codemode-worker, space-separated; process onlycodemode-worker on PATH
SANDBOX_WORKER_CONTAINERtrue when SANDBOX_WORKER starts a containerfalse
SANDBOX_MAX_HEAP_BYTESinteger; process isolation only268435456

Options passed in code win over these. See Sandbox and Running the worker.

sandbox.New refuses a configuration that is probably a mistake rather than guessing:

ConfigurationError
an isolation that is not inprocess or registeredsandbox isolation "x" is unknown
process without importing sandbox/subprocess... is not registered: add _ ".../sandbox/subprocess"
SANDBOX_WORKER or SANDBOX_WORKER_CONTAINER with inprocessa worker is configured but isolation is inprocess
SANDBOX_WORKER_CONTAINER=true with no SANDBOX_WORKERworker container is set but no worker command is
process, but the worker does not start or answercodemode-worker check failed (...)

The last check runs one trivial program through the worker inside New, so a missing binary, a version mismatch, a bad docker run or a missing image fails at startup, not on the first request.

Observing runs ​

There is no tracing dependency. agent.Options.OnEvent sees every step of a run, each capability call included, with the run's ID; feed it to whatever the host already runs. It must not block.

go
agent.Run(ctx, mode, model, request, agent.Options{
    Runner:  runner,
    OnEvent: agent.LogEvents(slog.Default().With("user", user)),
})

The same hook is where an audit log or an OpenTelemetry span goes; see Observability.

Commands ​

CommandWhat it does
mise installInstall pinned tools: Buf, Node, pnpm
make generateRegenerate Go from every proto module and the example's registry.json
make demo-todoRegenerate, then run the Todo example end to end
make testBuf lint plus all Go tests
make test-vectorSQLite vector search; needs SQLITE_VECTOR_EXTENSION
make test-postgrespgvector search against a throwaway container
make docsServe these docs locally with hot reload
make docs-buildBuild the static docs site

Every command works from the repository root and exits non-zero on failure.

Combinations worth knowing ​

Fully local, nothing leaves the machine. Ollama for both the model and the embeddings, SQLite for the index:

sh
LLM_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen2.5-coder
EMBEDDING_MODEL=nomic-embed-text
CAPABILITY_DB=sqlite
CAPABILITY_DB_DSN=capabilities.db
SQLITE_VECTOR_EXTENSION=/usr/local/lib/vector.so

No CGO. Postgres avoids the SQLite C dependency entirely:

sh
CAPABILITY_DB=postgres
CAPABILITY_DB_DSN=postgres://user:pass@localhost:5432/codemode?sslmode=disable

Tighter blast radius. Starlark has no while loops or recursion, and a small budget bounds a misbehaving program hard:

sh
SANDBOX_ENGINE=starlark
SANDBOX_TIMEOUT=5s
SANDBOX_MAX_CALLS=10