Skip to main content
amika rig manages hosted rigs. The retired --local flag is not supported. Use the open-source amika-server directly when developing its Docker-backed implementation. 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:
Pass a local path or Git URL to select a different repository:
Pass --no-git to create a rig without a repository:
Hosted rigs clone from the remote repository. Local modifications are not uploaded. Push the branch, configuration, and scripts before creating the rig:
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 and the config.toml reference.

​
Create-time overrides

Use CLI flags for one-off overrides:
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:
Select credentials during creation:
You can also set repository defaults under [agent_credentials]. See Inject credentials.

​
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. Do not bind repository services or setup-script processes to this range.