Documentation

• 1: Contributing
• 1.1: Maintenance
• 1.2: E2E Test Catalogue
• 1.3: Version-line porting
• 1.4: V1 adoption pilots
• 2: Overview
• 3: Skills (via processkit)
• 4: Getting Started
• 4.1: Installation
• 4.2: New Project
• 4.3: Existing Project
• 5: Container
• 5.1: Base Image
• 5.2: Container Configuration
• 5.3: Audio Support
• 5.4: File Preview
• 5.5: Runtime Operations
• 6: Tutorials
• 6.1: Create a local project with processkit
• 7: Addons
• 7.1: Overview
• 7.2: Language Runtimes
• 7.3: Tool Bundles
• 7.4: Documentation Frameworks
• 7.5: LaTeX Build and Preview
• 8: AI Providers
• 8.1: Claude
• 8.2: Aider
• 8.3: Gemini
• 8.4: Mistral
• 8.5: OpenAI (Codex CLI)
• 8.6: Copilot (GitHub)
• 8.7: Continue
• 9: Project Context
• 9.1: Context Overview
• 9.2: Skill Selection
• 9.3: Migration
• 10: Migrations
• 10.1:
• 10.2:
• 10.3:
• 11: Customization
• 11.1: Prompt Presets
• 11.2: Custom Themes
• 11.3: Layouts
• 11.4: Custom Prompts
• 11.5: Color Themes
• 12: Reference
• 12.1: CLI Commands
• 12.2: Configuration
• 12.3: Local Config (.aibox-local.toml)
• 12.4: Cheatsheet
• 12.5:
• 12.6: V1 support, deprecation, and retirement
• 12.7: Compatibility
• 12.8:
• 13: Roadmap

1 - Contributing

Contributing

Thank you for your interest in contributing to aibox!

Getting Started

1. Fork and clone the repository:

   git clone https://github.com/projectious-work/aibox.git
   cd aibox
   

2. Start the development container:

   cd .devcontainer
   docker compose up -d
   docker compose exec aibox bash
   

   Or open in VS Code with the Dev Containers extension.

3. Build the CLI:

   cd cli
   cargo build
   

4. Run the tests:

   cargo test
   cargo clippy -- -D warnings
   cargo fmt -- --check
   

Project Structure

• cli/ — Rust CLI source code
• images/ — Published container image Dockerfiles
• addons/ — Addon definitions (language runtimes, tool bundles, AI agents)
• docs-site/ — Hugo/Docsy documentation source
• .devcontainer/ — This project’s own dev environment

Process content (skills, packages, primitives, processes, the canonical AGENTS.md) lives in processkit, not in this repository. As of v0.16.0 aibox no longer ships a templates/ directory or a schemas/ directory — both have moved upstream to processkit.

See CLAUDE.md for detailed architecture notes.

Development Workflow

CLI Changes

1. Make your changes in cli/src/
2. Run cargo test to verify all tests pass
3. Run cargo clippy -- -D warnings for lint checks
4. Run cargo fmt to format code

Image Changes

1. Edit the relevant Dockerfile in images/
2. Build locally to verify: docker build -t aibox-test images/<flavor>/
3. Test that derived images still build if you changed the base

Documentation Changes

1. Edit or add pages in docs-site/docs/
2. Update docs-site/sidebars.js if adding new pages
3. Preview locally: ./scripts/maintain.sh docs-serve

Pull Requests

• Keep PRs focused on a single change
• Include a clear description of what and why
• Ensure all tests pass and clippy is clean
• Update documentation if your change affects user-facing behavior

Reporting Issues

File issues at github.com/projectious-work/aibox/issues.

When filing an issue, please:

• Use a descriptive title
• Label it: bug for broken behavior, enhancement for feature requests, documentation for doc gaps
• Include steps to reproduce (for bugs) or a use case description (for enhancements)
• Mention the aibox version (aibox --version) and container image flavor if relevant

1.1 - Maintenance

Maintenance

Internal procedures for building, testing, documenting, and releasing aibox. The canonical step-by-step release note remains in context/notes/; this page is the public contributor summary.

Development Checks

cd cli && cargo fmt -- --check
cd cli && cargo clippy --all-targets -- -D warnings
cd cli && cargo test

The helper script wraps the same checks:

./scripts/maintain.sh test

Documentation Site

The public docs live in docs-site/ and use Hugo with the Docsy theme.

git submodule update --init --recursive docs-site/themes/docsy
npm --prefix docs-site ci
./scripts/maintain.sh docs-serve
./scripts/build-docs.sh

./scripts/build-docs.sh is the local verification build. It writes the static site to docs-site/public/ and prints Hugo render warnings.

The maintenance script also exposes:

./scripts/maintain.sh docs-serve
./scripts/maintain.sh docs-deploy --dry-run
./scripts/maintain.sh docs-deploy

docs-deploy builds the site and pushes the static output to the gh-pages branch from the local checkout. It does not use GitHub Actions. Use --dry-run to validate the production build without pushing; use the command without that flag only when the current checkout is the source that should be published. The release script runs the same deployment as part of the container-side release phase.

Use the repository maintenance command for publication rather than npm run deploy. The maintenance command preserves the project’s local-only release flow, publishes the already configured /aibox/ site, and ensures GitHub Pages serves the gh-pages branch.

Published Image

aibox publishes the base Debian image used by generated downstream projects:

./scripts/maintain.sh build-images
./scripts/maintain.sh build-images --no-cache
./scripts/maintain.sh push-images X.Y.Z

Generated project images are built per project by aibox apply. They are not published from this repository.

Release Boundary

Releases are intentionally split:

Both phases run locally. The project deliberately does not use GitHub Actions for release validation, artifact builds, image publication, or deployment. Release speed comes from bounded local concurrency, persistent caches, and reuse of evidence for the exact release commit rather than from moving gates to a hosted runner.

Version-line branches

Long-lived branches are protected: direct pushes, force-pushes, and deletion are disabled; changes arrive through pull requests with resolved conversations. No GitHub Actions or required hosted checks are used.

main is the published-history branch. After a tag is cut on its designated release branch, merge that branch into main through a pull request. Apply or verify the policy from an administrator checkout with:

./scripts/configure-branch-protection.sh

Do not create GitHub releases by hand with gh release create. The release script attaches binaries and writes the release notes expected by users.

Container-Side Release

./scripts/maintain.sh release X.Y.Z

This command requires a clean working tree. It may stop after sync-processkit if a newer processkit release changes the pinned default and the CLI needs review before release.

The command performs:

• dependency, addon, image, and harness state report in dist/RELEASE-STATE.md
• processkit and host-context aibox doctor runs in dist/RELEASE-DOCTORS.md; doctor errors block the release and warnings remain visible for review
• processkit release sync check
• cli/Cargo.toml and Cargo.lock version bump when needed
• format, Clippy, and test checks
• tracked release-notes/vX.Y.Z.md, compatibility-matrix, README, contributor guidance, and Hugo/Docsy production-build validation
• Tier 2 SSH companion E2E tests, including generated runtime and visual asciinema probes
• cargo audit
• cargo update --dry-run review for lockfile-resolvable crate updates
• Linux release builds for aarch64-unknown-linux-gnu and x86_64-unknown-linux-gnu
• binary version smoke check
• annotated git tag push
• GitHub release creation with Linux binaries
• Hugo/Docsy docs deployment
• dist/RELEASE-PROMPT.md for host-side completion

Independent validation gates run concurrently. The default worker limit is two; set AIBOX_RELEASE_PARALLELISM to a positive integer that fits the local machine. Linux release targets build concurrently inside the build gate, and the version smoke reuses the matching release artifact instead of compiling a third binary.

Successful gates write local evidence under dist/release-evidence/vX.Y.Z/<commit>/. Evidence is bound to the exact commit, Rust toolchain, clean-tree state, release phase, and gate-specific environment. Companion evidence includes the companion fingerprint, audit evidence expires daily, and binary evidence rechecks archive checksums. Set AIBOX_RELEASE_REUSE_EVIDENCE=0 to force every selected gate to run again. Container-side timings are written to dist/RELEASE-TIMINGS.md.

The docs-check gate is mandatory whenever a tag or GitHub release is selected. It runs before publication, so missing release notes, stale compatibility metadata, incomplete v1 branch guidance, or a broken Hugo build cannot leave a published release with incomplete documentation. The later docs step deploys exactly that candidate’s site.

Run ./scripts/maintain.sh release-check-state standalone when you want the dependency and tool-state report without bumping, tagging, or building. Run ./scripts/maintain.sh release-doctors for the matching diagnostic report.

If a report finding is deferred, create a processkit WorkItem before continuing the release and mention that WorkItem ID in the release notes or handover. For cargo update --dry-run, either apply available crate updates in the release with full validation, or create a WorkItem for the deferred crate-update pass.

Host-Side Release

Run this on the macOS host after the container-side release succeeds. Sync the matching version-line release branch first; the container-side release may have pushed tag-prep commits from another clone. For a v0 release:

git fetch origin v0.x-release
git switch v0.x-release
git reset --keep origin/v0.x-release
./scripts/maintain.sh release-host X.Y.Z

release-host derives the protected release branch from the version: v0.x-release for v0, v1.x-pre-release for v1 prereleases, and v1.x-release for v1 GA. It fetches only that branch and the requested tag, then verifies that the tag is reachable from the branch before building.

This phase builds Darwin binaries, uploads them to the existing GitHub release, pushes GHCR images, then runs a fresh downstream-style runtime smoke against the pushed release tag. The smoke creates a temporary project, runs aibox init and aibox apply --no-cache --standardize-config, starts the generated container, probes Yazi, the aibox status helper, tmux state, and the diagnostics sidecar, and writes a bundle to dist/release-smoke/vX.Y.Z/<timestamp>/. By default, this smoke runs with AIBOX_RELEASE_SMOKE_TIER=addons, so git-ui (lazygit) startup is exercised in addition to the core runtime contract. It is host-side because macOS binaries and host runtime access are not available from the Linux devcontainer.

For a final v1 release candidate, retain the two Linux archives, two macOS archives, their checksum sidecars, the container- and host-release logs, and an exact-version rollback/reinstall log under one project-relative rehearsal directory. Record the completed rehearsal against the exact candidate and tested binary:

The final line of each retained log is the corresponding completion marker:

release phase=container status=passed candidate=<40-character-commit>
release phase=host status=passed candidate=<40-character-commit>
rollback status=passed candidate=<40-character-commit> version=<version>

Append a marker only after its command succeeds. The recorder also opens every archive, verifies the expected target-named binary, validates every checksum, and refuses symlinked inputs.

RELEASE_CANDIDATE_SHA=<40-character-commit> \
AIBOX_RELEASE_BINARY_SHA256=sha256:<tested-binary-digest> \
  ./scripts/record-v1-platform-rehearsal.sh \
    dist/v1-platform-rehearsal/1.0.0 1.0.0

Stable readiness remains blocked if this evidence is missing, stale, bound to a different candidate, or references a missing or modified artifact.

The two macOS targets build concurrently. The host release also overlaps that build lane with source-hash-aware image reuse or publication, then joins both lanes before uploading binaries and starting the runtime smoke. Healthy tmux smoke probes advance on observed session, window, pane, and status readiness; their timeouts are failure ceilings rather than fixed delays. Host timings are written to dist/RELEASE-HOST-TIMINGS.md.

The Linux-side Tier 2 E2E companion is separate from this host phase. From the devcontainer, verify that companion over SSH/SCP; do not use local Docker/Podman availability in the main devcontainer as the reachability check.

release-doctors is an aibox CLI development exception to the normal host/container diagnostic split. Inside the workspace container, ordinary dogfood diagnostics use pk-doctor; aibox doctor is host-side. During release Phase 0, however, ./scripts/maintain.sh release-doctors runs aibox doctor as a host-context simulation so the CLI’s host diagnostic behavior remains gated.

Verification

After release:

• gh release view vX.Y.Z shows all expected binary assets.
• curl -fsSL https://raw.githubusercontent.com/projectious-work/aibox/main/scripts/install.sh | VERSION=X.Y.Z bash installs the expected version.
• aibox --version reports X.Y.Z.
• For v0.26.x, docker pull ghcr.io/projectious-work/aibox:base-debian-vX.Y.Z or the matching Podman pull succeeds.
• For v0.27.0+, docker pull ghcr.io/projectious-work/aibox:base-debian-runtime-vX.Y.Z and base-debian-runtime-latest succeed. Foundation images are published as base-debian-foundation-vX.Y.Z; source-hash marker tags are not published.
• To remove historical source-hash marker tags from GHCR, first run ./scripts/maintain.sh ghcr-prune-source-tags --repair-mixed and review the mixed-version repair plan. Then run ./scripts/maintain.sh ghcr-prune-source-tags --repair-mixed --execute with read:packages, delete:packages, and Docker Buildx available on the host.
• The docs site at https://projectious-work.github.io/aibox/ reflects the release.

Project Devcontainer

The maintenance script can also operate this repository’s own devcontainer:

./scripts/maintain.sh start
./scripts/maintain.sh status
./scripts/maintain.sh attach
./scripts/maintain.sh stop

Do not confuse .devcontainer/ in this repository with images/. The former is the environment used to develop aibox. The latter contains image recipes published for downstream projects.

1.2 - E2E Test Catalogue

E2E Test Catalogue

This page describes every end-to-end and integration test in cli/tests/e2e/ in plain language. Each entry states the precondition and the expected outcome, followed by a reference to the exact test function for traceability.

Test tiers

Tier 1 tests run automatically with cargo test. Tier 2 tests require the companion container and the --features e2e flag. The expensive visual matrix tests are opt-in and are not included in the default Tier 2 command.

From inside the aibox devcontainer, the companion is a remote SSH target, not a local Docker/Podman dependency. Check it with:

ssh -i /workspace/.aibox-e2e-runner-home/.ssh/id_ed25519 testuser@aibox-e2e-testrunner 'echo ok'

Missing docker or podman in the main devcontainer does not mean Tier 2 cannot talk to the companion. The tests deploy the current aibox binary and addons with SCP, then use the companion’s own runtime for lifecycle checks.

Rebuilding the Kubernetes-capable companion

The release-gated disposable-cluster test requires the companion to run systemd as PID 1, use cgroup v2 delegation for rootless Podman, expose the read-only host /lib/modules tree, and contain both kind and kubectl. ./scripts/maintain.sh test-e2e verifies this contract before it runs Cargo; when the reachable companion is an older image, it automatically rebuilds and recreates the service.

If a host daemon restart or a failed build prevents automatic recreation, run this from the repository root on the Docker host, then rerun the E2E command:

docker compose -f .devcontainer/docker-compose.yml -f .devcontainer/docker-compose.override.yml \
  up -d --build --force-recreate aibox-e2e-testrunner
./scripts/maintain.sh test-e2e

Do not accept SSH reachability alone as evidence that this companion is ready: an old SSH-only image reports sshd as PID 1 and fails the preflight without mutating a disposable cluster.

aibox commands inside the devcontainer

In normal dogfood use, the workspace container is the processkit/runtime side of the project: run pk-doctor there. aibox doctor is a host-side diagnostic and should not be used from inside the container to judge the live dogfood project. It still can run inside containers when that container is intentionally simulating a host environment for CLI development.

The aibox repository has deliberate exceptions because it develops the aibox CLI. Those exceptions simulate host-user behavior in controlled test projects:

• Tier 1 tests run aibox init, aibox apply, aibox doctor, and related commands in temporary directories, usually without starting containers.
• Tier 1 mock tests put fake docker/podman scripts on PATH to verify host runtime behavior without requiring a real runtime in the main devcontainer.
• Tier 2 tests deploy the current binary to aibox-e2e-testrunner over SSH and may run aibox apply, aibox up, or aibox doctor there because the companion owns the nested container runtime for the test.
• Release Phase 0 runs ./scripts/maintain.sh release-doctors, which invokes aibox doctor as an explicit host-context simulation.

Use these exceptions only in aibox CLI development/release harnesses. They are not general dogfood escape hatches.

The container-side release command runs Tier 2 as part of Phase 1 with cargo test --features e2e --test e2e, so the SSH companion, generated runtime probes, and non-ignored asciinema checks are release gates. Tier 1 modules are excluded from feature-enabled test binaries because the default cargo test invocation already covers them. The default Tier 2 suite intentionally performs only one full generated container build/start/probe. File-generation contracts use --no-container, and ./scripts/maintain.sh test-e2e removes only E2E-owned containers, networks, volumes, and workspaces before and after the suite. Images and BuildKit caches survive for later runs.

