# Configuration

Use this reference when changing `~/.code-container/settings.json`, `~/.code-container/Dockerfile.User`, enabled packs, runtime flags, mounts, or persisted harness and tool configurations.

## Storage

Container owns this host-side structure:

```text
~/.code-container/
├── archive/              # Archived V2 files
├── configs/              # Persisted harness and tool configs mounted into containers
├── Dockerfile.User       # User-owned final image layer
├── settings.json         # Primary configuration
└── temp/                 # Generated Dockerfiles and internal state; do not edit
```

Only modify `settings.json`, `Dockerfile.User`, and requested files under `configs/`. Preserve unknown settings keys and omitted defaults. Do not edit migration, onboarding, or TOS version fields.

## Settings Schema

Supported user-facing top-level keys:

- `enabledHarnesses`: Array of harness pack IDs.
- `enabledTools`: Array of tool pack IDs.
- `runtime`: `"docker"` or `"podman"`.
- `systemMounts`: Object with optional Boolean `ssh`.
- `dockerRunFlags`: Array of individual arguments passed during container creation.
- `dockerExecFlags`: Array of individual arguments passed when opening an interactive session.
- `dockerfileCore`: Advanced base-stage configuration.

Internal keys that must not be edited:

- `migrationVersion`
- `onboardingVersion`
- `tosVersion`

Container validates the complete JSON document. Preserve the existing object and change only requested values. Flags must be separate array entries:

```json
{
  "dockerRunFlags": ["-p", "8080:80"],
  "dockerExecFlags": ["-e", "FOO=bar"]
}
```

Do not combine a flag and value into one entry such as `"-p 8080:80"`.

## Dockerfile Core

All `dockerfileCore` fields are optional:

```json
{
  "dockerfileCore": {
    "baseImage": "ubuntu:24.04",
    "workdir": "/root",
    "cmd": "[\"/bin/bash\"]",
    "promptCommand": "RUN echo 'custom prompt' >> /root/.bashrc",
    "disableDefaultCommands": false,
    "customCommands": [
      "RUN apt-get update && apt-get install -y postgresql-client",
      "ENV MY_VAR=hello"
    ]
  }
}
```

Use this only when changing the base image or when commands must run before tool and harness installation. Run `container build full` after any change. Direct file edits do not reliably create a core dirty-state prompt.

## User Dockerfile

Prefer `~/.code-container/Dockerfile.User` for ordinary package installation and final-layer customization. Preserve existing instructions and this required base as the first Dockerfile instruction:

```dockerfile
FROM localhost/aerovato/container-v3-harness:latest
```

Example:

```dockerfile
RUN apt-get update && apt-get install -y postgresql-client
RUN npm install -g bun
RUN pip install requests
```

Run `container build user` afterward. User Dockerfile changes are not tracked automatically.

## Harness Packs

Current harness IDs:

- `claude`: Claude Code
- `opencode`: OpenCode V2 (default; installs via `https://opencode.ai/v2/install`)
- `opencode-v1`: OpenCode V1 (legacy npm installation; manual selection only)
- `codex`: OpenAI Codex
- `pi`: Pi
- `gemini`: Gemini CLI
- `copilot`: GitHub Copilot CLI
- `grok`: Grok Build
- `cursor`: Cursor CLI
- `nitro`: Aerovato Nitro
- `antigravity`: Antigravity CLI

After changing `enabledHarnesses`, run `container build harness`. Newly enabled harness config mounts require recreation of existing project containers.

## Tool Packs

Current tool IDs:

- `python`
- `bun`
- `enhanced-tools`
- `agents-directory`
- `npm-config`
- `git-config`
- `vim-config`
- `deno`
- `rust`
- `go`
- `uv`
- `gh`
- `aws`
- `gcloud`
- `azure`
- `neovim`

Onboarding detects tools and writes an explicit selection. When `enabledTools` is absent at build or mount time, no tool packs are implicitly applied.

After changing `enabledTools`, run `container build tools`. Newly enabled tool config mounts require recreation of existing project containers.

The `agents-directory` pack copies or prepares host `~/.agents` under `~/.code-container/configs/.agents` and mounts that persisted copy at `/root/.agents`. It does not live-sync later host changes. A globally installed skill added to host `~/.agents/skills` after onboarding may need to be installed or copied into Container's persisted `.agents` config separately.

## Mounts And Configs

`systemMounts.ssh` controls the read-only host `~/.ssh` mount. Default behavior is disabled when the key is absent.

Git configuration is supplied by the `git-config` tool pack, not by `systemMounts`.

Harness and tool config sources live under `~/.code-container/configs/` and are mounted read-write at pack-specific destinations. Edit these persisted copies when changing behavior inside managed containers. Do not edit the normal host harness config and expect an existing persisted copy to update automatically.

For a custom bind mount, add correctly separated runtime arguments to `dockerRunFlags`, for example:

```json
{
  "dockerRunFlags": [
    "--mount",
    "type=bind,source=/host/path,target=/container/path"
  ]
}
```

