> ## 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.

# How configuration works

> How a repository configures its rigs and agents, and how Amika resolves settings across sources.

A rig needs to know what image to boot, what to install, what services to
expose, and which secrets to inject. Amika reads that from **repository
configuration** — a `.amika/config.toml` file committed at the root of your repo.
When a rig is created from the repo, Amika reads the file and applies the
settings automatically, so every collaborator gets the same environment without
passing extra flags.

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

This guide explains how configuration reaches a rig: where it can come from,
how Amika resolves conflicts, and how it behaves for multi-repo and repo-less
rigs. For the full field-by-field spec, see
[config.toml reference](https://docs.amika.dev/guides/config-toml.md).

## What a repo config controls

`.amika/config.toml` is a template for the rigs created from a repository.
Each section maps to one dimension of the rig:

* **`[lifecycle]`** — setup and start scripts that provision the environment.
* **`[env]`** — environment variables and secret references.
* **`[services.<name>]`** — named services with port bindings and public URLs.
* **`[sandbox]`** — the default preset, size, and boot snapshot.
* **`[filesystem]`** — additional repos to clone alongside the primary one.
* **`[agent_credentials]`** — which stored credential each agent uses by default.
* **`[workflow]`**: a hosted multi-step agent workflow.

Because the file lives in the repo, it is versioned with your code and easy for
a coding agent to read and edit. That makes it the **recommended** place to
declare rig settings.

## How configuration is applied

The same setting can be declared in more than one place. Amika resolves each
setting independently, taking the first non-empty value in this order:

| Priority | Source | Where it comes from |
| - | - | - |
| 1 (highest) | **API request / CLI flags** | Values passed at rig creation time |
| 2 | **Database** | Values saved through the web UI |
| 3 | **`.amika/config.toml`** | Committed in the repository |
| 4 (lowest) | **Built-in default** | Fallback when nothing else is set |

Resolution is per-dimension: a preset from a CLI flag, env vars from the TOML,
and a size from a UI setting can all apply to the same rig at once. A value
saved through the web UI becomes the "Database" layer and overrides the
corresponding `.amika/config.toml` value for all future rigs; the UI shows
a notice when a value originates from the TOML file.

> [!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 — unlike
> UI or per-request settings, which live outside the repo. Reserve CLI flags and
> the UI for one-off overrides.

### Setting a value across surfaces

Setting the rig preset is a good example — you can declare it once in the
repo, override it per rig from the CLI, or set a repository default in the
UI. All three feed the resolution table above.

> [tab] .amika/config.toml
>
> Commit the default with your code. It applies to every rig created from
> the repo.
>
> ```toml theme={null}
> [sandbox]
> preset = "coder-plus-docker"
> ```

> [tab] CLI
>
> Override the preset for a single rig at create time.
>
> ```bash theme={null}
> amika rig create --preset coder-plus-docker
> ```

> [tab] Web UI
>
> On [app.amika.dev](https://app.amika.dev), open **Repos** and select your
> repo. In the **Rig Image** section, pick a **Preset**, then click **Save**.
> This becomes the "Database" layer and wins over the `[sandbox]` value in
> `.amika/config.toml`.

## Multi-repo rigs

A rig can clone more than one repository. List the extra repos under
[`[filesystem].repos`](https://docs.amika.dev/guides/config-toml#filesystem) in the primary repo's
config. Each is cloned into `~/workspace/<repo-name>` alongside the primary.

> [!WARNING]
>
> Only the **primary repo's** `.amika/config.toml` is applied. The primary repo is
> the one the rig is created from — the repo that carries the `[filesystem]`
> list. Any `.amika/config.toml` in an additional repo is **ignored**: its
> `[env]`, `[services]`, `[lifecycle]`, and other sections have no effect. Declare
> everything the rig needs in the primary repo's config.

```toml theme={null}
# In the primary repo's .amika/config.toml
[filesystem]
repos = [
  "https://github.com/gofixpoint/amika",
  "https://github.com/gofixpoint/amika-mono",
]
```

## Repo-less rigs

A repository is optional. A rig can boot with **no repo** — and therefore no
`.amika/config.toml`. This is useful for scratch environments, or when you clone
repos yourself after connecting.

With no config file, every setting falls through to the API request / CLI flags
layer or the built-in default. Pass the preset, size, env vars, and credentials
you need at create time.

```bash theme={null}
# Create a repo-less rig and configure it inline
amika rig create --name scratch --no-git --preset coder --size m
```

See [Create a rig](https://docs.amika.dev/guides/create-a-rig.md) for how the CLI picks (or
skips) a repo.

## Related docs

* [config.toml reference](https://docs.amika.dev/guides/config-toml.md) — full field-by-field spec
* [Create a rig](https://docs.amika.dev/guides/create-a-rig.md) — repo detection and `--no-git`
* [Repository configuration](https://docs.amika.dev/reference/repository-configuration.md) — reference-tab summary
* [Manage secrets](https://docs.amika.dev/guides/manage-secrets.md) — pushing secrets referenced from `[env]`


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