The suite defaults to four test threads. Workspace-isolated tests run in parallel, while tests that mutate the companion runtime and tests that own interactive tmux/Yazi state use separate keyed serialization lanes. Override the worker count with AIBOX_E2E_TEST_THREADS; use 1 when diagnosing ordering or isolation failures.

The release process also has a host-side generated-runtime smoke: ./scripts/maintain.sh release-runtime-smoke X.Y.Z. It is not an SSH companion test; it runs on the macOS host during release-host, creates a fresh downstream-style project, runs aibox init and aibox apply --standardize-config, starts the generated container, probes tmux-native status output and the diagnostics sidecar, and writes logs under dist/release-smoke/vX.Y.Z/. The default AIBOX_RELEASE_SMOKE_TIER=addons includes git-ui (lazygit) probes. Use minimal only for a quicker non-addon pass, or full to include preview addons and force --no-cache.

Opt-in visual E2E

Use these commands when the release diff touches generated runtime visuals or when the periodic full visual sweep is due:

Set AIBOX_E2E_VISUAL_ARTIFACT_DIR to write documentation capture artifacts elsewhere. The artifacts are intended as source material for current-release website screenshots and screencasts.

Lifecycle — lifecycle.rs

Companion is reachable If the SSH connection to aibox-e2e-testrunner is attempted, then the host must respond with ok, confirming the companion container is up and reachable before any other Tier 2 test runs. The test also asserts that the companion image has the expected tmux and Yazi tools for the visual/runtime tests; stale companion images fail here with a rebuild hint. [lifecycle.rs · companion_is_reachable]

Init then apply produces valid project If aibox init is run followed by aibox apply, then aibox.toml, .devcontainer/Dockerfile, .devcontainer/docker-compose.yml, and CLAUDE.md must all exist in the workspace. [lifecycle.rs · lifecycle_init_apply]

Generated container starts If a fresh project is initialized, applied, and the generated Compose service is started on the companion runtime, then the running container must expose /etc/aibox-version, tmux, Yazi, and valid aibox-status --plugin-json output. [lifecycle.rs · lifecycle_apply_starts_generated_container]

CLAUDE.md user content is preserved on apply If a user edits CLAUDE.md after aibox init and then runs aibox apply, then the edited content must still be present — aibox must not overwrite user-modified files. [lifecycle.rs · claudemd_preserved_on_sync]

Generated files are overwritten on apply If a generated file (e.g. .devcontainer/Dockerfile) is manually tampered with and aibox apply is run, then the file must contain regenerated content and the tampered content must be gone. [lifecycle.rs · generated_files_overwritten_on_sync]

Status reports missing when no container exists If aibox get runtime is run in a project with no running container, then the output must contain missing or equivalent wording. [lifecycle.rs · status_without_container_shows_missing]

Default processkit mode writes the project skeleton If aibox init --harness claude is run, then the slim project skeleton must exist: aibox.toml, an empty context/ directory, AGENTS.md, and the thin provider pointer files for enabled harnesses. This is the default processkit mode, so a later aibox apply with a real [processkit].version can install processkit content under context/. The single-file context tracks (BACKLOG.md, DECISIONS.md, STANDUPS.md) are not scaffolded by init — the corresponding processkit skills create entities in place on first use. [lifecycle.rs · init_with_managed_preset_creates_context_files]

Legacy processkit package selection is recorded in aibox.toml If aibox init --context software is run, then the same processkit-mode project skeleton must exist and the package selection is recorded under [context].packages. The --context <PKG> option is retained as a hidden legacy package selector; new flows should use [context].mode for the context backend and [skills] for explicit processkit skill selection. [lifecycle.rs · init_with_software_preset_creates_code_files]

Addon management — addon.rs

Addon add writes to aibox.toml If aibox set addon python is run in an initialized project, then aibox.toml must contain an [addons.python] section afterwards. [addon.rs · set_addon_modifies_toml]

Addon remove cleans aibox.toml If a project is initialized with the python addon and then aibox delete addon python is run, then the [addons.python] section must no longer appear in aibox.toml. [addon.rs · delete_addon_cleans_toml]

Addon content appears in generated Dockerfile after apply If a project is initialized with the python addon and aibox apply is run, then .devcontainer/Dockerfile must contain Python-related content (install commands or references to uv). [addon.rs · addon_rebuild_includes_tools_in_dockerfile]

Addon list shows available addons If aibox get addon is run in an initialized project, then the output must list known addons such as python. [addon.rs · addon_list_shows_available]

Reset and backup — reset.rs

Reset with backup removes files and creates backup directory If aibox reset project --yes is run in an initialized project, then aibox.toml must be deleted and .aibox/backup/ must be created containing the backed-up files. [reset.rs · reset_creates_backup]

Reset with –no-backup removes all files without creating a backup If aibox reset project --no-backup --yes is run, then aibox.toml and .devcontainer/ must be deleted and .aibox/backup/ must not be created. [reset.rs · reset_no_backup_deletes_all]

Doctor diagnostics — doctor.rs

Doctor without a config reports an error If aibox doctor is run in a directory that has no aibox.toml, then the output must mention the missing config or config error and the command must still exit 0 (doctor is always non-fatal). [doctor.rs · doctor_reports_missing_files]

Doctor after init reports healthy checks If aibox doctor is run immediately after a successful aibox init, then the output must contain at least one passing check indicator (ok, ✓, or similar). [doctor.rs · doctor_after_init_reports_healthy]

Version upgrade flows — version_upgrade.rs

Generated Dockerfile contains version label If aibox init is run, then the generated .devcontainer/Dockerfile must contain a LABEL aibox.version line so the built image carries a machine-readable version stamp. [version_upgrade.rs · dockerfile_contains_aibox_version_label]

Generated Dockerfile writes version to /etc/aibox-version If aibox init is run, then the generated .devcontainer/Dockerfile must contain a RUN statement that writes to /etc/aibox-version inside the image, making the build version queryable from within a running container. [version_upgrade.rs · dockerfile_contains_etc_aibox_version_write]

Up fails when container image version mismatches config If an existing container was built from image v0.0.1 (mock label) and aibox.toml pins the current version, then aibox up must exit non-zero and output a message containing mismatch and a suggestion to run aibox apply. [version_upgrade.rs · start_fails_on_image_version_mismatch]

Up succeeds when container image version matches config If an existing container reports the same image version as the one pinned in aibox.toml, then aibox up must not produce a version mismatch error. [version_upgrade.rs · start_does_not_error_when_versions_match]

Update -y exits zero without hanging If aibox self update -y is run (the global --yes flag), then the command must exit 0 regardless of registry availability — confirming the flag is correctly wired to cmd_update and does not block on an interactive prompt. [version_upgrade.rs · update_yes_flag_exits_zero]

Update –dry-run does not mention .aibox-version If aibox self update --dry-run is run, then the output must not contain the phrase Would update .aibox-version — that write was removed in BACK-060 because the image version is now tracked exclusively in aibox.toml. [version_upgrade.rs · update_dry_run_does_not_mention_aibox_version_file]

Doctor warns when running container has a stale image label If the running container reports aibox.version=0.0.1 (mock label) but aibox.toml pins the current version, then aibox doctor must emit a warning containing mismatch while still exiting 0. [version_upgrade.rs · doctor_warns_on_container_version_mismatch]

Doctor warns when .aibox-version is outdated If .aibox-version is overwritten with 0.0.1 (an old CLI version) and aibox doctor is run, then the output must contain CLI version mismatch and suggest running aibox apply to update generated files. [version_upgrade.rs · doctor_warns_on_cli_version_file_mismatch]

Migration — migration.rs

Apply absorbs legacy .aibox-version into aibox.lock If .aibox-version is overwritten with 0.1.0 (an old version) and aibox apply is run, then .aibox-version must be removed and aibox.lock must contain the current [aibox].cli_version sync state. [migration.rs · apply_absorbs_legacy_version_file_into_lock]

Update command — update.rs

Update exits zero when registry returns an error If aibox self update is run in a project where the GHCR registry is unreachable or returns a non-2xx response, then the command must still exit 0 — the error must be treated as a warning, not a hard failure. [update.rs · update_runs_without_crashing_in_derived_project]

Update –check exits zero If aibox self update --check is run in an initialized project, then the command must exit 0 and print output containing either Current CLI version: or Checking for updates, regardless of whether the registry is reachable. [update.rs · update_check_exits_cleanly]

Appearance — appearance.rs

All themes render without error and without leftover placeholders If aibox init is run for each of the seven supported themes (gruvbox-dark, catppuccin-mocha, catppuccin-latte, dracula, tokyo-night, nord, projectious), then the seeded config files must contain no unreplaced template placeholders such as AIBOX_THEME or AIBOX_VIM_COLORSCHEME. [appearance.rs · all_themes_render_without_error]

Gruvbox theme sets the correct vim colorscheme and tmux theme If aibox init --theme gruvbox-dark is run, then vimrc must contain gruvbox or retrobox as the colorscheme and tmux.conf must reference gruvbox-dark. [appearance.rs · theme_gruvbox_renders_correctly]

Catppuccin-mocha theme is reflected in tmux config If aibox init --theme catppuccin-mocha is run, then tmux.conf must reference catppuccin-mocha. [appearance.rs · theme_catppuccin_mocha_renders]

Changing the theme updates all themed tool configs If a project is initialized with gruvbox-dark and the theme is changed to dracula via aibox apply, then tmux.conf must contain dracula and no longer gruvbox-dark, and vimrc, yazi/theme.toml, and starship.toml must be updated. Lazygit config is optional and is checked only when the git-ui addon enables it. [appearance.rs · theme_change_auto_applies_untouched_runtime_files]

Each theme produces matching configs across all tools If aibox init is run for each of five themes with known vim colorscheme names, then vimrc must contain the exact colorscheme <name> line, tmux.conf must reference the theme name, yazi and starship configs must be non-empty, and lazygit config must be non-empty when present. [appearance.rs · theme_alignment_all_tools_match_selected_theme]

Yazi keymap includes the open-in-editor binding If aibox init is run, then yazi/keymap.toml must contain an "e" key binding that invokes open-in-editor. [appearance.rs · yazi_keymap_includes_edit_in_pane_binding]

All prompt presets produce a non-empty starship config If aibox init is run for each prompt preset (default, plain, minimal, nerd-font, pastel, powerline-pastel, bracketed, arrow), then starship.toml must exist and be non-empty. [appearance.rs · all_prompts_render_without_error]

Default prompt includes directory and git_branch modules If aibox init --prompt default is run, then starship.toml must contain both directory and git_branch module sections. [appearance.rs · prompt_default_generates_starship]

Plain prompt uses ASCII-only symbols If aibox init --prompt plain is run, then starship.toml must not contain Nerd Font glyph characters (e.g. no \ue0b0 powerline arrow). [appearance.rs · prompt_plain_no_nerd_font]

Config coverage — config_coverage.rs

Container name appears in docker-compose.yml If aibox.toml specifies a container name and aibox apply is run, then docker-compose.yml must contain that name. [config_coverage.rs · container_name_in_compose]

Container hostname appears in docker-compose.yml If aibox.toml specifies a hostname and aibox apply is run, then docker-compose.yml must contain that hostname. [config_coverage.rs · container_hostname_in_compose]

Port mappings appear in docker-compose.yml If aibox.toml defines ports (e.g. "8080:80") and aibox apply is run, then docker-compose.yml must contain those port entries. [config_coverage.rs · container_ports_in_compose]

Extra packages appear in the generated Dockerfile If aibox.toml lists extra packages and aibox apply is run, then .devcontainer/Dockerfile must contain those package names in an apt install block. [config_coverage.rs · container_extra_packages_in_dockerfile]

Environment variables appear in docker-compose.yml If aibox.toml defines environment variables and aibox apply is run, then docker-compose.yml must contain those key-value pairs. [config_coverage.rs · container_environment_in_compose]

Extra volumes appear in docker-compose.yml If aibox.toml defines extra volume mounts and aibox apply is run, then docker-compose.yml must contain those source and target paths. [config_coverage.rs · container_extra_volumes_in_compose]

Claude AI provider adds volume mount If aibox.toml lists claude as an AI provider and aibox apply is run, then docker-compose.yml must contain a volume mount for the .claude config directory. [config_coverage.rs · ai_claude_provider_volume_mount]

Aider AI provider adds volume mount If aibox.toml lists aider as an AI provider and aibox apply is run, then docker-compose.yml must contain a volume mount for the .aider config directory. [config_coverage.rs · ai_aider_provider_volume_mount]

Multiple AI providers each add their own volume mounts If aibox.toml lists both claude and gemini as providers and aibox apply is run, then docker-compose.yml must contain volume mounts for both .claude and .gemini. [config_coverage.rs · ai_multiple_providers_volume_mounts]

Audio enabled adds PulseAudio mounts and socket If aibox.toml enables audio and aibox apply is run, then docker-compose.yml must contain audio-related volume mounts or socket references. [config_coverage.rs · audio_enabled_adds_mounts]

Audio disabled produces no audio mounts If aibox.toml has audio disabled (the default) and aibox apply is run, then docker-compose.yml must not contain audio-related content. [config_coverage.rs · audio_disabled_no_mounts]

Python addon adds install commands to Dockerfile If aibox.toml includes the python addon and aibox apply is run, then .devcontainer/Dockerfile must contain Python install instructions. [config_coverage.rs · addon_python_in_dockerfile]

Rust addon adds rustup install to Dockerfile If aibox.toml includes the rust addon and aibox apply is run, then .devcontainer/Dockerfile must contain rustup installation instructions. [config_coverage.rs · addon_rust_in_dockerfile]

Multiple addons each contribute to the Dockerfile If aibox.toml includes both the python and rust addons and aibox apply is run, then .devcontainer/Dockerfile must contain install content for both. [config_coverage.rs · addon_multiple_in_dockerfile]

Legacy minimal package creates processkit project skeleton If aibox init --context minimal is run, then aibox.toml, aibox.lock, an empty context/ directory, and a thin CLAUDE.md pointer must exist. The single-file context tracks (BACKLOG.md, DECISIONS.md, STANDUPS.md) are not created at init time — the corresponding processkit skills create them in place on first use.

Default processkit mode is the recommended full context path If aibox init --harness claude is run, then the slim project skeleton must exist. With a real [processkit].version pinned, aibox apply then installs the selected processkit skill catalogue under context/skills/ and the immutable upstream snapshot under context/templates/processkit/<version>/.

Product / research / software packages The legacy processkit packages (minimal, managed, software, research, product) are declarative metadata in [context].packages when [context].mode = "processkit". Current projects should prefer explicit [skills] selection for installed processkit skills. Harness-only mode ignores processkit package and skill selection entirely and does not create processkit content or processkit references.

File preview — preview.rs

svg.yazi plugin is seeded into .aibox-home after init If aibox init is run, then .aibox-home/.config/yazi/plugins/svg.yazi/init.lua must exist. [preview.rs · svg_yazi_plugin_seeded]

eps.yazi plugin is seeded into .aibox-home after init If aibox init is run, then .aibox-home/.config/yazi/plugins/eps.yazi/init.lua must exist. [preview.rs · eps_yazi_plugin_seeded]

svg.yazi plugin invokes resvg for conversion If svg.yazi/init.lua is read after init, then its content must reference resvg as the SVG-to-PNG conversion tool. [preview.rs · svg_yazi_plugin_uses_resvg]

eps.yazi plugin invokes ghostscript for conversion If eps.yazi/init.lua is read after init, then its content must reference gs (ghostscript) as the EPS-to-PNG conversion tool. [preview.rs · eps_yazi_plugin_uses_ghostscript]

yazi.toml has a [plugin] section with prepend_previewers If aibox init is run, then yazi.toml must contain a [plugin] section that defines prepend_previewers. [preview.rs · yazi_toml_has_plugin_section]

*yazi.toml routes .svg to the svg previewer If aibox init is run, then yazi.toml must contain a prepend_previewers entry matching *.svg with run = "svg". [preview.rs · yazi_toml_svg_previewer_entry]

*yazi.toml routes .eps to the eps previewer If aibox init is run, then yazi.toml must contain a prepend_previewers entry matching *.eps with run = "eps". [preview.rs · yazi_toml_eps_previewer_entry]