Only mount resources the user explicitly approves. Never mount the complete host `~/.code-container/` directory.

Mounts and `dockerRunFlags` apply at container creation. `dockerExecFlags` apply when attaching. Existing containers must be removed and recreated before creation-time changes take effect; obtain explicit approval first.

## Build Selection

Container builds four stages in order: Core, Tools, Harness, and User.

- `container build full`: Core through User.
- `container build tools`: Tools through User.
- `container build harness`: Harness and User.
- `container build user`: User only.

Use the narrowest target that begins at or before the changed stage. Runtime selection, flags, mount settings, and mounted config content do not themselves require an image rebuild.

# V2 To V3 Migration

Runtime setup archives V2 files but does not migrate their content. Perform content migration only with user approval.

## Detection

Inspect `~/.code-container/archive/` for:

- `MOUNTS.txt`
- `DOCKER_FLAGS.txt`
- `DOCKER_RUN_FLAGS.txt`
- `Dockerfile.Packages`
- An old `Dockerfile.User`

If none exist, no V2 content migration is needed. Read [configuration](configuration.md) before editing current files.

Skip an item when its equivalent is already present in the V3 configuration. This indicates that it may already have been migrated. Stop and ask the user whenever intent or equivalence is ambiguous.

## Runtime Flags

V2 `DOCKER_FLAGS.txt` applied to both `docker run` and `docker exec`. Add its individual arguments to both `dockerRunFlags` and `dockerExecFlags`.

V2 `DOCKER_RUN_FLAGS.txt` applied only to `docker run`. Add its individual arguments to `dockerRunFlags`.

Preserve existing arguments, split flags and values into separate array entries, and deduplicate exact equivalents.

## Mounts

Convert each `MOUNTS.txt` entry according to its purpose:

- Host SSH mount: set `systemMounts.ssh` to `true`.
- Git configuration: enable the `git-config` tool pack.
- Other mounts: append separated `--mount` or `-v` arguments to `dockerRunFlags`.

Never translate a mount into access to the complete host `~/.code-container/` directory. Confirm sensitive or broad host mounts with the user.

## Dockerfile Packages

Ignore the archived base `FROM` instruction and migrate subsequent instructions through the appropriate V3 layer:

- Ordinary user packages and final setup: append to `~/.code-container/Dockerfile.User`.
- Base-image changes or commands that must precede tools and harnesses: append to `dockerfileCore.customCommands`.

Preserve this required base as the first instruction in the current user Dockerfile:

```dockerfile
FROM localhost/aerovato/container-v3-harness:latest
```

Do not duplicate instructions already present.

## Old User Dockerfile

An archived user Dockerfile is from V2 when it does not use the V3 harness base. Read both old and current files, then append only the still-relevant instructions after the current V3 base. Do not restore the old `FROM` line.

## Completion

Validate `settings.json` as JSON and review the resulting Dockerfile before building.

- Any `dockerfileCore` migration: `container build full`
- Tool selection only: `container build tools`
- Harness selection only: `container build harness`
- User Dockerfile only: `container build user`

Creation-time flag and mount migrations also require project containers to be recreated. Obtain explicit approval before removing an existing container.

# Harness Permissions

Use these settings only when the user explicitly asks to reduce or remove harness approval prompts inside managed containers.

Full harness permissions allow an agent to modify or delete the mounted project and any writable mounted configuration. Optional credentials such as SSH or cloud configs may also be accessible. Explain this risk before changing permissions.

Modify only the persisted files under `~/.code-container/configs/`. Do not change the normal host harness configurations for this task.

## OpenCode

File: `~/.code-container/configs/.opencode/opencode.json`

Merge this property into the existing JSON object:

```json
{
  "permission": "allow"
}
```

## OpenAI Codex

File: `~/.code-container/configs/.codex/config.toml`

Set:

```toml
approval_policy = "never"
sandbox_mode = "danger-full-access"
```

Preserve unrelated TOML configuration and avoid duplicate keys.

## Claude Code

File: `~/.code-container/configs/.claude/settings.json`

Merge these properties into the existing JSON object:

```json
{
  "permissions": {
    "allow": ["*", "Bash"]
  }
}
```

Preserve other permission settings unless the user asks to replace them.

## Gemini CLI

File: `~/.code-container/configs/.gemini/policies/rules.toml`

Create the parent directory when needed and add:

```toml
[[rule]]
toolName = ["run_shell_command", "write_file", "replace"]
decision = "allow"
priority = 777
```

Preserve existing rules.

## Applying Changes

These files are bind-mounted, so edits normally become visible without an image rebuild. If the relevant harness was newly enabled after the project container was created, rebuild the harness image and recreate that project container with explicit approval.

# Troubleshooting

Start with documentation, current configuration, and non-interactive diagnostics. Inspect source only when those do not explain the behavior.

## Safe Diagnostics

Confirm the installed CLI and available commands:

```bash
container --version
container --help
container list
```

Do not run `container`, `container run`, or `container attach` through a non-interactive agent command. They open an interactive shell.

