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

# Rig configuration

> Configure hosted rigs with repository settings and CLI overrides.

`amika rig` manages hosted rigs. The retired `--local` flag is not supported.

Repository settings in `.amika/config.toml` provide defaults. CLI flags on
`amika rig create` override those defaults for one rig.

## Repository selection

Run `amika rig create` from inside a Git repository to use that repository
automatically:

```bash theme={null}
cd /path/to/repo
amika rig create
```

Pass a local path or Git URL to select a different repository:

```bash theme={null}
amika rig create --git /path/to/repo
amika rig create --git https://github.com/gofixpoint/example-repo.git
```

Pass `--no-git` to create a rig without a repository:

```bash theme={null}
amika rig create --no-git
```

Hosted rigs clone from the remote repository. Local modifications are not
uploaded. Push the branch, configuration, and scripts before creating the rig:

```bash theme={null}
git add .amika
git commit -m "Update Amika rig configuration"
git push
amika rig create
```

When the CLI infers a local branch, it rejects creation if the branch has not
been pushed or is not up to date with `origin`.

## Repository configuration

Amika reads `.amika/config.toml` from the selected repository. Common settings
include:

* Lifecycle setup and start scripts
* Environment variables and secret references
* Named services and published URLs
* Preset, size, and default snapshot
* Additional repositories
* Default agent credentials
* Agent workflows

See [How configuration works](https://docs.amika.dev/guides/configuration.md) and the
[config.toml reference](https://docs.amika.dev/guides/config-toml.md).

## Create-time overrides

Use CLI flags for one-off overrides:

```bash theme={null}
# Override the preset or size
amika rig create --preset coder-plus-docker --size m

# Override the setup script with a local file
amika rig create --setup-script ./install-deps.sh

# Skip the repository setup script
amika rig create --no-setup

# Select a branch
amika rig create --branch feature/new-api
```

Run `amika rig create --help` for the complete current flag list.

## Lifecycle scripts

### Setup script

`[lifecycle].setup_script` runs once during initial rig creation. The
`--setup-script` flag takes priority, while `--no-setup` replaces it with a
no-op script.

For hosted repository configuration:

* Use a path relative to the repository root.
* Include a shebang and exit `0` on success.
* Use `$AMIKA_AGENT_CWD` for the primary repository path.
* The executable bit on the source file in Git is not required.
* A nonzero exit records a setup failure. The rig remains active and
  accessible for debugging.

### Start script

`[lifecycle].start_script` runs each time a stopped rig starts again. It does
not run during initial creation. Amika re-reads it from the repository inside
the rig on each start.

Use it for work that must repeat after a stop, such as starting development
services. Keep one-time package installation and builds in the setup script.

## Agent credentials

Hosted rigs receive selected credentials from Amika's remote credential store.
The CLI can discover credentials on the machine where it runs and push them to
that store:

```bash theme={null}
amika secret claude push --type oauth
amika secret codex push --type oauth
```

Select credentials during creation:

```bash theme={null}
amika rig create \
  --agent-credential-type claude=oauth \
  --agent-credential-type codex=oauth
```

You can also set repository defaults under `[agent_credentials]`. See
[Inject credentials](https://docs.amika.dev/guides/inject-credentials.md).

## Setup failure behavior

A user setup or start script can fail without destroying the rig. Amika keeps
the VM accessible and records the setup status and sanitized error detail.
Inspect lifecycle output, connect to the rig, correct the script, and create or
start the rig again.

## Reserved ports

Amika reserves container ports 60899 through 60999 for internal services.

| Port | Service |
| - | - |
| 60999 | `amikad` daemon |
| 60998 | OpenCode web UI |
| 60997 | Managed SSH daemon |
| 60996 | Pi Web UI |
| 60899 through 60995 | Reserved for future use |

Do not bind repository services or setup-script processes to this range.

## Related docs

* [How configuration works](https://docs.amika.dev/guides/configuration.md)
* [config.toml reference](https://docs.amika.dev/guides/config-toml.md)
* [Services](https://docs.amika.dev/reference/services.md)
* [Rig environment presets](https://docs.amika.dev/reference/presets.md)


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