SVG and EPS entries appear before built-in image entries If aibox init is run, then the *.svg and *.eps entries in prepend_previewers must appear at a lower byte offset than the *.jpg entry, ensuring first-match semantics dispatch SVG/EPS to the custom plugins rather than the built-in image previewer. [preview.rs · yazi_toml_svg_and_eps_precede_builtin_previewers]

sample.svg fixture is valid XML If tests/e2e/fixtures/sample.svg is read, then its content must start with <svg or <?xml, confirming the fixture file is intact. [preview.rs · fixture_sample_svg_is_valid_xml]

sample.eps fixture has a valid EPS header If tests/e2e/fixtures/sample.eps is read, then its content must start with %!PS-Adobe or contain %%BoundingBox, confirming the fixture file is intact. [preview.rs · fixture_sample_eps_has_eps_header]

Generated runtime — runtime_generated.rs

Generated runtime tools are usable If a fresh project is initialized with git-ui and shell status enabled, then aibox apply --no-container --standardize-config must generate Yazi config that parses with the pinned Yazi binary, lazygit state directories that permit startup, and an aibox-status --plugin-json payload with required fields. [runtime_generated.rs · generated_runtime_yazi_lazygit_and_status_are_usable]

Generated tmux status renders If the generated dev layout is launched under asciinema with tmux status enabled, then the cast must show key/status row text and runtime status output. [runtime_generated.rs · generated_runtime_tmux_status_renders_key_and_status_rows]

Visual matrix — visual_matrix.rs

These tests are ignored by default and run only through the explicit visual E2E commands above.

Generated layouts render across all themes If each generated layout is launched for each supported theme, then the recording must include the theme RGB signature and tmux status/key row text. [visual_matrix.rs · visual_generated_layouts_render_across_all_themes]

Generated tools and harness windows render when enabled If all harnesses and visual runtime addons are enabled, then window traversal must show the expected Yazi surface, Vim, shell, lazygit, and every harness marker. [visual_matrix.rs · visual_generated_tools_and_harness_windows_render_when_enabled]

Yazi previews, git symbols, and optional plugins render If the Yazi preview addons are enabled, then generated Yazi config must parse, preview plugins must be installed, git symbols must be configured, and directory, Markdown, CSV, TSV, and SQLite previews must render their markers. [visual_matrix.rs · visual_yazi_previews_git_symbols_and_optional_plugins_render]

Smoke tests — smoke.rs

These tests validate that the Tier 2 companion container’s container runtime is functional end-to-end (Tier 2 only).

Container runtime is available on the companion If the companion container is queried for its selected runtime, then the command must succeed and the output must contain either docker or podman. [smoke.rs · runtime_available_on_companion]

Container runtime can pull and run a container If the selected runtime runs alpine echo hello-e2e on the companion, then the image pull, container creation, and command execution must succeed, and the output must contain hello-e2e. [smoke.rs · runtime_can_pull_and_run_container]

1.3 - Version-line porting

Version-line porting

aibox maintains the v0.x and v1.x lines in parallel. A fix landing on either line must be reconciled with the other line when applicable.

The release gate compares both maintained branches after the recorded enforcement baselines in .github/version-line-port-baselines.toml. Every non-merge source commit must have a matching port on the target line or an explicit not-applicable disposition. This derives obligations from Git history, so it does not depend on labels, manually created issues, or workflow tokens.

When the equivalent change lands on the other line, add this commit trailer:

Version-Line-Port: ported-from=<full source commit SHA>

The target line’s release gate recognizes and settles the matching obligation. When a change genuinely cannot or should not cross lines, document the reason in the commit body and add:

Version-Line-Port: not-applicable

Use not-applicable only for line-specific version metadata, generated release artifacts, or code that does not exist on the other line. Do not use it to defer an applicable fix.

Before publishing, run:

scripts/check-version-line-ports.sh check v0
scripts/check-version-line-ports.sh check v1

The release workflow automatically runs the gate for the major version being published.

1.4 - V1 adoption pilots

V1 adoption pilots

Stable-v1 readiness requires four repeatable journeys against the exact candidate and binary:

1. a new Compose workspace can compile and render a deterministic plan;
2. a representative v0 project can preview, apply, and roll back a reviewed v1 intent without exposing secrets or touching v1 deployment records;
3. an existing Kubernetes target passes the complete live M7c lifecycle;
4. exact-pinned processkit install, verify, unchanged update, recovery, and uninstall pass through the direct opaque boundary.

After the live M7c and M5 producer evidence has been generated, run:

RELEASE_CANDIDATE_SHA="$(git rev-parse HEAD)" \
AIBOX_RELEASE_BINARY_SHA256="sha256:<tested-binary-digest>" \
  ./scripts/test-v1-adoption-pilots.sh

The harness refuses missing or candidate-mismatched prerequisites. It executes the local Compose and migration journeys, verifies the live Kubernetes and direct-processkit scenario sets, and writes .aibox/release-evidence/v1-readiness/adoption-pilots.json. Stable publication reruns this automatically and verifies the retained log digest.

This automated evidence establishes repeatability, not user sentiment. Record configuration friction, plan comprehension, recovery steps, terminology confusion, and documentation gaps from external pilots in their tracking issues. Do not convert an unrun or unsuccessful external pilot into a passing release marker.

2 - Overview

Overview

aibox creates reproducible, AI-ready development workspaces from one project configuration file. It is not a new container runtime and it is not a process framework. It is the glue that turns a declared project shape into a standard devcontainer, selected tool bundles, AI harness configuration, and either a processkit-backed context layer or a harness-only project skeleton.

The Short Version

aibox init my-app --harness claude --addon python
aibox apply
aibox up

aibox init writes the initial project contract. aibox apply reconciles that contract into generated files and content. aibox up starts or attaches to the workspace.

What aibox Owns

The generated files use common formats on purpose. You can inspect them, run Docker or Podman commands against them, and use the same project in VS Code Dev Containers when that is useful.

What processkit Owns

processkit owns the project-process content:

• skills and SKILL.md files
• schemas and state machines
• work processes
• package definitions such as managed, software, research, and product
• the canonical AGENTS.md template

aibox installs processkit content into context/, keeps an immutable upstream snapshot under context/templates/processkit/<version>/, and uses that snapshot for three-way diff and migration workflows. The content itself remains processkit-owned. This is the default [context].mode = "processkit" path.

When [context].mode = "harness-only", aibox skips processkit entirely. It still writes the container, runtime home, harness config, and minimal AGENTS.md, but it does not install processkit skills, templates, hooks, command adapters, Migration entities, or processkit MCP gateway config.

Why This Split Matters

The split keeps the system forkable and maintainable:

• aibox can improve containers, addons, and runtime operations without changing process semantics.
• processkit can improve skills, primitives, and workflows without shipping a new container tool.
• projects can pin or fork processkit independently through [processkit] in aibox.toml when they use processkit mode.
• projects that only want installed harnesses and a reproducible container can choose harness-only mode without carrying processkit references.

When To Use aibox

Use aibox when you want:

• a reproducible terminal-first workspace for AI-assisted development
• selected AI harnesses and tool bundles declared in one file
• project context on disk instead of only in chat history
• consistent tmux layouts, themes, shell tooling, and runtime diagnostics
• a clean handoff path between different agents and human contributors

Do not use aibox as a general infrastructure deployer. It manages development workspaces. Production deployment, remote host provisioning, and service orchestration belong in dedicated infrastructure tooling.

Daily Mental Model

aibox.toml is desired state.

Run aibox apply after changing desired state. It regenerates managed files, updates the lock file, and builds the image unless you ask it not to. In processkit mode it also refreshes processkit content; in harness-only mode it only touches the container, runtime, harness, and minimal project surfaces.

Run aibox up to enter the workspace. It starts the Compose project and attaches through tmux.

Run aibox doctor when the environment looks wrong. Run aibox get runtime --resources when the workspace feels slow or agents exit without a clean error.

3 - Skills (via processkit)

Skills

As of aibox v0.16.0, skills are no longer bundled with aibox. They live in processkit — a separate, versioned content repository that ships skills, primitives, processes, packages, and the canonical AGENTS.md template.

aibox owns the container (devcontainers, addons, the CLI, the install/apply machinery). processkit owns the content (skills, packages, processes, state machines). The boundary is deliberate and load-bearing: it lets the two projects move at their own velocity without dragging each other through breaking changes.

Where skills land in your project

After running aibox init and aibox apply in your project, processkit content is materialised under your context/ directory when [context].mode = "processkit":

context/
├── skills/                          # Active, editable skill copies
└── templates/
    └── processkit/
        └── v0.27.4/                 # Immutable upstream snapshot, git-tracked
            ├── context/
            │   └── skills/
            ├── .processkit/
            └── AGENTS.md

The version in the path (v0.27.4) is whatever you pinned in aibox.toml:

[context]
mode = "processkit"

[processkit]
source  = "https://github.com/projectious-work/processkit.git"
version = "v0.27.4"

When [context].mode = "harness-only", aibox does not install processkit skills, does not create context/templates/processkit/, and does not project processkit command adapters into harness-specific surfaces. The generated AGENTS.md is a minimal aibox-owned file with no processkit references.

The context/skills/ copies are yours to edit. The context/templates/processkit/<version>/ copies are the immutable upstream snapshot — aibox apply uses them as the base side of a three-way diff to detect upstream changes that should be pulled into your local edits.

Skill catalogue and documentation

processkit documentation is not yet deployed as a standalone site. Until then, browse the upstream source directly:

• GitHub: https://github.com/projectious-work/processkit/tree/main/src/skills
• Releases: https://github.com/projectious-work/processkit/releases
• In your project, after aibox apply: context/skills/ and context/templates/processkit/<version>/context/skills/

Every skill is a directory with at least a SKILL.md (the agent-readable instructions) and may include references/, mcp/, assets/, and scripts/ siblings. Skills follow the open Agent Skills specification.

Browsing installed skills

aibox get skill                    # list installed skills, grouped by category
aibox get skill --all              # include available-but-not-installed skills
aibox get skill --category ai      # filter by category
aibox describe skill <name>        # frontmatter + description for one skill

Skill Selection

New projects list the standard processkit operating skills explicitly in [skills].include. Use [skills].include and [skills].exclude for skill-level overrides in processkit mode:

[skills]
include = [
  "pk-doctor",
  "status-briefing",
]
exclude = [
  # "skill-to-omit",
]

Legacy package selections are still accepted for compatibility, but new aibox.toml files use explicit skill selection as the primary control surface. enabled and disabled are accepted as aliases for older configs. [skills] is omitted and ignored in harness-only mode.

Custom skills

To add a project-specific skill, drop a directory under context/skills/:

context/skills/my-custom-skill/
└── SKILL.md

Local skills are not touched by aibox apply. They are also not part of any processkit package — they exist purely for the local project.

Core skills

Some processkit skills carry metadata.processkit.core: true in their frontmatter (e.g. skill-finder). Core skills are installed regardless of any [skills].include / [skills].exclude configuration. aibox doctor warns if you attempt to exclude a core skill.

Why this split?

• Independent release cadence. processkit can ship a new skill or fix a prompt without forcing an aibox CLI release.
• Reusable content. Other tools can consume processkit directly without taking a dependency on aibox or its container stack.
• Forkable content. A team can fork processkit, point [processkit].source at the fork, and ship a private skill catalogue without forking aibox itself.
• Smaller aibox. The aibox binary stays focused on container lifecycle and the install/diff/migrate machinery.

See [processkit] configuration for the full set of fields, including release-asset URL templates and SHA256 verification.

4 - Getting Started

4.1 - Installation

Installation

Prerequisites

aibox requires a container runtime and a Compose-compatible provider on your host machine.

Podman (recommended)

# macOS
brew install podman
podman machine init
podman machine start

# Fedora / RHEL
sudo dnf install podman podman-compose

# Ubuntu / Debian
sudo apt install podman podman-compose

Docker

# macOS
brew install --cask docker
# Then launch Docker Desktop

# Linux — follow the official install guide
# https://docs.docker.com/engine/install/

aibox auto-detects which runtime is available. If both are installed, Podman takes priority. OrbStack works through its Docker-compatible runtime and Compose integration.

Install script (recommended)

Install the latest stable release:

curl -fsSL https://raw.githubusercontent.com/projectious-work/aibox/main/scripts/install.sh | bash

Downloads the correct pre-built binary for your platform (Linux or macOS, x86_64 or ARM64) and installs it to ~/.local/bin/.

Install the v1 alpha

The v1 line is a prerelease and is never selected by the stable channel. After the GitHub prerelease exists, install its exact version:

curl -fsSL https://raw.githubusercontent.com/projectious-work/aibox/main/scripts/install.sh |
  VERSION=1.0.0-alpha.1 bash
aibox --version

Do not use a moving branch name as the installed version. Exact pins make reinstallation and rollback reproducible.

Roll back from the alpha

Reinstall the last known-good v0 release by exact version:

curl -fsSL https://raw.githubusercontent.com/projectious-work/aibox/main/scripts/install.sh |
  VERSION=0.28.17 bash
aibox --version

This replaces the CLI binary; it does not destroy v1 deployments or rewrite their receipts. Remove a v1 deployment with the v1 CLI’s guarded aibox deploy destroy flow before rolling back when cleanup is required. Configuration rollback is separate: use the exact backup created by aibox config migrate-v1 --apply, and preview restoration before applying it.

Other options

# Install a specific version
curl -fsSL https://raw.githubusercontent.com/projectious-work/aibox/main/scripts/install.sh | VERSION=X.Y.Z bash

# Install to a custom directory
curl -fsSL https://raw.githubusercontent.com/projectious-work/aibox/main/scripts/install.sh | INSTALL_DIR=/usr/local/bin sudo -E bash

Manual download

Download the binary for your platform from the releases page:

# Example for macOS ARM64
tar xzf aibox-vX.Y.Z-aarch64-apple-darwin.tar.gz
mv aibox-vX.Y.Z-aarch64-apple-darwin ~/.local/bin/aibox
chmod +x ~/.local/bin/aibox

Replace X.Y.Z with the release version you downloaded.

Available binaries:

Build from source

Requires a Rust toolchain:

git clone https://github.com/projectious-work/aibox.git
cd aibox
cargo install --path cli

Installs the binary to ~/.cargo/bin/.

Verify

aibox --version
# aibox X.Y.Z

Shell completion scripts

# Add to your shell profile for persistent completion scripts:

# Bash (~/.bashrc)
eval "$(aibox self completion bash)"

# Zsh (~/.zshrc)
eval "$(aibox self completion zsh)"

# Fish (~/.config/fish/config.fish)
aibox self completion fish | source

Next steps

• Create a new project
• Add aibox to an existing project
• Read the overview

4.2 - New Project

New Project

This guide walks through creating a new project from scratch with aibox.

Initialize the Project

mkdir my-app && cd my-app
git init

aibox init my-app --harness claude --addon python

The init command accepts these options:

If you omit options, aibox init runs interactively and prompts for each value.

What Gets Created

By default, aibox init lays down a processkit-backed project skeleton: devcontainer files, config, an empty context/ directory, and processkit content (skills, processes, and the canonical AGENTS.md).

my-app/
├── aibox.toml                  # Single source of truth (includes [processkit])
├── AGENTS.md                   # Canonical agent entry — rendered from processkit scaffolding
├── CLAUDE.md                   # Thin pointer to AGENTS.md (when Claude is enabled in [ai].harnesses)
├── .gitignore                  # Generated with language-specific blocks
├── aibox.lock                  # Records resolved CLI, image, addon, and processkit state
├── .aibox-home/                # Persistent config (git-ignored)
├── .devcontainer/
│   ├── Dockerfile              # Generated from aibox.toml
│   ├── docker-compose.yml      # Generated — volume mounts, env vars
│   └── devcontainer.json       # Generated — VS Code integration
└── context/
    ├── skills/                 # Editable skill copies — installed by processkit
    ├── processes/              # release, code-review, feature-development, bug-fix
    ├── schemas/                # primitive schemas
    ├── state-machines/         # state machine definitions
    └── templates/
        └── processkit/
            └── v0.27.4/        # Immutable upstream snapshot, used by `aibox apply` for three-way diffs

For projects that only want the generated devcontainer and AI harness setup, use harness-only mode:

aibox init my-app --context-mode harness-only --harness claude

Harness-only projects still get aibox.toml, .devcontainer/, .aibox-home/, selected harness config, AGENTS.md, and provider pointer files such as CLAUDE.md. They do not get processkit content, context/skills/, context/templates/processkit/, processkit MCP gateway config, processkit hooks/preauth, processkit command adapters, or processkit Migration entities. The minimal generated AGENTS.md contains no processkit references.

