> ## Documentation Index
> Fetch the complete documentation index at: https://docs.karta.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# karta.toml reference

> An agent's local identity, deploy gate, and build hints.

`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](/concepts/releases) 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

```toml karta.toml theme={null}
# Karta deploy manifest.
name = "support-bot"
deploy = true

# `entry_point` is the module:attribute exposing the Karta instance.
entry_point = "app:app"
buildpack = "python"
```

This is the manifest from the [support-bot tutorial](/tutorials/support-bot):
`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

<ResponseField name="name" type="string">
  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.
</ResponseField>

<ResponseField name="deploy" type="boolean">
  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.
</ResponseField>

<ResponseField name="entry_point" type="string">
  The `module:attribute` that exposes your `Karta` instance - e.g. `app:app`
  means "import `app` from `app.py`." Required when `buildpack` is set.
</ResponseField>

<ResponseField name="buildpack" type="string">
  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.
</ResponseField>

<ResponseField name="[env]" type="table">
  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`](/cli/overview#environment). A `required` var with no
  production binding fails the deploy build.
</ResponseField>

<ResponseField name="[harness]" type="table">
  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.
</ResponseField>

<ResponseField name="[environment]" type="table">
  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](/concepts/instances-and-memory) and are available on every turn.
</ResponseField>

## Build-kind resolution

The builder picks one of three strategies, in order:

| Signal                                                         | Build kind   | What happens                                     |
| -------------------------------------------------------------- | ------------ | ------------------------------------------------ |
| A `Dockerfile` in the repo                                     | `dockerfile` | Build the image from your Dockerfile.            |
| `buildpack = "python"` or `buildpack = "node"` in `karta.toml` | `buildpack`  | Build the release for that language.             |
| neither                                                        | direct       | Run the extracted file tree directly (no image). |

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 own `karta.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](/deploy/deploy-loop) for how the fan-out runs.

<Info>
  Do not confuse `karta.toml` (an agent's identity, deploy gate, and build
  hints) with [`karta.jsonc`](/build/configuration) (CLI, harness, and runtime
  settings) - the latter governs how the deployed agent behaves when it runs.
</Info>