Check the configured runtime in `~/.code-container/settings.json`, then use its normal status command when needed:

```bash
docker info
podman info
```

Run only the relevant command. Runtime startup may require the user to open Docker Desktop or start the Podman service.

## Configuration Failures

For settings load failures:

1. Parse `~/.code-container/settings.json` as JSON.
2. Check keys and value types against [configuration](configuration.md).
3. Remove comments and trailing commas.
4. Preserve unknown valid data while correcting only the invalid field.
5. Never repair internal version values by guessing.

Generated files under `~/.code-container/temp/` are not configuration sources. Fix settings or the user Dockerfile and regenerate through an appropriate build.

## Build Failures

Identify the first failing stage and command. Use the narrowest target that includes the changed stage:

- Core failure: `container build full`
- Tools failure: `container build tools`
- Harness failure: `container build harness`
- User Dockerfile failure: `container build user`

Do not repeatedly broaden the build without understanding the first error. Check network access, package repository availability, runtime readiness, and Dockerfile syntax. User Dockerfile changes and direct core edits do not reliably produce automatic stale-build prompts.

## Changes Not Appearing

Use these distinctions:

- Image content changed: rebuild from the affected stage.
- Persisted config content changed: bind mounts normally expose it immediately.
- Enabled pack changed: rebuild and recreate existing project containers so their mount set is regenerated.
- `dockerRunFlags` or mounts changed: recreate existing project containers.
- `dockerExecFlags` changed: the next interactive attachment uses them.
- Runtime changed: containers belonging to the old runtime are not automatically moved.

Removing a project container discards container-local state. Ask for explicit approval and explain the impact before `container remove` or equivalent runtime commands.

## Skill Availability Inside Managed Containers

A host-side global skill installation does not guarantee availability inside managed containers.

- Claude Code primarily uses `.claude/skills/`.
- Codex, OpenCode, Gemini CLI, GitHub Copilot, and several other agents support `.agents/skills/`.
- The `agents-directory` tool pack mounts `~/.code-container/configs/.agents`, not the live host `~/.agents` directory.
- Installing a skill into host `~/.agents/skills/` after onboarding does not automatically update the persisted copy.
- Project-local skills travel with the mounted project only when stored in a location recognized by the selected harness.

Do not solve discovery by mounting the complete host `~/.code-container/`. If automatic provisioning is required, explain that it is a separate Container product and security decision.

## Last-Resort Source Inspection

Use source inspection only after documented behavior, current files, and runtime output are insufficient.

1. Record `container --version` and the exact observed behavior.
2. Ask the user before network access or cloning.
3. Clone `https://github.com/aerovato/container` into a temporary location outside the user's project.
4. Prefer the release tag matching the installed version, commonly `v<version>`.
5. If no matching tag exists, state that limitation before inspecting `main`.
6. Treat the clone as read-only unless the user explicitly approves contribution work.
7. Inspect the smallest relevant source path and its tests.
8. Do not run release workflows, standalone binary compilation, or interactive Container sessions.
9. Compare source behavior with the installed version and report file references and concrete evidence.
10. Remove the temporary clone afterward only when that cleanup was included in the user's approval.

Useful source areas include:

- `src/types.ts`: Settings and state schemas.
- `src/container.ts`: Mount generation and container execution.
- `src/docker.ts`: Build stages and dirty-state clearing.
- `src/harness-packs.ts`: Harness IDs, installation, and config mounts.
- `src/tool-packs.ts`: Tool IDs, installation, and config mounts.
- `src/onboarding.ts`: Detection, config copying, and setup behavior.
- `src/platform/`: Platform-specific paths, filesystems, and runtime startup.
- `tests/`: Expected behavior and regressions.

If the evidence shows a reproducible bug or a clear, logical, non-breaking improvement, explain:

- Expected behavior.
- Actual behavior.
- Reproduction steps.
- Relevant source and tests.
- The smallest likely correction.

Then ask whether the user wants help contributing to `aerovato/container`. Do not create an issue, fork, branch, commit, or pull request without explicit approval.

# Windows Support

Aerovato Container runs natively on Windows alongside Linux, macOS, and WSL.

## Requirements

- Windows 10 or 11, or WSL2
- Docker Desktop for Windows or Podman

No extra compatibility layer is required for native Windows. Container detects supported runtimes, harnesses, and tools during onboarding.

## Config Paths

Harness and tool definitions use POSIX-style paths such as `~/.config/opencode`. Container expands these against the Windows home directory.

When a Windows application stores configuration elsewhere, such as `%APPDATA%`, automatic migration may not find it. Copy the required configuration into the corresponding location under `~/.code-container/configs/` only with user approval.

## Project Paths

UNC project paths such as `\\server\share\project` are not supported.

Container canonicalizes Windows drive paths so native Windows and WSL access to the same project resolve to the same managed container.

## WSL

When invoked inside WSL, Container follows Linux behavior. Use paths visible to the selected runtime and avoid mixing inaccessible Windows and WSL mount sources.