[container.environment]
ANTHROPIC_API_KEY = "sk-ant-..."
GH_TOKEN = "github_pat_project_scoped_token"

aibox init my-app --processkit-version v0.27.4

aibox init my-app --processkit-version v1.0.0-alpha.3
aibox init my-app --include-prerelease

The Generated aibox.toml

The scaffolded config file comes with commented documentation for every option:

# aibox.toml — project configuration for aibox.
# All generated files (.devcontainer/) derive from this file.
# Run `aibox apply` after editing to regenerate.
#
# Full documentation: https://projectious-work.github.io/aibox/docs/reference/configuration

[aibox]
project_name = "my-app"
profile      = "human-dev"

[container]
name     = "my-app"
hostname = "my-app"
# user = "aibox"  # Container user (default: aibox)

[container.image]
release_version = "latest"
base = "debian"

[context]
mode = "processkit"
packages = ["product"]

[processkit]
source  = "https://github.com/projectious-work/processkit.git"
version = "latest"

[processkit.context]
schema_version = "1.0.0"

# Addons install tool sets into the container.
# Run `aibox get addon` to see all available addons.
# [addons.python.tools]
# python = { version = "3.14" }
# uv     = { version = "0.12.0" }

# AI harnesses — controls which AI CLIs/configs are enabled.
[ai]
harnesses = [
  { harness = "claude", enable = true, install = true },
]

[customization]
theme  = "gruvbox"
mode   = "auto"
prompt = "default"
layout = "dev"

# Audio support for PulseAudio bridging (e.g., Claude Code voice).
# Requires host-side PulseAudio setup: run `aibox apply audio`
[audio]
enabled = false
# pulse_server = "tcp:host.docker.internal:4714"

After editing, regenerate devcontainer files:

aibox apply

Build and Start

aibox apply    # Reconcile config, regenerate files, build image
aibox up       # Start the container and attach via tmux

You land in a tmux session with the dev layout: a work window with Yazi, the 1st harness, and a shell, plus optional lazygit, further harness, and shell windows.

Four layouts are available: dev (default), focus, cowork, and ai. See Layouts.

The project root is mounted at /workspace. Persistent configuration lives in .aibox-home/ on the host, mounted into the container automatically.

VS Code Integration

The generated devcontainer.json works with VS Code’s Dev Containers extension:

1. Open the project folder in VS Code
2. When prompted, click “Reopen in Container”
3. VS Code builds and starts the container automatically

Both aibox up (terminal) and VS Code can use the same container simultaneously.

Next Steps

• Explore the base image
• Choose the right image addon
• Operate the runtime
• Understand process packages
• Skills (via processkit)
• Full CLI reference

4.3 - Existing Project

Existing Project

This guide covers adding aibox to a project that already exists.

Create aibox.toml

If your project does not yet have a aibox.toml, create one manually or use init:

cd my-existing-project
aibox init my-existing-project --harness claude

If you prefer to write it by hand:

[aibox]
project_name = "my-existing-project"

[container]
name     = "my-existing-project"
hostname = "my-existing-project"

[container.image]
release_version = "latest"
base = "debian"

[context]
mode = "processkit"
packages = ["product"]

[processkit]
source  = "https://github.com/projectious-work/processkit.git"
version = "latest"

[processkit.context]
schema_version = "1.0.0"

[ai]
harnesses = [
  { harness = "claude", enable = true, install = true },
]

[audio]
enabled = false

For a container-and-harness-only adoption with no processkit content, use:

[context]
mode = "harness-only"

[ai]
harnesses = [
  { harness = "claude", enable = true, install = true },
]

In harness-only mode, omit [processkit], [processkit.context], and [skills]; aibox apply will not create processkit skill mirrors or processkit Migration entities.

Apply Devcontainer Files

Run apply to create the .devcontainer/ directory from your config:

aibox apply

This creates:

• .devcontainer/Dockerfile
• .devcontainer/docker-compose.yml
• .devcontainer/devcontainer.json

Replacing Hand-Written Devcontainer Files

If your project already has a .devcontainer/ directory with hand-written files, you have two options:

Option A: Let aibox take over

1. Back up your existing files:

   cp -r .devcontainer .devcontainer.bak
   

2. Run aibox apply – it will overwrite the existing files
3. Move any custom configuration into aibox.toml:
   • Environment variables go in [container.environment]
   • Bind mounts go in [[container.extra_volumes]] (or .aibox-local.toml for secrets and per-developer paths)
4. Rebuild without cached image layers: aibox apply --no-cache (--rebuild is an alias)

Option B: Keep hand-written files

If your devcontainer setup is heavily customized, you can still use aibox for context or harness configuration and skip the container lifecycle commands. Use aibox.toml for the [aibox], [context], [ai], and, when applicable, [processkit] sections, and manage .devcontainer/ yourself.

Running Diagnostics

Use doctor to validate your project structure:

aibox doctor

This checks:

• Config file validity and version
• Container runtime availability (podman or docker)
• .aibox-home/ directory existence
• .devcontainer/ directory existence
• Image and process settings

Example output:

==> Running diagnostics...
 ✓ Config version is compatible
 ✓ Container runtime detected
 ✓ .aibox-home/ directory exists
 ✓ .devcontainer/ directory exists
 ✓ Generated compose enables an init reaper
 ✓ Runtime resource pressure is below configured thresholds
 ✓ Diagnostics complete

Migrating from .root/ to .aibox-home/

If you are upgrading from aibox ≤ v0.3.4, the persisted config directory was renamed from .root/ to .aibox-home/. This directory is gitignored and not tracked, so use a plain filesystem rename:

mv .root .aibox-home

aibox will fall back to .root/ automatically if .aibox-home/ does not exist, so this migration is optional but recommended.

Migrating Context Structure

If your project already has context files (like DECISIONS.md or BACKLOG.md) that predate aibox, doctor can help identify what needs to change. See Migration for the full guide.

Common gaps to watch for

• Node.js version pinning – use the node addon and --addon-tool or [addons.node.tools] when you need a specific supported version.
• postCreateCommand – use post_create_command in [container] config. For git identity, prefer .aibox-home/.config/git/config.
• VS Code extensions/settings – the generated devcontainer.json works with VS Code Dev Containers. For project-specific settings, keep a .vscode/settings.json.
• Third-party CLI tools (Gemini, Jules) – mount from host via [[container.extra_volumes]], or add installation to post_create_command.
• Existing generated containers – after adopting aibox, recreate the runtime so Compose identity, image name, mounts, and init-reaper settings take effect.

Build and Start

Once aibox.toml and .devcontainer/ are in place:

aibox apply    # Regenerate files and build image
aibox up       # Start and attach

The workflow is identical to a new project from this point forward.

Next Steps

• Configuration reference
• CLI commands
• Runtime operations
• Context migration guide

5 - Container

5.1 - Base Image

Base Image

The base image is the foundation for all aibox container flavors. It provides a complete, opinionated development environment built on Debian Trixie Slim.

Installed Tools

GitHub CLI (gh) and lazygit are provided by the optional git-ui addon, not by the base image. Add [addons.git-ui.tools] to aibox.toml when a project needs those tools.

Audio tools are provided by the internal audio-voice recipe, which is selected automatically when [audio] enabled = true and install = true. File-preview and archive helpers such as chafa, timg, poppler-utils, mupdf-tools, entr, and resvg are provided by the optional preview-archive addon.

Build Architecture

The Dockerfile keeps the runtime stage on Debian Trixie Slim and installs tmux from the distro package set. That keeps the terminal multiplexer on the same security update path as the rest of the base image and avoids a separate prebuilt-binary fetch stage.

tmux Configuration

Plugin Policy

aibox-managed tmux plugins are preinstalled and pinned by the generated runtime and image build. TPM is documented only as a user convenience layer for adding personal tmux plugins after initialization; aibox does not rely on TPM to install or update managed plugins.

tmux-resurrect and tmux-continuum are installed and available in the image, but disabled by default until the workspace persistence policy is decided. Users can opt into them in local tmux config, but generated layouts should not assume session resurrection is active.

Key Bindings

All bindings use Ctrl+g as a leader key — press Ctrl+g, release, then press the action key. This avoids conflicts with macOS Option key (which produces special characters like @, €, |) and with Vim/bash Ctrl bindings.

Press Escape or Ctrl+g again to cancel the leader and return to normal mode.

Layouts

aibox ships four tmux layouts. Select one with aibox up --layout <name> (the default is dev). Layouts include harness windows based on the enabled entries in [ai].harnesses and [ai].harness_order; they include the lazygit window only when the git-ui addon selects lazygit.

dev (default)

Window work has Yazi and the 1st harness stacked on the left, with shell on the right. Further harnesses use the ai window; lazygit and shell get their own windows.

focus – one tool per window, fullscreen

Each tool gets the entire screen in its own window. Switch with Ctrl+g [/] or Ctrl+g 1-5.

Windows: files (yazi) | one window per harness | optional lazygit | shell

cowork – side-by-side coding with AI

Window work has Yazi on the left and shell on the right. The ai window contains all harnesses split evenly across full-height panes; the lazygit window is generated when enabled.

Opening Files from Yazi

• Enter – opens file in vim in-place (suspends Yazi, :q returns to Yazi). Works in all layouts.
• e – opens file in a full-screen vim popup and returns to Yazi when vim exits.

Theme

Gruvbox dark, defined in themes/gruvbox.conf.

Vim Configuration

Notable settings baked into the image:

• Leader key: Space
• Line numbers: Relative + absolute (hybrid)
• Indentation: 4 spaces default, 2 spaces for YAML, JSON, KDL, HTML, CSS, JavaScript
• Undo: Persistent undo files stored in /home/aibox/.vim/undo
• No swap files – clean container environment
• Color column at 88 (Black/PEP8 default)
• Grep program: ripgrep if available (rg --vimgrep --smart-case)
• Netrw: Tree mode, no banner, 25% width
• Colorscheme: desert (ships with vim-runtime, no plugins needed)

Git Configuration

Git config lives at /home/aibox/.config/git/config (XDG path, not ~/.gitconfig). The environment variable GIT_CONFIG_GLOBAL is set in the generated docker-compose.yml to point to this location.

Using a directory mount (rather than a single-file mount) allows a credentials file to coexist alongside config.

AI Coding Agents

AI coding agents (Claude, Codex, Aider, Gemini, and others) are not pre-installed in the base image. They are installed per-project when you select them in the ordered [ai].harnesses list, for example { harness = "claude", enable = true, install = true }.

Audio Support

Set [audio] enabled = true to enable audio bridging. aibox then selects the internal audio-voice recipe and configures the PulseAudio environment for the container. See Audio Support for setup details.

Configuration Persistence

All user configuration is persisted on the host under .aibox-home/ and bind-mounted into the container:

The Dockerfile bakes identical defaults into the image as a fallback. If no mounts are present, the container still works out of the box.

On first aibox init or aibox up, the .aibox-home/ directory is auto-seeded from built-in templates. User-owned files are retained. Files explicitly managed by aibox may be refreshed on aibox apply when their upstream template changes.

Tool credentials saved below /home/aibox/.config, including a GitHub CLI login stored in /home/aibox/.config/gh, therefore survive container replacement and image rebuilds. They remain local secret-bearing files rather than encrypted storage. See GitHub authentication for the security tradeoffs and the recommended scoped-PAT alternative.

File Preview

The base image ships the Yazi configuration and preview plugins. Install the optional preview-archive addon for raster/SVG/PDF/archive helper binaries and preview-enhanced for Markdown, EPS, video, and Ghostscript support. PDF and SVG also support watch-mode preview when the required preview tools are selected.

See the dedicated File Preview page for full documentation, including format coverage, standalone tools (chafa, timg), and the PDF/SVG watch-mode patterns.

Container Entrypoint

CMD ["sleep", "infinity"]

The container stays alive and idle. Both VS Code and aibox up exec into it. tmux is never the container entrypoint – it is launched on attach.

5.2 - Container Configuration

Container Configuration

The [container] section in aibox.toml controls per-project container settings.

Container Identity

[container]
name = "my-project"        # Container name (used by compose)
hostname = "my-project"    # Container hostname
user = "aibox"             # Container user (default: aibox)

The user field determines the non-root user inside the container. The default aibox user (UID 1000) is recommended. Set user = "root" only if needed for specific tools.

aibox apply generates a Compose file with an explicit top-level project name, an explicit service image, and container_name = [container].name. Docker Desktop, OrbStack, and Compose UIs therefore group aibox projects by their project/container names instead of under a generic devcontainer identity.

The generated main service also sets Compose init: true. Compose starts a small init process as PID 1 so orphaned child processes are reaped correctly while the service still runs command: sleep infinity as its long-lived container command. This prevents zombie buildup from tools that spawn helper processes, including bubblewrap-based sandbox helpers.

init: true is part of the Compose Specification. Docker Compose and modern Compose-spec providers support it. podman compose delegates to an external Compose provider, so support depends on the configured provider; if an older provider rejects the key, upgrade the provider rather than removing the reaper from generated projects.

Use the configured container name when writing Compose overrides:

services:
  my-project:
    ports:
      - "8080:80"

Post-Create Command

Run a command after the container is first created:

[container]
post_create_command = "npm install"

This maps to devcontainer.json’s postCreateCommand.

Network Keepalive

Prevent OrbStack/VM NAT from dropping idle connections:

[container]
keepalive = true

This sends a lightweight DNS lookup every 2 minutes via the devcontainer postStartCommand.

Custom Packages, Ports, Volumes, and Environment Variables

Container customizations such as extra packages, port forwarding, volume mounts, and environment variables are handled through standard Docker mechanisms rather than aibox.toml.

Extra Packages — Dockerfile.local

Install additional apt packages by adding them to .devcontainer/Dockerfile.local, which is appended to the generated Dockerfile at build time:

