# Set Up Amika Repository Configuration
You are tasked with setting up an Amika sandbox configuration for this repository. Amika is infrastructure for building a software factory — it spins up sandboxed development environments pre-loaded with coding agents and your repository code. Your job is to create a `.amika/config.toml` and a setup script so that when a sandbox is created from this repo, it has all dependencies installed and dev services running.
## Reference materials
Before you begin, read these resources to understand how Amika configuration works:
1. **Amika docs — sandbox configuration**: https://docs.amika.dev/reference/sandbox-configuration
2. **Amika docs — services**: https://docs.amika.dev/reference/services
3. **Amika docs — presets**: https://docs.amika.dev/reference/presets
4. **Example config (simple repo)**: https://github.com/gofixpoint/example-repo/blob/main/.amika/config.toml
5. **Example config (Go project)**: https://github.com/gofixpoint/amika/blob/main/.amika/config.toml
If you are unable to fetch these URLs, the key facts are summarized below in the "Amika Configuration Reference" section.
## Step 1: Investigate the repository
Analyze this repository thoroughly before doing anything else. You need to understand:
### Languages and runtimes
- What programming languages are used? (Check file extensions, config files, lock files)
- What versions are required? (Check `.nvmrc`, `go.mod`, `pyproject.toml`, `Gemfile`, `rust-toolchain.toml`, etc.)
- What package managers are used? (npm, pnpm, yarn, pip, cargo, go modules, etc.)
### Dev servers and services
- What services does this project run in development? (web servers, API servers, databases, queues, etc.)
- What ports do they listen on? (Check `package.json` scripts, Dockerfiles, docker-compose files, config files, source code for port defaults, CLI flag defaults)
- How are services started? (e.g., `pnpm dev`, `go run ./cmd/server`, `cargo run`, `python manage.py runserver`)
- Is there an existing Procfile, docker-compose.yml, or similar orchestration config?
### Environment variables and secrets
- What environment variables does the project use? (Check `.env.example`, `.env.sample`, source code for `os.Getenv`, `process.env`, etc.)
- Which are required vs optional?
- Which contain secrets (API keys, database passwords, encryption keys)?
- What are sensible defaults for development?
### Build steps
- Are there compilation steps? (Go build, Rust build, TypeScript compilation, etc.)
- Are there code generation steps? (protobuf, GraphQL codegen, etc.)
- What install commands are needed? (`pnpm install`, `pip install`, `go mod download`, etc.)
### Existing configuration
- Is there already a `.amika/` directory? If so, read it and ask the user whether they want to update it or start fresh.
- Look at `CLAUDE.md`, `README.md`, `CONTRIBUTING.md`, `Makefile`, or similar files for development setup instructions.
## Step 2: Ask the user to confirm your findings
After investigating, present your findings to the user and ask them to confirm or correct. Structure your questions like this:
### Sandbox settings
Explain the available sandbox presets and sizes, and recommend values:
**Presets:**
- **`coder`** (default) — Ubuntu 24.04 with Git, curl, zsh, build essentials, Python, Node.js 22, pnpm, TypeScript, tsx. Includes Claude Code, Codex, and OpenCode agent CLIs.
- **`coder-dind`** — Everything in `coder`, plus Docker-in-Docker (dind) support for running containerized services inside the sandbox.
Recommend `coder` unless the project uses Docker Compose, runs containerized services locally, or otherwise requires Docker.
**Sizes:**
- **`xs`** — Extra-small resource allocation. Suitable for lightweight tasks like documentation or simple scripts.
- **`m`** (default) — Medium resource allocation. Suitable for most projects.
- **`l`** — Large resource allocation. For heavier builds or multiple concurrent services.
- **`xl`** — Extra-large resource allocation. For the most demanding workloads.
These values are set in the `[sandbox]` section of `.amika/config.toml` and used as defaults when creating a sandbox from this repository. They can be overridden at creation time via CLI flags or the web UI.
### Services
List the services you discovered and the ports they use. Ask the user:
- Which of these services should be exposed in the sandbox?
- Are there any services you missed?
- For each service, confirm the port and whether it should have an HTTP/HTTPS URL scheme.
### Missing runtimes
Based on the preset's pre-installed tools (Git, GitHub CLI (`gh`), curl, zsh, build essentials, Python, Node.js 22, pnpm, TypeScript, tsx), identify what's missing that the setup script will need to install. For example:
- Go (not included in any preset)
- Rust (not included in any preset)
- Java/JVM (not included in any preset)
- Specific Node.js versions if the project requires something other than 22
- Any other system dependencies
### Environment variables
Present the environment variables you found, categorized as:
- **Required secrets** — values the user must provide via `amika secret push` or the web UI before creating a sandbox
- **Required config** — values that need to be set but aren't secret (e.g., database host pointing to a shared dev instance)
- **Optional/feature flags** — values with sensible defaults
Ask the user:
- Are any required env vars missing from your list?
- For database/service connection strings, should these point to a shared dev instance, or will they run locally in the sandbox?
- Are there any secrets they want to pre-configure?
### Dev server startup
Explain your plan for how the setup script will start services. Ask:
- Should all discovered services start automatically, or just some?
- Are there any dependencies between services (e.g., the API server must start before the frontend)?
- Are there database migrations that need to run?
## Step 3: Create the configuration
After the user confirms, create the following files:
### `.amika/config.toml`
This is the main configuration file. The sections you'll typically generate:
```toml
[sandbox]
preset = "coder" # "coder" or "coder-dind"
size = "m" # "xs", "m", "l", or "xl"
[lifecycle]
setup_script = ".amika/scripts/setup.sh"
start_script = ".amika/scripts/start.sh" # optional, runs on each restart
[services.<name>]
port = <port_number>
url_scheme = "https" # or "http", or omit for non-HTTP services like gRPC
[env]
PLAIN_VAR = "value"
SECRET_VAR = { secret = "secret-name" }
```
**Rules:**
- `preset` selects the base image: `"coder"` (default) or `"coder-dind"` (adds Docker-in-Docker). Use `coder-dind` only if the project requires Docker.
- `size` sets the resource allocation: `"xs"`, `"m"` (default), `"l"`, or `"xl"`. Use `xs` only for lightweight tasks; reach for `l`/`xl` for heavy builds or many concurrent services.
- `setup_script` is a path relative to the repo root pointing to an executable script that runs once when a new sandbox is created, before the agent starts.
- `start_script` (optional) is an executable script that runs each time a stopped sandbox is started again — not on the initial create, where only `setup_script` runs. Put one-time provisioning in `setup_script`; use `start_script` for steps that must repeat whenever a sandbox resumes.
- Services expose ports from the sandbox. Each service has a name, port, and optional `url_scheme`. Only set `url_scheme` for HTTP/HTTPS services — omit it for raw TCP services like gRPC.
- Ports 60899–60999 are reserved by Amika — do not use them.
- Environment variables can be plain strings or secret references. Secrets must be pushed via `amika secret push` or the Amika web UI before sandbox creation. Use `{ secret = "name" }` syntax for secrets.
### `.amika/scripts/setup.sh`
This script runs inside the sandbox before the agent starts. It must:
1. Be executable (`chmod +x`)
2. Use `$AMIKA_AGENT_CWD` to reference the repo root (do NOT hardcode paths)
3. Exit 0 on success (non-zero aborts sandbox startup)
4. Be deterministic and idempotent
**Structure the setup script in phases:**
```bash
#!/usr/bin/env bash
set -euo pipefail
# --- Phase 1: Install missing system dependencies ---
# Check what's already installed before installing anything.
# The preset already includes: Git, GitHub CLI (gh), curl, zsh,
# build essentials, Python, Node.js 22, pnpm, TypeScript, tsx.
# Only install what's missing (e.g., Go, Rust, specific tools).
# Run independent installs in parallel with & and wait.
# --- Phase 2: Install project dependencies ---
# e.g., pnpm install, pip install -r requirements.txt, go mod download
# --- Phase 3: Build/compile if necessary ---
# e.g., go build, cargo build, tsc
# --- Phase 4: Start services in the background ---
# Use nohup and & to background services.
# Write PID files to /tmp/amika-<service>.pid for cleanup.
# Write logs to /var/log/amika/<service>.log (mkdir -p first).
# If services have startup dependencies, add brief sleeps between them.
```
**Where to start services:** the setup script runs once, on create; the start script runs each time a stopped sandbox is restarted, but not on the initial create. Start services in the setup script so they come up on a fresh sandbox. If the project will be stopped and resumed, repeat that service startup (Phase 4) in the start script so the services come back. Keep one-time install/build steps (Phases 1–3) in the setup script only.
**Best practices for setup scripts:**
- Always check if a tool is installed before installing it (`command -v <tool> &>/dev/null`).
- Use architecture detection to handle both amd64 and arm64.
- Run independent installs in parallel using `&` and `wait`.
- For version checks, compare against the minimum required version rather than requiring an exact match.
- Use `curl -fsSL` for downloads (fail silently on HTTP errors, show errors on other failures).
- Install binaries to `/usr/local/bin/` using `sudo`.
- Use `nohup <command> > /var/log/amika/<name>.log 2>&1 &` to start background services.
- Add `mkdir -p /var/log/amika` before starting services.
- Print clear status messages so the user can see progress.
### `.amika/scripts/start.sh`
Only generate this if you set `start_script` in `config.toml`. It runs each time a stopped sandbox is resumed — not on the initial create — so it must bring services back up after a restart. It has the same requirements as the setup script: executable (`chmod +x`), use `$AMIKA_AGENT_CWD` for the repo root, exit 0 on success.
Because `setup_script` runs on create and `start_script` runs on resume, **service startup must happen in both**. Factor the service-startup logic (Phase 4) into a shared script that each one sources, rather than duplicating it:
```bash
#!/usr/bin/env bash
set -euo pipefail
# Bring services back up after a resume. This sources the same helper
# the setup script uses for Phase 4 so the two stay in sync.
"$AMIKA_AGENT_CWD/.amika/scripts/start-services.sh"
```
Then have `setup.sh` Phase 4 call the same `start-services.sh`. Keep one-time install/build steps (Phases 1–3) in `setup.sh` only.
## Step 4: Verify the configuration
After creating the files, verify:
1. The setup script is executable (`chmod +x .amika/scripts/setup.sh`)
2. If `start_script` is set in config.toml, that script exists and is executable, and any shared service-startup helper it references exists and is executable
3. The config.toml is valid TOML (no syntax errors)
4. All ports in config.toml match what the scripts start
5. All environment variables referenced by the services are defined in the `[env]` section
6. Secret references use the `{ secret = "name" }` syntax
7. No ports fall in the reserved range 60899–60999
Tell the user what secrets they need to push before creating a sandbox:
```bash
amika secret push <SECRET_NAME>=<value>
```
And how to create a sandbox with this config (run from inside the repo; the repo is auto-detected from the current directory):
```bash
amika sandbox create
```
---
## Amika Configuration Reference
This section summarizes the key configuration details in case you cannot fetch the documentation URLs above.
### config.toml structure
The file lives at `.amika/config.toml` in the repository root.
**`[sandbox]`** — Default sandbox settings for the repository.
- `preset` (string, default `"coder"`): The base image to use. Allowed values: `"coder"`, `"coder-dind"`.
- `size` (string, default `"m"`): Resource allocation. Allowed values: `"xs"` (extra-small), `"m"` (medium), `"l"` (large), `"xl"` (extra-large).
These values are used as defaults when creating a sandbox from this repository. They can be overridden at creation time via CLI flags or the web UI.
**`[lifecycle]`** — Sandbox lifecycle hooks.
- `setup_script` (string): Path to a setup script relative to the repo root. The script runs once before the agent starts. It must be executable and exit 0 on success.
- `start_script` (string, optional): Path to an executable script that runs each time a stopped sandbox is restarted — not on the initial create, where only `setup_script` runs. Use it to bring services back up when a sandbox resumes.
**`[filesystem]`** — Additional repos to clone alongside the primary repo.
- `repos` (list of strings): GitHub repo URLs to clone into the sandbox at `~/workspace/<repo-name>`. The primary repo is inferred automatically and need not be listed. Only set this if the project spans multiple repositories.
**`[services.<name>]`** — Named services with port mappings.
- `port` (integer or string): Single port binding. Integer defaults to TCP. String allows protocol: `"4838/tcp"` or `"4982/udp"`.
- `ports` (list): Multiple port bindings. Mutually exclusive with `port`.
- `url_scheme` (string or list): URL generation. Accepts `"http"` or `"https"`. For multi-port services, use a list of `{ port = N, scheme = "https" }` tables. Only ports listed in `url_scheme` get generated URLs.
**`[env]`** — Environment variables injected into the sandbox.
- Plain values: `DATABASE_HOST = "localhost"`
- Secret references: `API_KEY = { secret = "my-api-key" }` — the secret must be pushed to the remote store before sandbox creation.
- Service references: `WEB_URL = { service = "web", field = "url" }` — injects another service's generated `url`, its `host`, or published `port`. `field` is `"url"`, `"host"`, or `"port"`; `"url"` and `"host"` require that service to have a `url_scheme`.
### Presets
Presets are pre-built Docker images for sandboxes. Set via the `[sandbox]` section in config.toml or overridden at creation time with `--preset`.
| Preset | Image | Description | Pre-installed tools |
|--------|-------|-------------|---------------------|
| `coder` (default) | `amika/coder:latest` | Standard dev environment with Claude Code, Codex, and OpenCode agent CLIs | Ubuntu 24.04, Git, GitHub CLI (`gh`), curl, zsh, build essentials, Python, Node.js 22, pnpm, TypeScript, tsx |
| `coder-dind` | `amika/coder-dind:latest` | Same as `coder`, plus Docker-in-Docker support for running containerized services | Same as coder + Docker |
### Setup script environment
- `$AMIKA_AGENT_CWD` — the path to the cloned repository inside the sandbox (typically `/home/amika/workspace/<repo-name>`)
- Credentials for coding agents are auto-mounted from the host
- The script runs as the `amika` user with `sudo` access
- If the script exits non-zero, the sandbox does not start
### Reserved ports
Ports 60899–60999 are reserved for Amika internal services. Do not bind to them.
### Sandbox creation
```bash
# Clone current repo into a sandbox (auto-detected from cwd; uses preset and size from config.toml).
# To target a different repo, pass a path or git URL: amika sandbox create --git <path-or-url>
amika sandbox create
# Override preset at creation time
amika sandbox create --preset coder-dind
# Include uncommitted/untracked files (local sandboxes only)
amika sandbox create --no-clean
# Clone a specific branch
amika sandbox create --branch my-branch
# List running services
amika service list
```
### Secrets
```bash
# Push a secret (for use in config.toml { secret = "name" } references).
# The KEY is the secret name referenced from config.toml.
amika secret push MY_SECRET=secret-value
# Push multiple at once, or load from a .env file
amika secret push API_KEY=abc DB_PASSWORD=xyz
amika secret push --from-file=.env
# Push Claude Code credentials
amika secret claude push --type oauth
amika secret claude push --type api_key --value sk-ant-xxx
```
