karta.toml is an optional file at the root of an agent project. It carries the
agent’s name and deploy gate - read locally by karta setup, karta status, and karta deploy - and the build hints the
release builder uses to run the agent project. A project
with no karta.toml still runs under karta dev; the file is what makes the
project a named, deployable agent.
karta create writes a starter karta.toml with deploy = false.
karta setup --enable flips that gate when you are ready to ship.
Example
karta.toml
name is the slug the agent deploys as, deploy = true opts the folder into
deploys, Karta imports app from app.py to obtain the Karta instance, and
the python buildpack tells the builder to synthesize a Python runtime image.
Keys
The agent’s name, unique within your org - the slug it deploys as. Read
locally by
karta setup, karta status, and karta deploy. Deploying again
with the same name publishes a new release of that agent.The per-agent deploy gate.
karta deploy (and git push karta) builds a
folder only when its karta.toml sets deploy = true; absent or false
leaves it configured but not deployed.The
module:attribute that exposes your Karta instance - e.g. app:app
means “import app from app.py.” Required when buildpack is set.The buildpack to run -
python or node. When present, Karta builds the
release for that language. Omit it, and ship no Dockerfile, to run the file
tree directly.Declares the environment variables the agent expects. Each entry is
NAME = { required = true, description = "..." }. This is the declare half
of the env workflow - bind values locally in .env and in production with
karta env set. A required var with no
production binding fails the deploy build.Selects the agent runtime.
type names the harness runtime - "claude-code",
"opencode", "deepagents", "goose", or "codex-cli" - and is fixed for
the life of the agent; switching harness means a new agent. karta create --harness
writes this block for new CLI-scaffolded agents, and karta setup writes the
detected type when it configures an existing native harness folder.
version is optional: a range like "2" resolves to the latest matching
version Karta supports at deploy time, omitting it takes the curated default,
and pinning an exact version gives you a deterministic runtime. karta deploy
checks the requested version against the versions Karta supports and reports the
exact harness and version your release was frozen to.Prepares the agent’s workspace before it runs.
setup names a shell script Karta
runs once when the workspace is first prepared, before the first turn - use it to
install the packages your agent needs (pip install ..., npm install ...). Installs
land in the agent’s home directory, so they persist with the
workspace and are available on every turn.Build-kind resolution
The builder picks one of three strategies, in order:
Karta validates the package before activation:
karta.toml must parse, the
archive must fit the size limits, and file paths must stay inside the agent
project.
Multiple agents in one repo
A single repo can hold many agents - each a folder with its ownkarta.toml
carrying a name and deploy = true. One karta deploy (or
git push karta) builds every enabled agent in the tree, each from its own
subdirectory. A folder with deploy absent or false is skipped. See
the deploy loop for how the fan-out runs.
Do not confuse
karta.toml (an agent’s identity, deploy gate, and build
hints) with karta.jsonc (CLI, harness, and runtime
settings) - the latter governs how the deployed agent behaves when it runs.