RUN apt-get update && apt-get install -y --no-install-recommends \
    universal-ctags graphviz postgresql-client \
    && rm -rf /var/lib/apt/lists/*

Ports, Volumes, and Environment Variables — docker-compose.override.yml

Use .devcontainer/docker-compose.override.yml to add port mappings, volume mounts, and environment variables:

services:
  my-project:                # must match [container] name in aibox.toml
    ports:
      - "8080:80"
      - "5432:5432"
    volumes:
      - /host/data:/container/data:ro
    environment:
      DATABASE_URL: "postgres://localhost/mydb"
      NODE_ENV: "development"

Both Dockerfile.local and docker-compose.override.yml are scaffolded by aibox init and are never overwritten by aibox apply.

Compose Override

For project-specific services (databases, sidecars, test companions), use Docker Compose’s standard override mechanism. During aibox init, an empty .devcontainer/docker-compose.override.yml is scaffolded with example usage.

Docker Compose automatically merges the override file with the generated docker-compose.yml using a strategic merge — maps (services, environment) are deep-merged by key, lists (ports, volumes) are appended, and scalars (image, command) are replaced.

When aibox apply detects the override file, it wires both files into devcontainer.json so VS Code picks them up.

Example — add a PostgreSQL sidecar:

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: dev
    ports:
      - "5432:5432"

Example — add depends_on to the main service:

services:
  my-project:            # must match [container] name in aibox.toml
    depends_on:
      - postgres

5.3 - Audio Support

Audio Support

aibox can enable audio support for voice-capable tools. Audio is bridged from the container to the host via PulseAudio over TCP, and the required container packages live in the optional audio-voice addon.

Why Audio Matters

Claude Code supports voice interaction. For this to work inside a container, audio output (and optionally input) must be forwarded to the host’s sound system. aibox handles this by installing PulseAudio client utilities in the container and connecting them to a PulseAudio server running on the host.

Architecture

Container                          Host
┌─────────────────────┐     ┌─────────────────────┐
│  Claude Code        │     │  PulseAudio Server   │
│       │             │     │       │              │
│  pulseaudio-utils   │────>│  TCP :4714           │
│  sox                │     │       │              │
│  .asoundrc          │     │  Speakers / Mic      │
└─────────────────────┘     └─────────────────────┘

The container sets PULSE_SERVER to point at the host’s PulseAudio TCP module. Audio data flows over the network socket.

Configuration in aibox.toml

[audio]
enabled = true
backend = "pulseaudio"
install = true
pulse_server = "tcp:host.docker.internal:4714"

When enabled = true, the generated docker-compose.yml sets PULSE_SERVER in the container environment. When install = true, it also selects the internal audio-voice recipe during aibox apply, which installs Sox, PulseAudio client utilities, and ALSA PulseAudio plugins in the container.

Host Setup

The fastest way to set up audio on your host is the built-in CLI command:

# Check if your host is ready
aibox doctor audio

# Automatic setup (macOS: installs PulseAudio, configures TCP, creates launchd agent)
aibox apply audio

aibox apply audio handles:

• Installing PulseAudio via Homebrew (macOS) if not present
• Configuring ~/.config/pulse/default.pa with the TCP module on port 4714
• Creating a launchd agent with KeepAlive so PulseAudio auto-starts and restarts on crash (macOS)
• Loading the TCP module immediately

aibox doctor audio diagnoses: PulseAudio installation, daemon status, TCP module, persistence config, port listening, launchd agent (macOS), and connectivity.

Both commands accept --port to override the default port (4714).

Manual setup

If you prefer manual configuration:

macOS

1. Install PulseAudio:

   brew install pulseaudio
   

2. Enable the TCP module. Add to ~/.config/pulse/default.pa:

   load-module module-native-protocol-tcp port=4714 auth-anonymous=1
   

3. Start PulseAudio:

   pulseaudio --start
   

4. Verify it is listening:

   lsof -i :4714
   

Docker Desktop and OrbStack provide host.docker.internal automatically. For Podman, check your machine’s network configuration — you may need to use the host IP directly:

[audio]
enabled = true
pulse_server = "tcp:192.168.64.1:4714"

Linux

1. PulseAudio is likely already running. Enable the TCP module:

   pactl load-module module-native-protocol-tcp port=4714 auth-ip-acl=127.0.0.1;172.16.0.0/12;10.0.0.0/8;192.168.0.0/16
   

   To make this persistent, add to ~/.config/pulse/default.pa:

   load-module module-native-protocol-tcp port=4714 auth-ip-acl=127.0.0.1;172.16.0.0/12;10.0.0.0/8;192.168.0.0/16
   

2. Use host.docker.internal (Docker 20.10+) or the Docker bridge IP:

   [audio]
   enabled = true
   pulse_server = "tcp:host.docker.internal:4714"
   

Claude Code OAuth in Containers

When running claude auth inside a container with bridge networking (OrbStack, Docker Desktop), the OAuth callback may fail. Claude Code starts a temporary HTTP server on a random ephemeral port to receive the callback, but that port isn’t forwarded to the host browser.

Workaround: Use claude setup-token to authenticate manually, or authenticate on the host first. aibox bind-mounts Claude’s .claude/, .claude.json, and XDG cache/config/state locations, so credentials survive container rebuilds.

The .asoundrc File

The seeded home configuration includes an .asoundrc file at /home/aibox/.asoundrc. This configures ALSA to route through PulseAudio, so applications that use ALSA rather than PulseAudio directly also get audio output when the audio-voice addon is installed.

Troubleshooting

No sound output

1. Verify PulseAudio is running on the host:

   pulseaudio --check && echo "running" || echo "not running"
   

2. Verify the TCP module is loaded:

   pactl list modules | grep module-native-protocol-tcp
   

3. Test from inside the container:

   paplay /usr/share/sounds/freedesktop/stereo/bell.oga
   

   If the file does not exist, use sox to generate a test tone:

   play -n synth 0.5 sine 440
   

Connection refused

The PULSE_SERVER address is not reachable from the container.

• Check that the PulseAudio TCP module is listening on the correct port
• Check that host.docker.internal resolves from inside the container:

  # From inside the container
  getent hosts host.docker.internal
  

• Try using the host’s explicit IP address instead

Audio works but is choppy

This is usually a network or resource issue. PulseAudio over TCP adds latency. Ensure the container has sufficient CPU resources and the host is not under heavy load.

Disabling audio

If you do not need audio, set enabled = false in aibox.toml:

[audio]
enabled = false

This removes the PULSE_SERVER environment variable from the container. The audio packages (sox, pulseaudio-utils) remain installed in the base image but are inert without a server to connect to.

5.4 - File Preview

File Preview

aibox containers ship with Yazi preview configuration and can install TUI-native preview tools for raster images, vector graphics, PDF, archives, and video through optional addons. Several formats also support watch-mode preview, where the rendered output updates automatically whenever the source file changes.

Overview

There are two independent preview mechanisms:

Watch-mode (live-updating preview) is available via the standalone tools — see Watch-Mode Preview.

Yazi File Preview

When you open Yazi (Ctrl+g s from the file manager pane, or via the layout sidebar), files are previewed automatically in the right panel as you navigate. No manual invocation needed.

Supported formats

Raster image, SVG, PDF, archive, and standalone terminal viewers require the preview-archive addon. SQLite, CSV/TSV, and Excel previews require the data-preview addon. Markdown rendering, EPS, and video thumbnails require the preview-enhanced addon, which depends on preview-archive:

aibox set addon preview-archive enabled --apply    # adds chafa, timg, poppler, mutool, entr, p7zip, resvg
aibox set addon data-preview enabled --apply       # adds sqlite3 and csvkit for data previews
aibox set addon preview-enhanced enabled --apply   # adds python3-rich, ffmpeg, ghostscript

How previewer dispatch works

Yazi matches files against a list of prepend_previewers in ~/.config/yazi/yazi.toml. The first matching entry wins:

[plugin]
prepend_previewers = [
    { url = "*.svg", run = "svg" },
    { url = "*.eps", run = "eps" },
    { url = "*.md",  run = "rich-preview" },
    { url = "*.jpg",  run = "image" },
    { url = "*.jpeg", run = "image" },
    { url = "*.png",  run = "image" },
    { url = "*.gif",  run = "image" },
    { url = "*.webp", run = "image" },
    { url = "*.bmp",  run = "image" },
    { url = "*.tiff", run = "image" },
    { url = "*.tif",  run = "image" },
]

Custom plugins (svg.yazi, eps.yazi) live at ~/.config/yazi/plugins/<name>.yazi/init.lua. They are seeded into .aibox-home/.config/yazi/ on first aibox init.

Format notes

SVG — converted to PNG by resvg, a fast standalone Rust-based SVG renderer bundled as a static binary in /usr/local/bin/resvg. The rendered PNG is cached under Yazi’s cache directory. If resvg is absent from PATH, the plugin fails gracefully and Yazi falls back to the text previewer.

EPS — rendered to PNG at 150 DPI by gs (Ghostscript), then displayed as an image. Result is cached.

Markdown — when the preview-enhanced addon is enabled, .md and .markdown files are rendered through rich-preview.yazi, which uses Python Rich for terminal-native Markdown rendering. Without the addon, Yazi falls back to its built-in text/code preview.

PDF — page 1 is rendered by pdftoppm (from poppler-utils). Navigate multi-page documents with Yazi’s built-in PDF plugin controls.

Wide text previews — the seeded Yazi keymap includes a pager shortcut for the selected file using less -R -S. -R preserves ANSI color from rich/code output; -S disables wrapping so long lines can be inspected with horizontal scrolling.

SQLite — sqlite-preview.yazi opens databases read-only through sqlite3 and shows schema objects plus table/view columns. It is enabled only when the data-preview addon is configured.

CSV / TSV / Excel — tabular-preview.yazi formats CSV/TSV with csvlook; .xls and .xlsx are converted with in2csv before formatting. It is enabled only when the data-preview addon is configured.

.excalidraw files — Excalidraw’s native format is JSON. A graphical preview is not possible in a TUI environment. Yazi falls back to the text previewer showing the raw JSON. This is a known limitation — Excalidraw requires a browser to render.

Standalone TUI Viewers

These tools are available directly in the shell for viewing a specific file or integrating into a pipeline when the preview-archive addon is enabled.

chafa — universal image renderer

chafa converts images to terminal graphics using Sixel, Kitty protocol, half-block Unicode, or plain ASCII, auto-detecting the best mode for the current terminal.

# View any raster image
chafa photo.jpg

# Force half-block mode (safe inside tmux)
chafa --format=halfblock diagram.png

# SVG via librsvg (if chafa was compiled with librsvg support)
chafa --format=halfblock logo.svg

# Constrain to a specific cell size
chafa -s 80x40 banner.png

Supported formats: JPEG, PNG, GIF (animated), WebP, BMP, TIFF, AVIF, and more. SVG support depends on whether chafa was built with librsvg — run chafa --version and check for SVG: yes.

timg — terminal image and document viewer

timg renders images, animated GIFs, videos, and PDFs (page by page) directly in the terminal.

# View an image
timg photo.jpg

# View a PDF — renders all pages sequentially
timg document.pdf

# View a specific PDF page (page 2)
timg -p2 document.pdf

# Constrain output size
timg -g 120x40 wide-image.png

# Clear previous output before rendering (useful in watch loops)
timg --clear output.pdf

Supported formats: JPEG, PNG, GIF (animated), WebP, BMP, TIFF, PDF (via MuPDF), video (via ffmpeg).

Watch-Mode Preview

Watch-mode preview automatically re-renders a file whenever it changes on disk. This is particularly useful for LaTeX, Typst, and other document workflows where you write source in one pane and see the rendered output update in real time in another.

The pattern uses entr (an inotify-based file watcher) combined with a rasteriser and timg --clear:

source file changes → entr triggers → rasteriser produces PNG → timg renders PNG in terminal

Install the preview-archive addon to get the watch-mode tools (entr, mupdf-tools, resvg, timg).

PDF watch preview ⟳

Run this in a dedicated pane while editing your LaTeX or Typst source:

pdf-watch output.pdf

pdf-watch wraps the underlying entr + mutool draw + timg --clear pipeline and re-renders page 1 whenever the PDF changes:

ls output.pdf | entr -s 'mutool draw -o /tmp/p.png output.pdf 1 && timg --clear /tmp/p.png'

Yazi also seeds a PDF live-watch binding for selected .pdf files. It invokes pdf-watch so you can start the same live preview directly from the file manager.

Tips:

• Change the final 1 to preview a different page number.
• To watch all pages: mutool draw -o /tmp/p-%d.png output.pdf (produces /tmp/p-1.png, /tmp/p-2.png, …); then timg --clear /tmp/p-*.png.
• Add -r 150 to mutool draw for higher resolution (default is 72 DPI).
• Use timg -g 120x40 to constrain the rendered size to fit a specific pane.

SVG watch preview ⟳

ls diagram.svg | entr -s 'resvg diagram.svg /tmp/d.png && timg --clear /tmp/d.png'

resvg converts the SVG to a high-fidelity PNG. Unlike Inkscape or rsvg-convert, resvg is a static binary with no runtime dependencies and typically renders in under 100 ms for typical diagrams.

General pattern

The same entr + rasteriser + timg pattern works for any file format that has a headless rasteriser:

# Watch a file and re-render on change
ls <file> | entr -s '<rasterise-command> && timg --clear <output.png>'

Format Coverage Summary

5.5 - Runtime Operations

Runtime Operations

The generated devcontainer is standard Compose output, but the normal workflow should go through aibox so generated files, runtime home state, and diagnostics stay aligned.

Start and Attach

aibox up
aibox up --layout focus
aibox up --apply

aibox up creates or starts the container and attaches through tmux. Use --layout for a one-session layout override. Use --apply when you want aibox to reconcile configuration before starting.

Stop or Remove

aibox down
aibox delete runtime

down stops the Compose project. delete runtime removes the container while preserving project files and .aibox-home/.

Rebuild

aibox apply
aibox apply --no-cache
aibox apply --config-only

Use --no-cache after base-image, addon, or package-cache issues. --rebuild is kept as a visible alias for the same behavior. Use --config-only when you only want to regenerate files, and in processkit mode refresh processkit content, without building the image. In harness-only projects, --config-only regenerates config/runtime surfaces without processkit content work.

Inspect Runtime State

aibox get runtime
aibox get runtime --resources
aibox get runtime --resources -o json
aibox describe runtime

The resource snapshot is designed for low-dependency environments. It reads cgroupfs and procfs directly instead of relying on tools such as ps or free being installed.

Key fields:

An oom_kill_count above zero is strong evidence that a missing agent or terminated tool was killed by the operating system rather than by the CLI.

With current processkit releases, [ai.mcp.gateway].mode = "auto" registers a processkit-gateway stdio proxy for MCP-capable harnesses. The proxy starts the local gateway on demand when no listener exists, so generated devcontainer startup no longer has to supervise one Python process per skill in the default mode. Use separate only when a harness needs the older one-server-per-skill layout. Harness-only projects do not register the processkit gateway.

Resource Thresholds

Configure warning thresholds in aibox.toml:

[container.resource_thresholds]
memory_mib_warn = 4096
process_count_warn = 400
processkit_mcp_python_warn = 50

aibox doctor uses these values when reporting runtime pressure.

Compose Identity

Generated Compose output includes:

• a top-level project name derived from [container].name
• an explicit image name
• a main service named after the project
• container_name = [container].name
• init: true for PID 1 process reaping

This keeps Docker Desktop, OrbStack, and Compose UIs from grouping unrelated aibox projects under a generic devcontainer identity.

Existing Containers After Generator Changes

aibox apply rewrites generated files, but it does not magically replace a running container that was created from older Compose output. Recreate the runtime when a change affects process model, mounts, image labels, init behavior, or service identity:

aibox down
aibox apply
aibox up

If a container has already accumulated zombie processes, the fix is still a runtime recreate. A new generated init: true service can reap future orphaned children, but it cannot change PID 1 in an already-created container.

Common Symptoms

Podman Notes

Podman support depends on the Compose provider behind podman compose. Generated files follow the Compose Specification, including init: true. If an older provider rejects a spec key, upgrade the provider instead of removing the generated setting.

6 - Tutorials

Tutorials

These tutorials start with an empty directory and finish with a working result. Use them when you want the complete sequence rather than a command reference.

6.1 - Create a local project with processkit

Create a local project with processkit

This tutorial starts with an empty directory, deploys a workspace through the v1 Compose backend, and installs the processkit v1 process base into the project. Both products are prereleases, so the example uses exact versions.

Before you begin

Install a Docker- or Podman-compatible Compose runtime, curl, tar, and sha256sum. Then install the exact aibox v1 release shown on the releases page:

curl -fsSL https://raw.githubusercontent.com/projectious-work/aibox/main/scripts/install.sh |
  VERSION=1.0.0-alpha.1 bash
aibox --version

If that release is not published yet, use the latest v1 prerelease shown on the releases page and substitute its version below.

Scaffold the project

mkdir hello-aibox
cd hello-aibox
aibox init hello-aibox --context-mode harness-only --harness codex --no-container

harness-only keeps aibox’s legacy processkit installer out of the project. The process base is installed later by the processkit v1 CLI, through its own native boundary.

Add an application and image source:

# image-source/Containerfile
FROM docker.io/library/alpine:3.22
CMD ["sh", "-c", "while true; do date; sleep 30; done"]

Create image-source/ and save the file there. Build and push the image to a registry you can access:

aibox image build --push --output json

Before running that command, add a complete [orchestration] contract to aibox.toml. Replace the image reference, digest, and owner with your values:

[orchestration]
enabled = true

[orchestration.image]
reference = "ghcr.io/YOUR-ACCOUNT/hello-aibox:dev"
digest = "sha256:0000000000000000000000000000000000000000000000000000000000000000"
platform = "linux-amd64"

[orchestration.image.build]
context = "image-source"
dockerfile = "Containerfile"

[orchestration.fleet]
name = "hello-aibox"
services = [{ name = "workspace" }]

[orchestration.target]
backend = "compose"
reference = "docker-context:default"
scope = "hello-aibox"

[orchestration.deployment]
name = "hello-aibox-local"
owner_id = "YOUR-STABLE-OWNER-ID"

[[orchestration.connections]]
name = "shell"
service = "workspace"
transport = "compose-exec"
command = ["sh"]

The first build uses that syntactically valid, all-zero placeholder digest. After the push, copy the returned registry manifest digest into orchestration.image.digest. The deployment never consumes a mutable tag by itself.

Plan and deploy locally

aibox config compile --output json
aibox deploy plan --output json
aibox deploy apply --output json
aibox deploy status
aibox connect shell

The plan is read-only. Apply creates only the Compose resources carrying this deployment’s ownership labels and writes its local deployment record.

Install the processkit process base

Download one exact processkit v1 release, verify both release assets, and run the native installer. The filenames and checksums are published with every processkit release.

PROCESSKIT_VERSION=v1.0.0-alpha.4
PROCESSKIT_TARGET=aarch64-unknown-linux-gnu
PROCESSKIT_DIR=.aibox/processkit-release
mkdir -p "${PROCESSKIT_DIR}"

curl -fL -o "${PROCESSKIT_DIR}/processkit.tar.gz" \
  "https://github.com/projectious-work/processkit/releases/download/${PROCESSKIT_VERSION}/processkit-${PROCESSKIT_VERSION}.tar.gz"
curl -fL -o "${PROCESSKIT_DIR}/processkit.tar.gz.sha256" \
  "https://github.com/projectious-work/processkit/releases/download/${PROCESSKIT_VERSION}/processkit-${PROCESSKIT_VERSION}.tar.gz.sha256"
curl -fL -o "${PROCESSKIT_DIR}/processkit" \
  "https://github.com/projectious-work/processkit/releases/download/${PROCESSKIT_VERSION}/processkit-${PROCESSKIT_VERSION}-${PROCESSKIT_TARGET}"
curl -fL -o "${PROCESSKIT_DIR}/processkit.sha256" \
  "https://github.com/projectious-work/processkit/releases/download/${PROCESSKIT_VERSION}/processkit-${PROCESSKIT_VERSION}-${PROCESSKIT_TARGET}.sha256"

(cd "${PROCESSKIT_DIR}" && sed 's/  .*/  processkit.tar.gz/' processkit.tar.gz.sha256 | sha256sum --check)
(cd "${PROCESSKIT_DIR}" && sed 's/  .*/  processkit/' processkit.sha256 | sha256sum --check)
chmod +x "${PROCESSKIT_DIR}/processkit"
tar -xzf "${PROCESSKIT_DIR}/processkit.tar.gz" -C "${PROCESSKIT_DIR}"

