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

# Repository configuration

> How .amika/config.toml configures rigs, and how settings resolve across sources.

Repository configuration lets you commit rig settings alongside your code in
`.amika/config.toml`. When a rig is created from a repository, Amika reads
this file and applies the settings automatically — every collaborator gets the
same environment without passing extra flags.

> [!NOTE]
>
> This page is the reference-tab summary. For the full concept guide — including
> multi-repo and repo-less rigs — see
> [How configuration works](https://docs.amika.dev/guides/configuration.md). For the field-by-field spec,
> see the [config.toml reference](https://docs.amika.dev/guides/config-toml.md).

## File location

```
<repo-root>/
  .amika/
    config.toml
```

Amika looks for this file at the root of the repository selected by
`amika rig create`, whether the CLI detects the repository from the current
directory or you pass `--git <path-or-URL>`.

## Configuration resolution

Repository configuration acts as a template for rigs. Settings can come
from multiple sources, and Amika resolves them in priority order:

| Priority | Source | Description |
| - | - | - |
| 1 (highest) | **API request / CLI flags** | Values provided at rig creation time |
| 2 | **Database** | Values saved via the web UI |
| 3 | **`.amika/config.toml`** | Committed in the repository |
| 4 (lowest) | **Built-in default** | Fallback when nothing else is configured |

The first non-empty value wins. Each configuration dimension (setup script,
start script, env vars, services, rig settings, additional repos, agent
credential defaults, and workflows) is resolved independently.

> [!TIP]
>
> Prefer `.amika/config.toml` as your source of truth: it is versioned with your
> code, reviewable in pull requests, and easy for coding agents to edit. When you
> save a setting via the web UI it becomes the Database layer and overrides the
> corresponding TOML value for all future rigs; the UI shows a notice when a
> value originates from the TOML file.

## Sections at a glance

`.amika/config.toml` has these tables. Each links to its full spec.

| Table | Purpose |
| - | - |
| [`[lifecycle]`](https://docs.amika.dev/guides/config-toml#lifecycle) | Setup and start scripts |
| [`[env]`](https://docs.amika.dev/guides/config-toml#env) | Environment variables and secret references |
| [`[services.<name>]`](https://docs.amika.dev/guides/config-toml#services) | Named services with port bindings and URL schemes |
| [`[sandbox]`](https://docs.amika.dev/guides/config-toml#sandbox) | Default preset, size, and boot snapshot |
| [`[filesystem]`](https://docs.amika.dev/guides/config-toml#filesystem) | Additional repos to clone |
| [`[agent_credentials]`](https://docs.amika.dev/guides/config-toml#agent_credentials) | Per-agent credential defaults |
| [`[workflow]`](https://docs.amika.dev/guides/config-toml#workflow) | Multi-step agent workflow |

## `[lifecycle]` — Setup and start scripts

Lifecycle scripts run at rig initialization. Paths are relative to the
repository root.

```toml theme={null}
[lifecycle]
setup_script = "scripts/setup.sh"
start_script = "scripts/start.sh"
```

* **`setup_script`** runs once during initial creation with the working
  directory set to `$AMIKA_AGENT_CWD`. The hosted platform reads the file's
  contents, so its executable bit in Git is not required. A nonzero exit marks
  setup as failed, but the rig remains accessible. Passing `--setup-script` to
  `amika rig create` takes priority.
* **`start_script`** runs each time a stopped rig is started again — not on
  the initial create. It is re-read on each start. Use it for steps that must
  repeat on resume (starting a dev server, re-opening a tunnel).

| Flags passed | Setup source used |
| - | - |
| Auto-detected repository | `.amika/config.toml` (if present) |
| `--setup-script ./script.sh` | `--setup-script` flag |
| `--no-setup` | Built-in no-op script |

See the [`[lifecycle]` spec](https://docs.amika.dev/guides/config-toml#lifecycle) for full details.

## `[filesystem]` — Additional repos

Clone extra repositories into the rig alongside the primary repo.

```toml theme={null}
[filesystem]
repos = [
  "https://github.com/gofixpoint/amika",
  "https://github.com/gofixpoint/amika-mono",
]
```

Each entry is a GitHub repository URL, cloned at its default branch into
`~/workspace/<repo-name>`. The primary repo is inferred automatically and need
not be listed.

> [!WARNING]
>
> Only the **primary repo's** `.amika/config.toml` is applied. A
> `.amika/config.toml` in an additional repo is ignored. See
> [multi-repo rigs](https://docs.amika.dev/guides/configuration.md#multi-repo-rigs).

See the [`[filesystem]` spec](https://docs.amika.dev/guides/config-toml#filesystem) for validation and
merge semantics.

## Branch selection

When `--branch` is specified on `amika rig create`, the `.amika/config.toml`
file is read from that branch rather than the repository's default branch. This
allows different branches to carry different rig configurations.

```bash theme={null}
amika rig create --branch feature/new-api
```

## Example

Given this repository layout:

```
my-project/
  .amika/
    config.toml
    setup.sh
  src/
    ...
```

With this `config.toml`:

```toml theme={null}
[lifecycle]
setup_script = ".amika/setup.sh"

[env]
NODE_ENV = "development"
API_KEY = { secret = "my-api-key" }

[services.web]
port = 3000
url_scheme = "http"

[sandbox]
preset = "coder"
size = "m"
```

Running `amika rig create` from anywhere inside `my-project` will:

1. Clone the repository into the rig.
2. Mount `.amika/setup.sh` as the setup script.
3. Set `NODE_ENV=development` and resolve `API_KEY` from the secrets store.
4. Publish port 3000 with an HTTP URL.
5. Use the `coder` preset with medium resource allocation.

## Related docs

* [How configuration works](https://docs.amika.dev/guides/configuration.md) — concept guide: precedence, multi-repo, repo-less
* [config.toml reference](https://docs.amika.dev/guides/config-toml.md) — full field-by-field spec
* [Rig configuration](https://docs.amika.dev/reference/rig-configuration.md) — CLI flags, credential mounting, reserved ports
* [Services](https://docs.amika.dev/reference/services.md) — full `[services.<name>]` reference


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.