"${PROCESSKIT_DIR}/processkit" install \
  --root . \
  --distribution "${PROCESSKIT_DIR}/processkit-${PROCESSKIT_VERSION}" \
  --profile managed \
  --harness codex \
  --yes
"${PROCESSKIT_DIR}/processkit" verify --root . --json

Choose the target matching your host (aarch64-unknown-linux-gnu is the current v1 alpha target). The managed profile installs the shared process base, canonical AGENTS.md, and runtime policy. verify checks installed provenance and managed-path drift without changing the project.

Commit aibox.toml, aibox.lock, AGENTS.md, and the installed context/ tree. Do not commit .aibox/processkit-release/; it is only a download staging directory.

Clean up

aibox deploy destroy --output json

Destroy refuses resources that do not match the recorded identity and ownership labels.

7 - Addons

7.1 - Overview

Addons

aibox uses the Debian runtime image family (base-debian-v0.26.x for legacy releases, base-debian-runtime-v0.27.0+ after the image-tag cutover) with 31 composable addons that install language runtimes, tool bundles, documentation frameworks, and AI coding agents into your container.

Managing Addons

Via CLI

# See all available addons
aibox get addon

# Add an addon (updates aibox.toml and runs apply)
aibox set addon python

# Remove an addon
aibox delete addon python

# View addon details (tools, versions)
aibox describe addon rust

# Emit the machine-readable addon catalog index
aibox describe addon-catalog -o json

Via aibox.toml

[addons.python.tools]
python = { version = "3.14" }
uv = { version = "0.12.0" }

[addons.rust.tools]
rustc = { version = "1.97.1" }
clippy = {}
rustfmt = {}

[addons.node.tools]
node = { version = "26" }
pnpm = { version = "11.18.0" }

Each addon has default-enabled tools that are included automatically, and optional tools you can enable explicitly. Tools with version selection let you pick from curated, tested versions.

aibox describe addon-catalog -o json emits the stable aibox.addon-catalog.v0 index used by downstream automation. It includes each addon’s profile intent, automation usage class, supported aibox profiles, exported surfaces, dependencies, and tool metadata. Canonical processkit Artifact{kind=addon-spec} emission remains gated on the upstream processkit schema release.

After editing aibox.toml, run aibox apply to regenerate the Dockerfile and rebuild.

Available Addons

Language Runtimes

Tool Bundles

Documentation Frameworks

AI Harnesses

AI harnesses are selected under [ai], not as public addon blocks. aibox still uses internal install recipes for container CLIs when install = true.

[ai]
harnesses = [
  { harness = "claude", enable = true, install = true },
  { harness = "codex", enable = true, install = true, version = "latest" },
]

Legacy [addons.ai-*.tools] entries are accepted for compatibility, but fresh scaffolding keeps AI configuration in the [ai] section.

Addons and Skills

As of v0.16.0, all skills live in processkit. Projects using context.mode = "processkit" install processkit skills under context/skills/ independently from addons. Projects using context.mode = "harness-only" do not install processkit skills at all. There is no longer an addon-driven “auto-deploy a skill” mechanism.

The relevant skills for each addon’s tooling are still in the catalogue — agents pick them up via skill descriptions, not via addon membership:

See Skills (via processkit) for the full split.

How Addons Work

When you run aibox apply, the CLI:

1. Reads [addons] from aibox.toml
2. Looks up each addon definition from YAML files in ~/.config/aibox/addons/
3. Merges your tool selections with addon defaults
4. Generates Dockerfile builder stages (for heavy builds like Rust, LaTeX)
5. Generates runtime RUN/COPY commands
6. Builds the container image

Addons that need compilation (Rust, LaTeX, infrastructure, Kubernetes) use multi-stage Docker builds – heavy compilation happens in isolated builder stages, and only the final binaries are copied into the runtime image.

Addon Definition Format

Addon definitions are YAML files stored in ~/.config/aibox/addons/ with category subdirectories (languages/, tools/, docs/, ai/). They are installed automatically by the install script and updated when you upgrade aibox.

Extra Packages

For one-off apt packages not covered by addons, use extra_packages:

[container]
extra_packages = ["universal-ctags", "graphviz", "postgresql-client"]

These are installed during aibox apply via the generated Dockerfile. They persist across container restarts but are reinstalled on image rebuild.

Version Selection

Each tool in an addon has a curated list of supported versions. Use aibox describe addon <name> to see available versions:

$ aibox describe addon python
Add-on: python
Recipe version: 1.0.0

  TOOL      DEFAULT    VERSION  SUPPORTED
  python        yes       3.14  3.12, 3.13, 3.14
  uv            yes    0.12.0  0.7, 0.11.10, 0.11.11, 0.11.15, 0.11.19, 0.11.26, 0.11.32, 0.12.0
  poetry         no      2.4.1  1.8, 2.0, 2.4.1
  pdm            no     2.28.0  2.22, 2.26.9, 2.27.0, 2.28.0

Tools marked “DEFAULT: yes” are included automatically when you set the addon. Tools marked “no” must be explicitly listed in your aibox.toml to be installed.

7.2 - Language Runtimes

Language Runtime Addons

Language runtimes install compilers, interpreters, and package managers into your container.

Python

[addons.python.tools]
python = { version = "3.14" }   # 3.12, 3.13, 3.14
uv = { version = "0.12.0" }    # 0.7, 0.11.10, 0.11.11, 0.11.15, 0.11.19, 0.11.26, 0.11.32, 0.12.0
# poetry = { version = "2.4.1" } # Optional: 1.8, 2.0, 2.4.1
# pdm = { version = "2.28.0" }   # Optional: 2.22, 2.26.9, 2.27.0, 2.28.0

Installs Python, pip, venv, and uv (fast package manager). The base image pins uv to the curated default instead of following a floating latest image tag. Poetry and PDM are available but not enabled by default.

Rust

[addons.rust.tools]
rustc = { version = "1.97.1" }  # 1.90, 1.91, 1.92, 1.93, 1.94, 1.94.1, 1.96.0, 1.96.1, 1.97.1
clippy = {}                     # Linter (no version selection)
rustfmt = {}                    # Formatter (no version selection)

Installs the Rust toolchain via rustup with clippy and rustfmt. Uses a multi-stage Docker build — compilation happens in a builder stage and only the toolchain is copied to the runtime image.

Node.js

[addons.node.tools]
node = { version = "26" }       # 20, 22, 24, 26
pnpm = { version = "11.18.0" }  # 9, 10, 11.1.3, 11.5.2, 11.10.0, 11.17.0, 11.18.0
# yarn = { version = "4.17.0" } # Optional: 4, 4.16.0, 4.17.0
# bun = { version = "1.3.14" }  # Optional

Installs Node.js via NodeSource, plus pnpm as default package manager. Yarn and Bun are available but not enabled by default.

Go

[addons.go.tools]
go = { version = "1.26.5" }     # 1.25, 1.26, 1.26.3, 1.26.4, 1.26.5

Installs Go and sets up GOPATH.

Typst

[addons.typst.tools]
typst = { version = "0.15.0" }  # 0.13.1, 0.14.2, 0.15.0

Installs the Typst typesetting system for modern document creation.

LaTeX

[addons.latex.tools]
texlive-core = {}               # Base TeX Live installation
texlive-recommended = {}        # Common packages
texlive-fonts = {}              # Font packages
biber = {}                      # Bibliography processor
texlive-code = {}               # Code listing packages
texlive-diagrams = {}           # TikZ, PGF, circuit diagrams
texlive-math = {}               # Math packages
# texlive-music = {}            # Optional: LilyPond, MusiXTeX
# texlive-chemistry = {}        # Optional: chemfig, mhchem

Installs TeX Live via a multi-stage Docker build. The full TeX Live installation happens in a builder stage and only the final tree is copied to the runtime image, keeping layer sizes manageable.

Use the LaTeX build and preview workflow to define named documents, run reproducible latexmk builds and watchers inside the development container, and serve completed PDFs through the read-only EmbedPDF sidecar.

Emoji rendering with LuaLaTeX

The runtime image ships fonts-noto-color-emoji so emoji glyphs render correctly in LuaLaTeX documents. To wire it up, add the following to your preamble:

\directlua{luaotfload.add_fallback("emojifallback",{"NotoColorEmoji:mode=harf;"})}
\setmainfont{FreeSans}[Scale=0.95,RawFeature={fallback=emojifallback}]

Without the fallback configured, emoji characters render as missing-glyph boxes even though the font is installed.

7.3 - Tool Bundles

Tool Bundle Addons

Tool bundles install infrastructure, orchestration, and cloud CLI tools.

Git UI

[addons.git-ui.tools]
gh = {}        # GitHub CLI
lazygit = {}   # Interactive Git TUI

The git-ui addon is optional. Select it when a project needs GitHub CLI automation or lazygit inside the container; omit it to avoid installing those tools. This aibox repo may enable it for maintenance workflows such as release checks and GitHub issue/release work, but downstream projects do not need it by default.

Preview and Archive Tools

[addons.preview-archive.tools]
chafa = {}
timg = {}
poppler = {}
mupdf = {}
entr = {}
p7zip = {}
resvg = {}

preview-archive contains the terminal image/PDF/SVG/archive helper binaries used by Yazi previews and watch-mode document workflows. Keep it disabled for lean headless projects that do not inspect media or generated documents inside the terminal.

preview-enhanced layers Markdown, EPS, video, and Ghostscript support on top of preview-archive.

Data Preview

[addons.data-preview.tools]
sqlite3 = {}
csvkit = {}

data-preview adds read-only SQLite inspection and CSV, TSV, XLS, and XLSX formatting for the generated Yazi preview plugins.

Audio and Voice

[audio]
enabled = true

Audio bridging uses the internal audio-voice recipe for Sox, PulseAudio client tools, and ALSA PulseAudio plugins. aibox selects this recipe automatically when [audio] enabled = true and install = true; projects normally do not need to add [addons.audio-voice.tools] manually.

Infrastructure

[addons.infrastructure.tools]
opentofu = {}      # Infrastructure-as-code (Terraform alternative)
ansible = {}       # Configuration management
packer = {}        # Machine image builder

OpenTofu defaults to 1.12.5, Packer to 1.16.0, and Ansible to 14.2.0. OpenTofu and Packer are installed in a multi-stage builder. Ansible is installed via pip.

Kubernetes

[addons.kubernetes.tools]
kubectl = {}       # Kubernetes CLI
helm = {}          # Package manager
kustomize = {}     # Configuration customization
# k9s = {}         # Optional: terminal UI for Kubernetes

kubectl defaults to 1.36.3, Helm to 4.2.3, Kustomize to 5.8.1, and k9s to 0.51.0. All tools are downloaded as static binaries in a multi-stage builder.

Cloud Providers

AWS

[addons.cloud-aws.tools]
aws-cli = {}

Installs the AWS CLI v2.

Google Cloud

[addons.cloud-gcp.tools]
gcloud-cli = {}

Installs the Google Cloud CLI via the official APT repository.

Azure

[addons.cloud-azure.tools]
azure-cli = {}

Installs the Azure CLI via pip.

7.4 - Documentation Frameworks

Documentation Framework Addons

Documentation addons install static site generators and documentation tools.

Current curated pins are Docusaurus 3.10.1, Hugo 0.164.0, mdBook 0.5.4, MkDocs 1.6.1 with Material 9.7.7, and Zensical 0.0.52. Starlight remains scaffolded through the upstream create-starlight package.

Example

[addons.docs-docusaurus.tools]
docusaurus = {}

After aibox apply, the documentation tool is available inside the container. Initialize your docs project as usual (e.g., npx create-docusaurus@latest docs classic).

7.5 - LaTeX Build and Preview

LaTeX Build and Preview

The latex addon supplies TeX Live, latexmk, bibliography tools, fonts, and common package groups. aibox adds a project-level build contract on top so humans and agents use the same engine, cache, output paths, and document names.

Configure documents

Enable the addon and declare one or more documents:

[addons.latex.tools]
texlive-core = {}
texlive-recommended = {}
texlive-fonts = {}
biber = {}

[latex]
engine = "lualatex"
cache_dir = ".latex-cache"
options = []

[[latex.documents]]
name = "overview"
source = "docs/overview/overview.tex"
output_dir = ".latex-cache/overview"
options = []
extra_dirs = []

[[latex.documents]]
name = "appendix"
source = "docs/appendix/appendix.tex"
output_dir = ".latex-cache/appendix"
options = ["-shell-escape"]
extra_dirs = ["figs"]

[latex.preview]
enabled = true
engine = "embedpdf"
bind = "127.0.0.1"
port = 8765
# document = "overview" # optional compatibility-route default
allow_public = false

Supported engines are lualatex, pdflatex, xelatex, and tectonic. Continuous watch mode uses latexmk, so tectonic configurations support one-shot builds only.

Build and watch

Run these commands inside the development container. aibox apply generates them under .aibox-home/.local/bin, which is already on the container PATH:

aibox-latex-build                 # every configured document
aibox-latex-build overview        # one configured document
aibox-latex-watch overview        # foreground watcher; stop with Ctrl-C

Builds use non-interactive, file-and-line-error, halt-on-error flags. Watch mode adds latexmk -pvc -view=none, leaving browser preview ownership to the sidecar. TEXMFVAR and TEXMFCONFIG live below latex.cache_dir, so TeX does not write mutable state to the user’s global TeX tree.

Compilation never runs on the host or in the preview sidecar. The scripts use the TeX installation in the main development container, keep the watch process in the foreground, and write PDFs below each configured output_dir. Run one watcher per document when several documents should rebuild concurrently.

Running aibox apply adds a concise, conditional aibox-managed LaTeX section to AGENTS.md. This is the primary instruction surface for AI agents and gives them the configured container commands, companion health check, preview URLs, and document paths without adding another root-level guidance file.

Live PDF preview

When preview is enabled, aibox apply generates a dedicated Compose sidecar and port mapping. Host-side aibox up starts that sidecar, which serves every configured document from the project workspace mounted read-only. The sidecar does not contain a TeX toolchain and cannot modify the workspace. latex.preview.document chooses the preferred document used by compatibility routes; it does not exclude the others.

Inspect its logs with:

docker compose -f .devcontainer/docker-compose.yml logs <project-container-name>-latex-preview

aibox down stops the sidecar with the rest of the Compose project. A subsequent aibox up starts it again. With multiple documents, the root URL displays a selection page. Each PDF also has a stable direct URL:

http://127.0.0.1:8765/
http://127.0.0.1:8765/documents/overview/
http://127.0.0.1:8765/documents/appendix/

The stable URL is http://127.0.0.1:8765/. The service watches the completed PDF output for every document, waits for its metadata to remain stable across multiple polls, and then sends a document-specific SSE revision event. This prevents the browser from fetching a partially-written PDF. The browser requests a versioned PDF URL on reload so a stale cache cannot hide a new build. Page and zoom state are retained separately for each document.

The viewer uses the pinned @embedpdf/snippet browser package. Its default toolbar provides navigation, zoom, search, thumbnails, and outline support when the PDF contains an outline. The browser must be able to reach jsDelivr to load the pinned viewer module; the PDF itself is served by the local preview sidecar.

Host and network access

The preview helper listens on 0.0.0.0:8765 inside its isolated sidecar. The generated Compose mapping publishes that internal port only on the configured host address and port. The secure default is therefore accessible from the host browser but not from other machines:

[latex.preview]
enabled = true
bind = "127.0.0.1"
port = 8765
allow_public = false

Run aibox apply after changing this configuration, then run aibox up on the host. Do not add a manual override mapping; aibox generates 127.0.0.1:8765:8765 in .devcontainer/docker-compose.yml.

For access from another machine on the local network, explicitly expose the unauthenticated endpoint:

[latex.preview]
enabled = true
bind = "0.0.0.0"
port = 8765
allow_public = true

This generates 0.0.0.0:8765:8765. Open http://<host-ip>:8765/ and ensure the host firewall permits the port. Prefer the loopback default plus SSH forwarding when possible.

Remote hosts over SSH

The default bind address is loopback and is suitable for SSH forwarding:

ssh -L 8765:127.0.0.1:8765 user@remote-host

Then open http://127.0.0.1:8765/ locally. Publishing on a non-loopback host address is rejected unless allow_public = true is also set. That opt-in exposes an unauthenticated PDF endpoint; prefer an SSH tunnel.

8 - AI Providers

8.1 - Claude

Claude Code

Claude Code by Anthropic is a terminal-based AI coding assistant. It’s the default provider in aibox.

Setup

[ai]
harnesses = [
  { harness = "claude", enable = true, install = true },
]

Run aibox apply, then inside the container:

claude   # Launches Claude Code CLI

On first launch, Claude prompts for authentication via browser login.

Configuration

Claude’s configuration, cache, and account state are persisted under .aibox-home/ and mounted into the container. aibox preserves Claude’s primary config directory (.claude/), top-level account state (.claude.json), and XDG state/cache locations used by current Claude Code releases.

Key files:

• .claude/settings.json — Claude Code settings
• .claude.json — Claude Code account/install state
• .cache/claude*, .config/claude/, .local/share/claude/, .local/state/claude/ — Claude Code login and runtime state
• .claude/projects/ — Per-project memory and context
• .claude/skills/<name>/SKILL.md — generated processkit command shims when Claude is enabled in processkit mode

The generated .claude/skills/ entries are adapters. The canonical skill instructions remain in context/skills/. Harness-only projects do not generate processkit command shims.

Audio (Voice)

Claude Code supports voice input. To enable it, configure audio bridging:

[audio]
enabled = true

MCP Integration

Claude Code’s native MCP client reads .mcp.json. aibox generates .mcp.json automatically on aibox apply, merging processkit built-in servers in processkit mode, team servers from aibox.toml [ai.mcp], and personal servers from .aibox-local.toml [mcp].

.mcp.json is gitignored — it is regenerated on every aibox apply and must not be committed.

To add MCP servers:

# aibox.toml — team-shared servers
[[ai.mcp.servers]]
name    = "github"
command = "npx"
args    = ["-y", "@modelcontextprotocol/server-github"]

# .aibox-local.toml — personal servers (not committed)
[[mcp.servers]]
name    = "my-internal-tool"
command = "npx"
args    = ["-y", "@acme/internal-mcp-server"]

tmux Integration

When Claude is configured as a provider, tmux layouts include a dedicated Claude pane:

• dev layout: Claude gets its own window
• focus layout: Claude gets its own window
• cowork layout: Claude appears in a side-by-side pane next to the editor

8.2 - Aider

Aider

Aider is an open-source AI pair programming tool that works with multiple LLM providers from the terminal.

Setup

[ai]
harnesses = [
  { harness = "aider", enable = true, install = true },
]

Run aibox apply, then inside the container:

aider    # Launches Aider CLI

API Key

Aider requires an API key for the LLM provider you want to use. Set it in your environment:

[container.environment]
ANTHROPIC_API_KEY = "sk-ant-..."
# Or for OpenAI:
# OPENAI_API_KEY = "sk-..."

Alternatively, create a .aider.conf.yml in .aibox-home/.aider/.

Configuration

Aider’s configuration is persisted in .aibox-home/.aider/, mounted at /home/aibox/.aider/.

Installation

Aider is installed via uv tool install aider-chat — a fast, isolated Python tool installation.

8.3 - Gemini

Gemini

Gemini CLI is Google’s command-line interface for Gemini AI models.

Setup

[ai]
harnesses = [
  { harness = "gemini", enable = true, install = true },
]

Run aibox apply, then inside the container:

gemini   # Launches Gemini CLI

API Key

[container.environment]
GOOGLE_API_KEY = "..."

Configuration

Gemini’s configuration is persisted in .aibox-home/.gemini/, mounted at /home/aibox/.gemini/.

MCP Integration

Gemini CLI reads .gemini/settings.json. aibox generates this file automatically on aibox apply, merging processkit built-in servers in processkit mode, team servers from aibox.toml [ai.mcp], and personal servers from .aibox-local.toml [mcp].

.gemini/settings.json is gitignored — it is regenerated on every aibox apply and must not be committed.

To add MCP servers:

# aibox.toml — team-shared servers
[[ai.mcp.servers]]
name    = "github"
command = "npx"
args    = ["-y", "@modelcontextprotocol/server-github"]

# .aibox-local.toml — personal servers
[[mcp.servers]]
name    = "my-internal-tool"
command = "npx"
args    = ["-y", "@acme/internal-mcp-server"]

Installation

Gemini CLI is installed via npm (npm install -g @google/generative-ai-cli), with a pip fallback.

8.4 - Mistral

Mistral (SDK)

Mistral AI provides large language models via Python SDK.

Setup

[ai]
model_providers = ["mistral"]

[addons.ai-mistral.tools]
mistral = {}

mistral is retained as a legacy harness value for old configs, but it is not a current interactive CLI harness. Use the addon directly for SDK installs. Run aibox apply. Inside the container the mistralai Python SDK is available for scripting:

from mistralai import Mistral
client = Mistral(api_key="...")

API Key

[container.environment]
MISTRAL_API_KEY = "..."

MCP Integration

aibox generates .mcp.json (the Claude Code MCP format) on aibox apply when a compatible harness is enabled, merging processkit built-in servers in processkit mode, team servers from aibox.toml [ai.mcp], and personal servers from .aibox-local.toml [mcp]. A custom Mistral SDK-based tool you build can read MCP server registrations from this file.

.mcp.json is gitignored — it is regenerated on every aibox apply and must not be committed.

Installation

The Mistral AI SDK is installed via pip (pip install --no-cache-dir mistralai).

8.5 - OpenAI (Codex CLI)

OpenAI Codex CLI

Codex CLI is OpenAI’s open-source terminal coding agent. Built in Rust, GA since April 2025.

Setup

[ai]
harnesses = [
  { harness = "codex", enable = true, install = true },
]

Run aibox apply, then inside the container:

codex    # Launches OpenAI Codex CLI

API Key

[container.environment]
OPENAI_API_KEY = "sk-..."

Alternatively, use a ChatGPT Plus/Pro/Team/Enterprise account — Codex prompts for authentication on first launch.

Configuration

Codex’s home-directory state is persisted in .aibox-home/.codex/, mounted at /home/aibox/.codex/. This survives devcontainer rebuilds, so device sign-in only needs to be completed once per host cache unless you clear it.

Key files:

• .aibox-home/.codex/auth.json — cached ChatGPT/device authentication reused across rebuilds
• .aibox-home/.codex/rules/ — home-directory Codex rules and local state
• .aibox-home/.codex/sessions/ — Codex session history
• .aibox-home/.codex/prompts/pk-*.md — generated processkit custom-prompt aliases

Separately, aibox also generates project-local .codex/config.toml MCP server registration. In processkit mode it also generates .codex/hooks.json processkit hook configuration.

processkit commands

After aibox apply, processkit workflows are available through both Codex invocation surfaces:

• Type $pk-resume, $pk-doctor, and similar names to invoke the generated project skills under .agents/skills/. You can also select them through /skills.
• Type /prompts:pk-resume, /prompts:pk-doctor, and similar names to use the generated custom-prompt aliases persisted under .aibox-home/.codex/prompts/.

Codex reserves top-level slash commands and does not support registering a custom /pk-resume command. Custom prompts always use the /prompts: namespace. Restart the Codex session after the first aibox apply if newly generated prompt aliases do not appear immediately.

MCP Integration

Codex has a native MCP client. aibox generates .codex/config.toml automatically on aibox apply, merging processkit MCP entries in processkit mode, team servers from aibox.toml [ai.mcp], and personal servers from .aibox-local.toml [mcp]. With current processkit releases and [ai.mcp.gateway].mode = "auto", Codex uses the processkit-gateway stdio proxy instead of one Python process per skill.

.codex/config.toml and .codex/hooks.json are gitignored — they are regenerated on every aibox apply and must not be committed.

To add MCP servers:

# aibox.toml — team-shared servers
[[ai.mcp.servers]]
name    = "github"
command = "npx"
args    = ["-y", "@modelcontextprotocol/server-github"]

# .aibox-local.toml — personal servers
[[mcp.servers]]
name    = "my-internal-tool"
command = "npx"
args    = ["-y", "@acme/internal-mcp-server"]

Installation

Codex CLI is installed via npm (npm install -g @openai/codex). To pin a specific version, set it in aibox.toml:

[ai]
harnesses = [
  { harness = "codex", enable = true, install = true, version = "0.1.0" },
]

Sandbox prerequisites

aibox images include Debian’s bubblewrap package so Codex can use the OS-provided Linux sandbox helper instead of falling back to its vendored copy. Codex still needs the container runtime and host kernel to allow unprivileged user namespaces; if namespace creation is blocked, Codex can start but sandboxed shell commands fail before the project command runs.

The preferred fix is to enable unprivileged user namespaces on the host or container runtime. Avoid privileged: true and avoid adding SYS_ADMIN to the main development container for Codex; those grants are broader than Codex’s bubblewrap sandbox requires. When Codex is selected, generated docker-compose.yml includes a narrow security_opt: seccomp=unconfined fallback because Docker/Podman seccomp profiles can block bubblewrap before the project command runs:

services:
  <container-name>:
    security_opt:
      - seccomp=unconfined

This does not grant privileged or SYS_ADMIN; it only relaxes the runtime syscall filter enough for user-namespace creation. Keep Codex in workspace-write with approvals.

aibox doctor checks the Codex sandbox posture when Codex is selected. It verifies that bwrap/bubblewrap is available, runs a user-namespace smoke probe that matches Codex’s sandbox requirement, warns if the generated service is missing Compose init: true, and warns if the main aibox service uses broad grants such as privileged: true or SYS_ADMIN.

See OpenAI’s Codex sandbox prerequisites for the upstream requirements.

8.6 - Copilot (GitHub)

GitHub Copilot CLI

GitHub Copilot CLI is GitHub’s terminal coding agent. GA since February 2026, validated as a Dev Container feature.

Setup

[ai]
harnesses = [
  { harness = "copilot", enable = true, install = true },
]

Run aibox apply, then inside the container:

copilot /login   # Authenticate on first launch
copilot          # Launches GitHub Copilot CLI

Requirements

A GitHub Copilot subscription (Individual, Business, or Enterprise) is required.

Configuration

Copilot’s configuration is persisted in .aibox-home/.copilot/, mounted at /home/aibox/.copilot/.

Key files:

• .copilot/config.json — Copilot settings (overridable via COPILOT_HOME)

MCP Integration

GitHub Copilot CLI reads .mcp.json (the Claude Code MCP format). aibox generates .mcp.json automatically on aibox apply, merging processkit built-in servers in processkit mode, team servers from aibox.toml [ai.mcp], and personal servers from .aibox-local.toml [mcp].

.mcp.json is gitignored — it is regenerated on every aibox apply and must not be committed.

To add MCP servers:

# aibox.toml — team-shared servers
[[ai.mcp.servers]]
name    = "github"
command = "npx"
args    = ["-y", "@modelcontextprotocol/server-github"]

# .aibox-local.toml — personal servers
[[mcp.servers]]
name    = "my-internal-tool"
command = "npx"
args    = ["-y", "@acme/internal-mcp-server"]

Installation

GitHub Copilot CLI is installed via npm (npm install -g @github/copilot).

8.7 - Continue

Continue CLI

Continue is an open-source, provider-agnostic coding agent CLI. Designed for headless environments and containers (Apache 2.0).

Setup

[ai]
harnesses = [
  { harness = "continue", enable = true, install = true },
]

Run aibox apply, then inside the container:

cn          # Interactive mode
cn -p "..."  # Headless/non-interactive mode (great for scripts and CI)

Note: the binary is cn, not continue.

API Key

Continue is provider-agnostic — configure the LLM you want to use:

[container.environment]
CONTINUE_API_KEY = "..."   # Generic key for headless use
# Or provider-specific:
# ANTHROPIC_API_KEY = "sk-ant-..."
# OPENAI_API_KEY = "sk-..."

Configuration

Continue’s configuration is persisted in .aibox-home/.continue/, mounted at /home/aibox/.continue/.

MCP Integration

Continue has a native MCP client with a per-server file model. aibox generates files in .continue/mcpServers/ (one file per server) automatically on aibox apply, merging processkit built-in servers in processkit mode, team servers from aibox.toml [ai.mcp], and personal servers from .aibox-local.toml [mcp].

.continue/mcpServers/ is gitignored — it is regenerated on every aibox apply and must not be committed.

To add MCP servers:

# aibox.toml — team-shared servers
[[ai.mcp.servers]]
name    = "github"
command = "npx"
args    = ["-y", "@modelcontextprotocol/server-github"]

# .aibox-local.toml — personal servers
[[mcp.servers]]
name    = "my-internal-tool"
command = "npx"
args    = ["-y", "@acme/internal-mcp-server"]

Installation

Continue CLI is installed via npm (npm install -g @continuedev/cli).

9 - Project Context

9.1 - Context Overview

Context System Overview

The aibox context system controls what project-level instructions and structured working memory are available to AI harnesses. It has two modes: processkit, which installs the full structured context layer, and harness-only, which keeps only the generated container and harness setup.

As of v0.16.0, the system is split across two cleanly separated projects:

• aibox owns the container — devcontainers, addons, the CLI, the install/apply/migrate machinery, and the project skeleton (aibox.lock, .gitignore, provider pointer files, and, in harness-only mode, a minimal AGENTS.md).
• processkit owns the content — every skill, every primitive schema, every state machine, the canonical AGENTS.md template, the processes, and the package YAMLs that compose them.
• The user-side context/ directory is shared territory in processkit mode. aibox creates it, processkit fills it, and the user edits in place. An immutable upstream snapshot is kept under context/templates/processkit/<version>/ for the three-way diff that aibox apply uses to detect upstream changes versus local edits.

The Problem

AI coding agents like Claude operate best when they understand not just the code, but the project’s goals, decisions, and current state. Without structure, this information ends up scattered across chat histories, stale comments, and the developer’s memory.

A single root-level instructions file is not enough for non-trivial projects. It works well for instructions and preferences, but it does not provide a standard place for decisions, backlog, progress tracking, or team conventions.

How Context Files Work

With the default context.mode = "processkit" and a real [processkit].version pinned, your project looks something like this after aibox init and aibox apply:

my-project/
├── AGENTS.md                       # Canonical agent entry — rendered from processkit scaffolding
├── CLAUDE.md                       # Thin pointer to AGENTS.md (provider entry file)
├── aibox.toml
├── .devcontainer/
└── context/
    ├── skills/                     # Editable skill copies
    ├── processes/                  # release, code-review, feature-development, bug-fix
    ├── schemas/                    # primitive schemas
    ├── state-machines/             # state machine definitions
    └── templates/
        └── processkit/
            └── v0.27.4/            # Immutable upstream snapshot, base of three-way diffs

With context.mode = "harness-only", aibox writes only the container and harness surfaces:

my-project/
├── AGENTS.md                       # Minimal project instructions generated by aibox
├── CLAUDE.md                       # Thin pointer to AGENTS.md when Claude is enabled
├── aibox.toml
├── .aibox-home/
└── .devcontainer/

Harness-only mode intentionally omits processkit content, processkit MCP gateway config, processkit hooks/preauth, processkit command adapters, and processkit Migration entities. Generated text surfaces contain no processkit references.

AGENTS.md, CLAUDE.md, and provider files

AGENTS.md at the project root is the canonical agent entry document. It is either rendered from the processkit template (context.mode = "processkit") or generated as a minimal aibox-owned file (context.mode = "harness-only"). It is write-if-missing during aibox init; aibox does not overwrite local edits. The agents.md ecosystem convention is to read this file from any AI harness.

When Claude is enabled in [ai].harnesses, aibox also writes a thin CLAUDE.md at the project root that points at AGENTS.md. In processkit mode, command adapters are projected into enabled harness surfaces, including .claude/skills/<name>/SKILL.md for Claude Code. Canonical skill content still lives under context/skills/; provider-specific files are generated shims. In harness-only mode, only the pointer is written.

OWNER.md — Developer Identity

OWNER.md captures the developer’s identity and preferences. It is created during aibox init (or by the owner-profile skill the first time the agent asks), with fields that help AI agents understand who they are working with:

• Name — how the developer prefers to be addressed
• Domain expertise — areas of knowledge and experience
• Primary languages — programming languages used most often
• Communication language — natural language for responses (e.g., English, German)
• Timezone — for scheduling and availability context
• Working hours — typical availability window
• Current focus — what the developer is currently working on or learning
• Communication preferences — style and conventions for AI interactions

Skills and Processes

Skills and processes are owned by processkit and are only installed when context.mode = "processkit". For full documentation on what’s available, how skills are organised, and which packages to use, see:

• Skills — how skills install and how to browse them
• Process Packages — package tiers and selection
• processkit on GitHub

Version Tracking

Resolved versions are split between desired and applied state:

[context]
mode = "processkit"
packages = ["product"]

[processkit]
version = "v0.27.4"

[processkit.context]
schema_version = "1.0.0"

aibox.toml declares the desired image and processkit versions. aibox.lock records the CLI version and exact resolved processkit release, checksum, addon selection, and managed runtime-home state last applied to the project.

When the schema evolves, aibox doctor flags version mismatches and aibox apply runs the relevant migrations. See Migration for details.

Relationship to aibox.toml

The [context] section in aibox.toml selects the context mode. The [processkit] section is used only in processkit mode and pins which version of the content repository this project consumes:

[context]
mode = "processkit"
packages = ["product"]

[processkit]
source  = "https://github.com/projectious-work/processkit.git"
version = "v0.27.4"

Run aibox apply after editing [processkit].version to pull a new release. For harness-only projects, set only:

[context]
mode = "harness-only"

Design Principles

Convention over configuration. File names and locations are standardised so AI agents can find them without special instructions.

Human-readable first. Context files and root instructions are Markdown. They are useful without any tooling.

Editable in place. Everything under context/skills/, context/processes/, context/schemas/, and context/state-machines/ is yours to edit. The immutable snapshot under context/templates/processkit/<version>/ exists only as the base of aibox apply’s three-way diff.

No lock-in. Context files are plain Markdown and YAML in a context/ directory, and harness-only instructions are plain root-level Markdown. Stop using aibox and the files remain useful.

Clean boundary between container and content. aibox owns the box; processkit owns what goes in it. Each ships on its own cadence.

9.2 - Skill Selection

Skill Selection

New aibox projects list the standard processkit operating skills explicitly in [skills].include. This makes skill selection a direct comment/uncomment workflow in aibox.toml without relying on legacy package tiers.

Use [skills].include for explicit additions and [skills].exclude for explicit removals:

[skills]
include = [
  "pk-doctor",
  "status-briefing",
]
exclude = [
  # "skill-to-omit",
]

Legacy package tiers (minimal, managed, software, research, product) are still accepted for compatibility under [context].packages when [context].mode = "processkit", but explicit [skills] selection is the preferred control surface.

Where the Content Lands

After aibox init and aibox apply with [context].mode = "processkit" and [processkit].version pinned:

context/
├── skills/                              # Editable copies of installed skills
├── processes/                           # release, code-review, feature-development, bug-fix
├── schemas/                             # primitive schemas
├── state-machines/                      # state machine definitions
└── templates/
    └── processkit/
        └── v0.25.7/
            ├── context/
            │   ├── skills/
            │   └── schemas/
            ├── .processkit/
            │   └── packages/            # The package YAMLs themselves
            └── AGENTS.md

The version path (v0.25.7 above) is whatever [processkit].version is pinned to in aibox.toml.

Harness-only projects do not install this content and do not create context/templates/processkit/.

Upstream Source

The skills are owned by processkit:

• Repository: https://github.com/projectious-work/processkit
• Releases: https://github.com/projectious-work/processkit/releases
• Local copy in your project: context/templates/processkit/<version>/.processkit/packages/

To consume a fork or a private mirror, point [processkit].source at it (see [processkit] configuration).

9.3 - Migration

Migration

When the aibox context schema evolves between versions, existing projects may need to update their context files. The aibox doctor command helps identify schema gaps and produces review artifacts under .aibox/migration/.

Separate processkit content and generated-runtime changes are surfaced as Migration entities under context/migrations/ in processkit mode.

How Version Tracking Works

Two pieces track the version:

1. aibox.toml contains the target context schema version. Current canonical processkit-mode configs render this under [processkit.context]; [context].schema_version is still accepted for compatibility:

   [processkit.context]
   schema_version = "1.0.0"
   

2. aibox.lock records the aibox CLI/runtime state last applied to the project. Legacy .aibox-version files from older projects are absorbed into aibox.lock and removed by the migration path.

When aibox doctor detects a schema mismatch, it flags the project as needing migration and writes schema review artifacts.

Running Doctor

aibox doctor

Doctor performs the following checks:

• Validates aibox.toml syntax and field values
• Detects the container runtime (podman or docker)
• Checks for .aibox-home/ and .devcontainer/ directories
• Compares the current embedded context schema against the configured target schema version
• Validates expected context/processkit files for the chosen context mode

Example output when migration is needed:

==> Running diagnostics...
 ✓ Config version: 0.1.0
 ✓ Image: python
 ✓ Process: product
 ✓ Container name: my-app
 ✓ Container runtime: podman
 ✓ .aibox-home/ directory exists at .aibox-home
 ✓ .devcontainer/ directory exists
 ! Context schema: current 1.0.0, target 2.0.0 (migration needed)
 ✓ Diagnostics complete

Migration Artifacts

When a schema mismatch is detected, doctor generates review artifacts in .aibox/migration/:

.aibox/
└── migration/
    ├── schema-current.md
    ├── schema-target.md
    ├── diff.md
    └── migration-prompt.md

When processkit content, runtime-home drift, model/provider changes, or similar processkit-mode updates need human review, aibox emits Migration entities in context/migrations/:

context/
└── migrations/
    ├── pending/       # Migrations queued but not yet started
    ├── in-progress/   # Migration currently being applied
    └── applied/       # Completed migrations (archived for reference)

Each processkit Migration is identified by a MIG-ID and lives as a versioned document in the appropriate subdirectory. These Migration entities are managed through the normal resource grammar:

aibox get migration                       # show pending/in-progress migrations
aibox set migration <id> in-progress      # begin a pending migration
aibox apply migration <id>                # mark a migration as applied
aibox delete migration <id> --reason "…"  # reject and archive without applying

Applying a Migration

Strict Schema And Storage Policy

Migrations are the durable fix for schema, vocabulary, filename, ID, and directory-layout drift. A clean project should satisfy the current schemas and storage policy directly, not by carrying project-local compatibility allowlists.

Do not resolve doctor findings by adding legacy_known_* schema entries, doctor suppressions, mixed-layout exceptions, or local notes that accept legacy event names, IDs, filenames, or directory shapes as the steady state. If a schema genuinely needs a new value or layout, introduce that as an explicit schema migration and then migrate existing entities and references to the new standard.

Compatibility shims are acceptable only as short-lived migration aids. Before a migration is marked applied, the repository should contain canonical values, canonical filenames, canonical directory placement, and updated references.

With an AI agent (recommended)

1. Run aibox doctor to identify gaps and queue migration artifacts
2. Run aibox set migration <id> in-progress to begin the next pending migration
3. Open the migration document from context/migrations/in-progress/
4. Paste its contents into a Claude Code session (or let the agent find it via AGENTS.md)
5. Review the changes the agent makes
6. Run aibox apply migration <id> to mark the migration complete

Manually

1. Run aibox doctor to generate migration artifacts
2. Run aibox set migration <id> in-progress to move the migration to context/migrations/in-progress/
3. Follow the migration document’s checklist
4. Run aibox apply migration <id> to archive the migration to context/migrations/applied/

Best Practices

Never auto-migrate content. Structural changes (new files, renames) can be automated. Content changes (rewriting sections, reformatting entries) should always be reviewed by a human or guided AI session.

Migrate forward, do not grandfather. Fix schema and storage drift by moving entities to the current vocabulary, filenames, IDs, and directory layout. Project-local allowlists and doctor suppressions are not acceptable terminal states.

Commit before migrating. Always commit your current state before applying migration changes. This gives you a clean rollback point.

Run doctor after migrating. After applying changes, run aibox doctor again to confirm everything is clean.

Keep aibox.lock in version control. It records the resolved CLI, processkit, addon, and managed runtime state shared by the project. A legacy .aibox-version file is migration input only and is removed by aibox apply.

Schema Document Format

Schema documents in the schemas/ directory define the expected structure for each version. They specify:

• Which files each process flavor should contain
• Required sections within each file
• File naming conventions
• Directory structure requirements

These schemas are used by doctor to validate the project and by migration tooling to compute diffs between versions.

10 - Migrations

10.1 -

Moving from v0 containers to v1 deployments

v1 deployment orchestration is opt-in. A v0 project remains a v0 container project until its aibox.toml explicitly enables [orchestration]; aibox apply, up, and down from the v0 lifecycle do not discover, modify, or remove a v1 deployment receipt.

Prepare the configuration

Preview first. This reads only aibox.toml, reports digests rather than printing configuration contents, and does not contact a container runtime or a cluster:

aibox config migrate-v1 --output json

The preview maps the safe, deterministic part of the old configuration: container.name becomes the proposed fleet, first service, and deployment name. It then returns an unresolvedDecisions array for facts that aibox must not guess:

• immutable image reference and digest;
• target platform;
• Compose context/scope or Kubernetes context/namespace;
• stable deployment owner;
• connection transports;
• credential references for any v0 environment entries;
• a remove-or-redesign disposition for host bind mounts.

The report never includes environment values. readyToEnable remains false until these operator decisions have explicit v1 values. This makes the command a migration planner, rather than a textual marker that implies the v0 configuration was fully converted.

Create a reviewed TOML document containing only one complete [orchestration] tree, then apply it with the migration:

aibox config migrate-v1 --apply --intent-file v1-intent.toml --output json

The intent file may say enabled = true for validation, but the migration always writes it as enabled = false. Aibox validates the complete image, fleet, target, deployment, connection, and credential-reference contract offline before it creates the backup or changes aibox.toml. Extra top-level tables, incomplete intent, symlinked files, and raw credential values are rejected. The result reports readyToEnable: true; activation remains a separate reviewed edit followed by aibox config compile and aibox deploy plan.

Apply the narrow migration only after reviewing the preview:

aibox config migrate-v1 --apply

The command creates an exact original copy under .aibox/backups/v1-config/ before atomically replacing aibox.toml. The only new configuration is:

[orchestration]
enabled = false

That disabled boundary is intentional. Add the reported unresolved values explicitly, run aibox config compile, review aibox deploy plan, and only then set enabled = true.

Roll back configuration

The apply result prints the backup path. Restore it explicitly:

aibox config migrate-v1 --restore .aibox/backups/v1-config/v0-<stamp>-<digest>.toml

Restore accepts only regular backups inside the project backup directory and uses an atomic replacement. It restores the config alone: it deliberately does not read, alter, or delete .aibox/deployments/ records or any remote resource. Use aibox deploy destroy while the v1 configuration and ownership record are still available if you intend to remove an existing v1 deployment.

Coexistence boundary

Do not point v0 generated Compose files at v1 deployment artifacts. v1 Compose deployments use their own rendered artifacts and ownership labels; Kubernetes deployments use namespace-scoped labels and a durable DeploymentRecord. The v0 lifecycle has no authority to operate either form of v1 state.

This boundary makes rollback safe but not magical: reverting a config does not roll back a remote deployment. Treat deployment removal as a separate, guarded operation with its own record and evidence.

10.2 -

Lockfile schema bump v0.25.6 — what’s automatic, what to verify

aibox v0.25.6 extends aibox.lock with two new optional sections. The bump is fully automatic — aibox apply backfills the new fields on first run. No manual editing is required, and existing lockfiles remain valid (the new fields use #[serde(default)], so they are absent from old locks without causing parse errors).

What changed

cli/src/lock.rs adds:

• AddonsLockSection::previous_selection (BTreeMap<String, BTreeSet<String>>) — records which tool names were enabled under each addon family at the time of the last apply. Written under [addons.previous_selection] in aibox.lock. Used on the next apply to compute a removal diff when a tool is disabled, so stale addon binaries baked into an earlier image layer can be purged cleanly.

• [harnesses] section (HarnessLockSection) — records the set of AI harness names that were active (previous_selection: BTreeSet<String>) and the timestamp when the record was taken (recorded_at). Used by aibox apply to detect harnesses that were active last time but are no longer configured, enabling targeted cleanup of harness-specific state files (gated on [apply].purge_disabled_harness_state, default false).

Both fields are populated automatically on the first aibox apply that runs against an old v0.25.5 lockfile.

Troubleshooting

[addons.previous_selection] is absent after apply.

This is expected if no addon tools are enabled — the field serializes only when non-empty (skip_serializing_if = "BTreeMap::is_empty"). Enable at least one tool under [addons] in aibox.toml and re-run aibox apply to see it populated.

aibox apply reports a lockfile parse error after upgrading from v0.25.5.

A truncated or hand-edited aibox.lock may have a malformed [addons] section. Check that [addons].resolved_at is present and is a valid ISO 8601 timestamp. If the file is corrupt, delete aibox.lock and run aibox apply — the CLI regenerates it from scratch.

10.3 -

Zellij end-of-life migration (v0.25.5 → v0.25.6)

TL;DR

aibox v0.25.6 removes Zellij entirely. tmux is now the only supported terminal multiplexer. Any [customization.zellij_status] section in your aibox.toml causes schema validation to hard-reject aibox apply — you must remove it before upgrading. Stale Zellij directories and binaries are purged automatically on the first aibox apply that runs against a v0.25.6+ host CLI. No data from active work sessions is touched; only Zellij runtime artifacts are removed.

What changed

The following items are removed or rejected in v0.25.6 (commit faa9a88, decision DEC-20260508_1515-SilentAsh):

• [customization.zellij_status] config key — the field is removed from the Customization struct in cli/src/config.rs. The TOML deserializer now hard-rejects any aibox.toml that still contains this section, with a descriptive error pointing to this document.

• --forget-zellij-state CLI flag — removed from the argument parser in cli/src/cli.rs. Scripts or aliases that reference this flag will fail to parse.

• Unconditional purge on aibox apply — the following paths under .aibox-home/ are deleted on every apply regardless of config:

  • .config/zellij/
  • .cache/zellij/
  • .local/share/zellij/
  • .local/bin/aibox-status (the shell-backed Zellij helper; superseded by the tmux PowerKit plugin set)

  The purge is performed by cleanup_legacy_zellij_files() in cli/src/seed.rs, which calls unconditionally via LEGACY_MUX_RELPATHS.

• aibox doctor errors — any surviving artifact from the list above triggers an ERROR diagnostic (check_legacy_zellij_artifacts in cli/src/doctor.rs). The error is not advisory; it blocks a clean doctor run.

What you need to do

Complete these steps on the host before or immediately after upgrading to v0.25.6:

a. Remove [customization.zellij_status] from your aibox.toml. Open the file and delete the entire section (header and all keys beneath it). If you have no such section, skip this step.

b. Migrate any custom status configuration to tmux. If you previously used Zellij status customizations, set the tmux equivalent in aibox.toml:

[customization.tmux.status]
mode = "extended"   # or "minimal" for a compact single-line bar

The extended mode renders a two-line powerline bar with aibox metrics (log/OOM/proc/AI/MCP/migration counters). The minimal mode renders a single line. See docs-site/docs/customization/layouts.md for full reference.