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.

CLI Commands

CLI Commands#

aibox uses a small verb/resource grammar. aibox.toml is desired state, aibox apply reconciles generated files and images, and aibox up enters the workspace.

Global Options#

Core Workflow#

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

Command Grammar#

aibox init [NAME] [OPTIONS]
aibox apply [RESOURCE] [NAME] [OPTIONS]
aibox up [OPTIONS]
aibox down
aibox get <RESOURCE> [OPTIONS]
aibox describe <RESOURCE> [NAME] [OPTIONS]
aibox set <TARGET> [VALUE] [EXTRA...] [OPTIONS]
aibox edit <RESOURCE>
aibox reset <RESOURCE> [OPTIONS]
aibox delete <RESOURCE> [NAME] [OPTIONS]
aibox create <RESOURCE> [NAME] [OPTIONS]
aibox self <ACTION> [OPTIONS]

init#

Create aibox.toml, generated devcontainer files, .aibox-home/, context scaffolding, and provider pointer files.

aibox init
aibox init my-app --harness claude
aibox init runner --profile headless-runner
aibox init my-app --addon python --addon infrastructure
aibox init my-app --harness claude --harness codex
aibox init my-app --context-mode harness-only --harness claude
aibox init my-app --theme catppuccin-mocha

The hidden legacy --context <PKG> option is still accepted as a processkit package selector for compatibility. New configs use [context].mode and, when processkit is enabled, [context].packages.

--context-mode harness-only creates a container-and-harness project with no processkit install, no processkit MCP gateway, no processkit hooks/preauth, no processkit command adapters, and no processkit Migration entities.

apply#

Reconcile generated project state with aibox.toml.

aibox apply
aibox apply --no-cache
aibox apply --rebuild
aibox apply --config-only
aibox apply --standardize-config
aibox apply migration MIG-20260430_1200
aibox apply audio
aibox apply env research

Runtime#

aibox up
aibox up --layout focus
aibox up --apply
aibox down
aibox get runtime
aibox get runtime --resources
aibox get runtime --resources -o json
aibox describe runtime
aibox delete runtime

up starts or creates the workspace container and attaches through tmux. down stops the compose project. delete runtime removes the container while preserving project files and .aibox-home/.

get runtime reports the configured container name and detected state (running, stopped, or missing). With --resources, it reports a best-effort resource pressure snapshot from the current Linux runtime by reading cgroupfs and procfs directly rather than shelling out to ps or free.

aibox get runtime --resources includes:

The default table output is compact and human-readable. -o json and -o yaml emit the same field names for automation; unavailable cgroup values are null, while process counts fall back to 0 if /proc cannot be read.

Inspecting Resources#

get is compact and scriptable. describe is detailed and human-readable. All list/detail commands support -o, --format table|json|yaml; --output is accepted as a visible alias.

aibox get addon
aibox describe addon python
aibox describe addon-catalog -o json
aibox describe image-provenance-policy -o json
aibox get runtime --resources -o json
aibox describe provider-backends -o json
aibox describe workspace-manifest -o json
aibox get skill
aibox get skill --all --category engineering
aibox describe skill model-recommender-route
aibox get process
aibox describe process release-semver
aibox get migration
aibox get env
aibox describe env
aibox get kit

Preview projections#

These describe resources are stable enough for local automation. The workspace manifest has been promoted to aibox.workspace-manifest.v0 because processkit now recognizes Artifact{kind=workspace-manifest}; the other environment-contract projections remain aibox.*.v0-preview until processkit publishes more detailed canonical Artifact schemas.

The preview projections do not create processkit entities and should not be treated as canonical processkit Artifacts yet.

Mutating Resources#

set changes config. Use --apply when you want to reconcile immediately.

aibox set theme.mode dark --apply
aibox set theme.name tokyo-night --apply --restart-session
aibox set addon python enabled
aibox set addon python disabled --apply
aibox set skill model-recommender-route enabled
aibox set skill pandas-polars disabled --apply
aibox set migration MIG-20260430_1200 in-progress

Delete explicit resources:

aibox delete addon python
aibox delete addon python --apply
aibox delete skill pandas-polars
aibox delete env research --yes
aibox delete migration MIG-20260430_1200 --reason "Not applicable"

Reset And Backup#

Project reset is intentionally scoped; there is no bare destructive reset.

aibox create backup
aibox create backup --dry-run
aibox create backup --output-dir /tmp/my-backup
aibox reset project
aibox reset project --dry-run
aibox reset project --no-backup --yes
aibox reset context --from-processkit v0.25.0 --dry-run

reset project is the practical aibox soft reset. It stops the runtime, backs up aibox-managed project files, preserves auth/cache state from .aibox-home/, removes the managed scaffold, and writes a reset recovery migration briefing when user content is found in the backup. It also removes aibox.toml, so it is not a one-command reinit. Recreate or restore aibox.toml, run aibox init or aibox apply, then review context/migrations/pending/ for the recovery advice.

reset context is plan-only in this release. It reports the processkit-owned context paths that a hard reset would replace from a selected processkit baseline and the project-owned context paths that must be preserved or reviewed. Use normal migrations unless the owner explicitly approves a hard context reset.

Diagnostics#

aibox doctor
aibox doctor --integrity
aibox doctor --integrity -o json
aibox doctor audio
aibox doctor security

doctor audio checks host PulseAudio readiness. doctor security runs available dependency/image scanners.

LaTeX container scripts#

Named LaTeX documents are configured under [[latex.documents]]. aibox apply deploys the following managed scripts to .aibox-home/.local/bin; they are on PATH inside the development container and are not host CLI commands.

aibox-latex-build                 # build all configured documents
aibox-latex-build overview        # build one configured document
aibox-latex-watch overview        # continuous foreground build inside the container

Host-side aibox up starts the read-only Compose preview sidecar when preview is enabled. It serves every configured PDF and shows a selection page at its root when more than one exists. See LaTeX Build and Preview for container workflow, remote forwarding, and security details.

Self Management#

aibox self update --check
aibox self update --dry-run
aibox self update
aibox self completion bash
aibox self uninstall
aibox self uninstall --purge

Removed Old Grammar#

The hard-break CLI redesign removed the old top-level command taxonomy.

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.

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

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

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

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 36 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.5" }

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

[addons.node.tools]
node = { version = "26" }
pnpm = { version = "11.22.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.

Language addons also expose composable nested groups. For example, [addons.go.quality], [addons.go.supply-chain], and [addons.go.release] select the canonical go-quality, supply-chain, and go-release recipes and expand their dependencies automatically. Nested [addons.<language>.<group>.tools] entries use the same version and enabled overrides as flat addons.

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.5  0.7, 0.11.10, 0.11.11, 0.11.15, 0.11.19, 0.11.26, 0.12.0, 0.12.5
  poetry         no      2.4.1  1.8, 2.0, 2.4.1
  pdm            no     2.28.1  2.22, 2.26.9, 2.27.0, 2.28.0, 2.28.1

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.

Overview

What aibox does, what it owns, and when to use it.

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.

Configuration

Configuration#

aibox.toml is the single source of truth for an aibox project. All generated files derive from it.

Full Specification#

[aibox]
project_name = "my-app"               # Human-readable project name
profile      = "human-dev"            # Usage profile: human-dev or headless-runner

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

[container.image]
release_version = "latest"            # aibox image/CLI version, or "latest"
base            = "debian"            # Base image flavor

[container.paths]
devcontainer_json       = ".devcontainer/devcontainer.json"
docker_compose          = ".devcontainer/docker-compose.yml"
docker_compose_override = ".devcontainer/docker-compose.override.yml"
dockerfile              = ".devcontainer/Dockerfile"
dockerfile_local        = ".devcontainer/Dockerfile.local"
local_env               = ".aibox-local.env"

[container.lifecycle]
post_create_command = "npm install"   # Command to run after container creation
keepalive = false                     # Periodic DNS keepalive for idle network timeouts

[container.resource_thresholds]
memory_mib_warn = 4096                # Optional warning limit for cgroup memory usage in MiB
process_count_warn = 400              # Optional warning limit for total live processes; 0 disables
processkit_mcp_python_warn = 50       # Optional warning limit for live Python MCP server processes; 0 disables
oom_kill_warn = 0                     # Optional warning threshold for cgroup OOM kill count

[container.environment]
NODE_ENV = "development"              # Project-wide env vars (non-secret; use .aibox-local.toml for secrets)

[[container.extra_volumes]]
source    = "~/.aws"                  # Host path (~ expanded)
target    = "/home/aibox/.aws"        # Container path
read_only = true

[context]
mode = "processkit"                   # processkit | harness-only
packages = ["product"]                # processkit package selection

[processkit]
source   = "https://github.com/projectious-work/processkit.git"
version  = "latest"                   # newest stable release, "unset", or a real tag (including an explicit prerelease)
src_path = "src"
# branch = "main"                     # Optional; tarball-first, branch as fallback
# release_asset_url_template = "..."  # Optional, for non-GitHub hosts

[processkit.context]
schema_version = "1.0.0"              # Context schema version (semver)

[addons.python.tools]                 # Addon: Python runtime
python = { version = "3.14" }
uv     = { version = "0.12.5" }

[addons.rust.tools]                   # Addon: Rust toolchain
rustc   = { version = "1.97.1" }
clippy  = {}
rustfmt = {}

[addons.git-ui.tools]                 # Optional: GitHub CLI and lazygit
gh      = {}
lazygit = {}

[integrations.github]
credential_helper = "auto"            # auto | gh | none

[ai]
model_providers = ["anthropic"]       # Optional provider env hints (API key + base URL)
harnesses = [                         # Harness order is list order
    { harness = "codex", enable = true, install = true },
#   { harness = "claude", enable = true, install = true },
]

[ai.agents]
canonical     = "AGENTS.md"
provider_mode = "pointer"             # pointer | full

[ai.mcp]
# Team-shared MCP servers merged into all generated MCP client configs
# (see also [[mcp.servers]] in .aibox-local.toml for personal servers)

[[ai.mcp.servers]]
name    = "my-team-tool"              # Unique server name
command = "npx"                       # Executable to run
args    = ["-y", "@acme/team-server"] # Arguments
# [ai.mcp.servers.env]                # Optional environment variables
# API_KEY = "..."

[customization]
theme  = "ayu"                        # Theme family; concrete legacy names still parse
mode   = "auto"                       # Theme mode: auto, light, dark
variant = "mirage"                    # Optional family-specific variant
emphasis = "auto"                     # auto, full, standard, minimal, none
prompt = "default"                    # Starship preset (8 options)
layout = "dev"                        # tmux layout (4 options)

[customization.emphasis_overrides]
code_comment = "italic dim"           # Optional semantic role override
status_error = "bold underline"

[customization.tmux.status]
mode = "extended"                     # extended | plain | disabled (legacy: powerline -> extended)

[customization.tmux.title]
# The terminal tab title is owned by tmux while inside tmux.
enabled = true
format = "{state_symbol}{project}:{window} — {directory}"
max-length = 60
directory-style = "basename"           # basename | abbreviated | full
done-ttl-seconds = 10
message-max-length = 32

[customization.tmux.title.states]
working = "● "
question = "❓ "
done = "✓ "
error = "! "
idle = ""

[customization.tmux.notifications]
enabled = false
protocol = "osc-9"                    # osc-9 | bell
states = ["question", "error"]
include-message = true

[customization.tmux.status.layout]
# Row lists are ordered. Removing a name disables that status element.
# Allowed line1-left entries:
# - session: current tmux session name and prefix/copy-mode state
# - windows: tmux window list
#
# Allowed line1-right / line2-left / line2-right entries:
# - aibox_log: aibox log health counts
# - aibox_oom: cgroup OOM kill counters
# - aibox_proc: live process count versus configured process warning limit
# - aibox_ai: detected AI-agent/runtime process count
# - aibox_mcp: processkit/MCP daemon and server process status (processkit mode)
# - aibox_mig: pending processkit migration count (processkit mode)
# - weather: weather segment from tmux-powerkit
# - uptime: container uptime
# - datetime: local date/time
# - git: current repository branch/status
# - github: GitHub/repository integration status
# - kubernetes: Kubernetes context/status
# - terraform: Terraform/OpenTofu workspace/status
# - cloud: local cloud CLI/context status
# - cloudstatus: networked public provider status checks; opt-in, not enabled by default
# - hostname: container hostname
# - externalip: detected external IP
# - ssh: SSH agent/key status
# - netspeed: network throughput
# - ping: network latency
# - cpu: CPU usage
# - loadavg: system load average
# - memory: memory usage
# - swap: swap usage
# - disk: disk usage
# - gpu: GPU status when available
# - modelstatus_<provider>: per-provider AI status segment; explicit layout entries render even when model-provider auto-add is off
line1-left = ["session", "windows"]
line1-right = ["aibox_log", "aibox_oom", "aibox_proc", "aibox_ai", "aibox_mcp", "aibox_mig", "weather", "uptime", "datetime"]
line2-left = ["git", "github", "kubernetes", "terraform", "cloud"]
line2-right = ["hostname", "externalip", "ssh", "netspeed", "ping", "cpu", "loadavg", "memory", "swap", "disk", "gpu"]

[customization.tmux.status.labels]
# Visible headers/icons for status segments. Layout controls which segments appear;
# this section controls how those segments are labeled once rendered.
# Values may be plain ASCII labels or symbols. ASCII is safest across terminals;
# Nerd Font / Powerline symbols are compact but require the user's terminal font.
# Practical symbol candidates from Nerd Fonts. Keep icons distinct across
# configured PowerKit segments so adjacent status cells remain scannable.
aibox-log = "󱖫"
aibox-oom = "󰍛󰚌"
aibox-proc = "󰊚"
aibox-ai = "󱙺"
aibox-mcp = "󰌹"
aibox-mig = "󰚰"
kubernetes = "󱃾"
cloud = "󰅣"
cloud-aws = "󰸏"
cloud-gcp = "󰬠"
cloud-azure = "󰠅"
cloud-multi = "󰅤"
uptime = ""
netspeed = ""
netspeed-download = "󰇚"
netspeed-upload = "󰕒"

[customization.tmux.status.separators]
# PowerKit separator style. Options: normal | rounded | slant | slantup | trapezoid | flame | pixel | honeycomb | none
style = "rounded"
# Edge separators may use a different style at status boundaries.
edge-style = "rounded"
# Spacing between elements. Options: false | true | both | windows | plugins
elements-spacing = "both"

[customization.tmux.status.refresh]
# Refresh/caching controls for extended tmux status.
# interval-seconds: tmux redraw cadence. Higher values reduce shell process churn.
# aibox-metrics-cache-ttl-seconds: LOG/OOM/PROC/AI/MCP/MIG cache TTL.
# netspeed-cache-ttl-seconds: network throughput cache TTL.
# kubernetes-cache-ttl-seconds: local kubeconfig context cache TTL.
# cloud-cache-ttl-seconds: local cloud CLI/context cache TTL.
# github-cache-ttl-seconds: local repo + GitHub issue/PR/discussion count cache TTL.
interval-seconds = 15
aibox-metrics-cache-ttl-seconds = 30
netspeed-cache-ttl-seconds = 10
kubernetes-cache-ttl-seconds = 120
cloud-cache-ttl-seconds = 120
github-cache-ttl-seconds = 120

[customization.tmux.status.forge]
# Exact GitHub SSH hostnames and aliases recognized by the Forge segment.
github-hosts = ["github.com", "github-work"]

[customization.tmux.status.model-providers]
# Optional networked model-provider health segments for the extended tmux status line.
# Each configured provider becomes one PowerKit segment when enabled, for example OAI ✓ or ANT 󰚌.
# enabled: false avoids auto-adding all configured providers; explicit layout entries still render.
# cache-ttl-seconds: minimum time between provider status requests per provider.
# timeout-seconds: per-request HTTP timeout so status rendering cannot hang tmux.
# show-ok: true shows healthy providers with ✓; false hides healthy providers and only shows degraded/unknown/outage.
enabled = false
cache-ttl-seconds = 300
timeout-seconds = 3
show-ok = true
# Provider entries:
# - provider: stable key from the model roster (openai, anthropic, google, mistral, deepseek, cohere, xai, alibaba, aws, meta, microsoft, minimax, moonshot, nvidia, xiaomi, zai)
# - label: short category header shown in the status segment; use text or a symbol that your font supports
# - checks: any of overall, models, harness; worst status wins (outage > degraded > unknown > ok)
# - status-url: JSON status endpoint; Statuspage summary APIs are supported, Google uses incidents.json
# - overall-components/model-components/harness-components: optional component-name filters for providers with componentized status APIs
#   Symbols: ✓ ok, 󰀦 degraded, 󰚌 outage, ? unknown.

[[customization.tmux.status.model-providers.providers]]
provider = "openai"
label = "OAI"
checks = ["overall", "models", "harness"]
status-url = "https://status.openai.com/api/v2/summary.json"
model-components = ["Responses", "Chat Completions", "Embeddings", "Realtime", "Images"]
harness-components = ["CLI", "Codex API", "Codex Web"]

[[customization.tmux.status.model-providers.providers]]
provider = "anthropic"
label = "ANT"
checks = ["overall", "models", "harness"]
status-url = "https://status.claude.com/api/v2/summary.json"
model-components = ["Claude API"]
harness-components = ["Claude Code"]

[[customization.tmux.status.model-providers.providers]]
provider = "google"
label = "GOOG"
checks = ["overall", "models"]
status-url = "https://status.cloud.google.com/incidents.json"

[audio]
enabled      = false                  # Enable audio bridging
backend      = "pulseaudio"           # Audio bridge backend
install      = true                   # Install container audio tools
pulse_server = "tcp:host.docker.internal:4714"

Section Reference#

[aibox]#

Top-level project metadata.

profile is currently a compatibility signal for addon selection and doctor warnings. It does not change the generated image tag yet; headless-runner is reserved for automation-safe configurations that avoid subscription CLI tools and interactive desktop helpers.

For automation, aibox describe workspace-manifest -o json emits a sorted, read-only aibox.workspace-manifest.v0 projection of this file. The projection uses processkit’s canonical Artifact{kind=workspace-manifest} kind, while the machine-readable JSON shape remains aibox-owned until processkit publishes a more detailed Artifact schema.

aibox describe provider-backends -o json similarly emits aibox.provider-backends.v0-preview, an aibox-local index of supported harness backends, addon availability, and MCP registration/permission targets. aibox doctor uses the same preview model to warn about selected backends that cannot participate in MCP automation, have no permission projection, or conflict with the headless-runner profile.

aibox describe image-provenance-policy -o json emits aibox.image-provenance-policy.v0-preview, which summarizes the configured GHCR image tag or tag template, generated Dockerfile/Compose files, runtime version/profile markers, selected addons, and the host-side release phase command template.

[container]#

Container configuration. Controls the generated docker-compose.yml and Dockerfile.

Generated Compose files include a top-level project name, an explicit service image, and container_name = [container].name. Container runtime and Compose views should therefore show each aibox project under its configured project/container identity instead of a generic devcontainer group.

[container.resource_thresholds]#

These thresholds are warnings only. They do not stop aibox up or fail the container build; they make aibox doctor surface resource pressure before the operating system starts killing processes.

[[container.extra_volumes]]#

Each entry in the extra_volumes array is an ExtraVolume with these fields:

Example — mount a personal host configuration directory:

[[container.extra_volumes]]
source    = "~/.aws"
target    = "/home/aibox/.aws"
read_only = true

GitHub CLI configuration created inside the container does not need an extra volume: /home/aibox/.config/gh is already persisted through the managed .aibox-home/.config mount. See GitHub authentication for the least-privilege PAT and persistent-login options.

.aibox-local.toml#

.aibox-local.toml is a personal, gitignored overlay for per-developer settings that should never be committed — API keys, provider endpoint/base URL overrides, personal bind mounts, and similar secrets. It lives next to aibox.toml in the project root and is automatically added to .gitignore by aibox init and aibox apply.

Three sections are supported:

• [container.environment] — merged on top of aibox.toml’s [container.environment]. Local values win on conflicts.
• [[container.extra_volumes]] — appended after any volumes declared in aibox.toml.
• [[mcp.servers]] — personal MCP servers appended to the team MCP servers from aibox.toml [ai.mcp]. All sources are merged into each generated MCP client config file.

All other configuration (container name, addons, processkit version, etc.) must remain in aibox.toml.

See the dedicated Local Config reference for a full example and merge-behavior details.

[context]#

Selects the project context layer.

aibox init --context-mode harness-only writes:

[context]
mode = "harness-only"

In harness-only mode, generated aibox.toml, AGENTS.md, provider pointer files, MCP config, status comments, and migration surfaces do not mention processkit. aibox apply still regenerates .devcontainer/, .aibox-home/, selected harness config, addon files, and team/personal MCP servers; it does not install context/skills/, context/templates/processkit/, processkit hooks, processkit preauth, processkit command adapters, or processkit Migration entities.

Use [skills].include and [skills].exclude for explicit skill-level overrides when mode = "processkit".

[latex]#

Defines named LaTeX documents and their shared build/preview behavior. Add the latex addon separately to install TeX Live in the container.

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

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

[latex.preview]
enabled = true
engine = "embedpdf"
bind = "127.0.0.1"
port = 8765
document = "overview"
allow_public = false

Run aibox apply after changing this section. Besides refreshing the canonical config comments, apply adds conditional LaTeX companion guidance to AGENTS.md and installs the managed aibox-latex-build and aibox-latex-watch scripts into the development container’s runtime home. Compilation and watch mode run only in that main container. See LaTeX Build and Preview for the workflow and remote access. aibox generates the read-only serving sidecar and its port mapping; do not add a duplicate mapping to docker-compose.override.yml.

[addons]#

Addons install language runtimes and tool bundles into the container. AI harnesses are selected under [ai]; aibox may still use internal addon recipes to install their CLIs.

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

For interactive Git tooling:

[addons.git-ui.tools]
gh = {}
lazygit = {}

Omit git-ui if the project does not need GitHub CLI or lazygit in the container. The aibox repo may select it for maintenance workflows, but it is not required for every generated project.

Run aibox get addon to see all available addons, or aibox describe addon <name> for tool details and supported versions. See the Addons page for full documentation.

Language-scoped groups compose shared tooling and automatically expand their dependencies:

[addons.go]
[addons.go.infrastructure]
[addons.go.quality]
[addons.go.supply-chain]
[addons.go.release]

[addons.go.quality.tools]
staticcheck = { enabled = false }
golangci-lint = { version = "v2.12.2" }

Every language addon supports infrastructure, security/supply-chain, and release; Go also supports quality and lint. Existing flat selections such as [addons.infrastructure.tools] and [addons.supply-chain.tools] remain valid and require no migration. To adopt language scoping, move only the table prefix—for example, [addons.supply-chain.tools] becomes [addons.go.supply-chain.tools]; tool entries and overrides are unchanged.

[skills]#

Controls which skills from processkit are installed into context/skills/. Fresh aibox.toml scaffolds list the standard processkit operating skills in include. If include is empty, aibox falls back to installing every skill in the pinned processkit version minus anything listed in exclude.

aibox apply reconciles newly introduced standard skills into existing processkit projects while respecting explicit exclude entries. Tooling-linked skills remain opt-in: an interactive apply asks before persisting a recommendation. For example, selecting the latex addon offers to add latex-authoring; a non-interactive apply prints the recommendation without changing skill selection.

[skills]
include = ["pk-doctor", "status-briefing"]  # install only these plus core skills
exclude = ["research-with-confidence"]      # omit from the default all-skills set

include and exclude are mutually exclusive: use one or the other, not both. Both accept skill names (the filename without .md). enabled and disabled are accepted as aliases for older configs. An empty [skills] table (or omitting the section entirely) installs all skills.

See the Skills page for the full processkit boundary.

This section is omitted and ignored in context.mode = "harness-only".

[ai]#

AI harness and model-provider configuration. Harness entries are ordered; the order of the harnesses list is the tmux/layout order. A harness participates in generated agent/MCP config only when enable = true; CLI installation is controlled independently by install = true.

Harness controls live in the ordered harnesses list. Optional entries are usually shown as one-line inline tables so they can be enabled by uncommenting one line:

harnesses = [
    { harness = "codex", enable = true, install = true },
#   { harness = "claude", enable = true, install = true },
#   { harness = "cursor", enable = true, install = false },
]

Provider env mapping:

model_providers is a catalog hint only; it does not inject environment variables into Compose by itself. Set provider credentials explicitly in [container.environment], preferably in .aibox-local.toml:

[container.environment]
OPENAI_API_KEY = "..."
OPENAI_BASE_URL = "https://api.openai.com/v1"   # Optional override
GEMINI_API_KEY = "..."
GEMINI_BASE_URL = "https://generativelanguage.googleapis.com"  # Optional override

Some provider CLIs/SDKs also support aliases (for example OPENAI_API_BASE).

Legacy compact harness lists, harness_order, providers = [...], [ai.harness.<name>], and [addons.ai-*.tools] inputs are still accepted for compatibility. Use aibox apply --standardize-config to rewrite a schema-clean config into the current canonical shape.

[processkit]#

The load-bearing content section. Configures the content source the project consumes — skills, primitives, processes, package YAMLs, and the canonical AGENTS.md template. The default upstream is the canonical projectious-work/processkit repo, but any processkit-compatible source works (forks, self-hosted, private mirrors).

This section is only active when [context].mode = "processkit". In harness-only mode it is omitted from generated configs and ignored by aibox apply.

If version is the sentinel unset, both aibox init and aibox apply skip the processkit fetch entirely. Pin a real tag (e.g. v0.27.4) to land the content. The downloaded tarball is git-tracked under context/templates/processkit/<version>/ so derived projects always have the original to diff against.

[processkit.context]#

Processkit-mode context-system metadata.

Fetch strategy#

The fetcher tries strategies in priority order:

1. Branch override (if branch is set) — git clone --branch <name>.
2. Release-asset tarball — downloads a purpose-built .tar.gz from the URL built from release_asset_url_template (or the GitHub-style default {source}/releases/download/{version}/{name}-{version}.tar.gz). When a sibling <asset>.sha256 file is present, the tarball bytes are verified against it before extraction. The verified SHA256 is recorded in aibox.lock as release_asset_sha256 for bit-exact reproducibility.
3. Host auto-tarball — falls back to GitHub / GitLab’s auto-generated archive/refs/tags/<version>.tar.gz when no release asset is available.
4. Git clone of the tag — last resort for hosts that serve neither tarball form (typical for self-hosted git over SSH).

The release-asset path lets producers (processkit and any compatible content source) ship a smaller, explicit shippable artifact. Consumers get bit-exact reproducibility for free.

A SHA256 mismatch is a hard error (does NOT fall through), since it indicates either tampering or a producer bug; both are situations the user should be told about.

Example: consume a Gitea-hosted fork#

[processkit]
source                     = "https://gitea.acme.com/platform/processkit-acme.git"
version                    = "v1.2.0"
release_asset_url_template = "https://gitea.acme.com/{org}/{name}/releases/download/{version}/{name}-{version}.tar.gz"

[ai.mcp]#

MCP server definitions and permission configuration. aibox apply merges servers from these sources and regenerates all MCP client config files:

1. Built-in processkit servers — only in context.mode = "processkit", either the processkit gateway or separate per-skill servers, depending on [ai.mcp.gateway]
2. aibox.toml [[ai.mcp.servers]] — team-shared servers committed to version control
3. .aibox-local.toml [[mcp.servers]] — personal servers, gitignored

Generated files (.mcp.json, .cursor/mcp.json, .gemini/settings.json, .codex/config.toml, .codex/hooks.json, .continue/mcpServers/) are gitignored. They are always reproducible from the config sources above and must not be committed — doing so would embed personal server definitions or credentials from .aibox-local.toml.

In harness-only mode, processkit servers and the processkit gateway are not registered. Team and personal MCP servers are still generated for enabled harnesses.

processkit Gateway: [ai.mcp.gateway]#

When the selected processkit release provides processkit-gateway, its stdio proxy can start the matching localhost daemon on demand. It can replace the one-process-per-skill MCP topology with a single processkit MCP entry.

[ai.mcp.gateway]
mode = "auto"          # auto | daemon | stdio | separate
lazy_catalog = true
host = "127.0.0.1"
port = 8765
path = "/mcp"

lazy_catalog = true is the default. It enables processkit’s lazy catalog where the selected gateway topology supports it. Set it to false only when troubleshooting gateway import behavior. Legacy values daemon-proxy and granular are still accepted as aliases for daemon and separate.

The daemon-backed mode is localhost-only. Run aibox apply after changing this section so generated harness configs stay in sync.

Server Definitions: [[ai.mcp.servers]]#

Each [[ai.mcp.servers]] entry has these fields:

Example:

[[ai.mcp.servers]]
name    = "internal-docs"
command = "/usr/local/bin/internal-docs-mcp"
args    = ["--stdio"]
[ai.mcp.servers.env]
LOG_LEVEL = "info"

Credential-bearing personal servers belong in the gitignored .aibox-local.toml [[mcp.servers]] section. Do not commit GitHub tokens in aibox.toml; see GitHub authentication.

Permission Configuration: [ai.mcp.permissions]#

Controls which MCP servers harnesses are permitted to use, eliminating repetitive permission prompts. aibox apply expands glob patterns into concrete server names and regenerates harness-specific permission files for supported harnesses.

Global defaults:

Per-harness overrides (optional):

[ai.mcp.permissions.harness.claude-code]
default_mode = "allow"      # Override global default if needed
allow_patterns = []         # Add harness-specific patterns

[ai.mcp.permissions.harness.opencode]
default_mode = "allow"
deny_patterns = []          # Restrict specific tools per harness

aibox maps this provider-neutral permission intent to each harness’s native configuration format. Sandbox, approval, and network policy are configured separately in [ai.execution].

Example:

[ai.mcp.permissions]
default_mode    = "ask"
allow_patterns  = ["mcp__processkit-*"]
deny_patterns   = ["mcp__processkit-dangerous-admin"]  # Deny a specific pattern if needed

[ai.mcp.permissions.harness.claude-code]
# Use default settings; Claude Code will auto-allow all processkit tools

[ai.mcp.permissions.harness.continue]
# Continue defaults to "ask" for safety; override to "allow" to auto-approve
default_mode = "allow"

[ai.execution]#

Controls the default execution policy intent for AI harnesses. aibox uses stable cross-harness vocabulary here and maps it to each harness where supported.

[ai.execution]
filesystem = "workspace-write" # read-only | workspace-write | container-full
approval   = "on-request"      # ask | on-request | never
network    = "ask"             # deny | ask | allow

[ai.execution.codex]
filesystem = "container-full"
approval   = "on-request"
network    = "ask"

The legacy [ai.harness.<name>.execution] table is still accepted for existing configs, but new scaffolds use [ai.execution.<name>].

filesystem = "container-full" means the devcontainer is the filesystem security boundary. For Codex this maps to sandbox_mode = "danger-full-access", which keeps .git writable inside a trusted aibox devcontainer. It is distinct from Codex’s --dangerously-bypass-approvals-and-sandbox: approvals remain controlled by the approval axis.

Unsupported axes for a harness are best-effort projections; they are retained in aibox.toml as project intent even when the current harness has no exact native setting.

[ai.agents]#

Controls how aibox init scaffolds the canonical agent entry document (AGENTS.md) and the provider-specific entry files (CLAUDE.md, future CODEX.md, …). The principle is provider neutrality: every agent harness reads the same AGENTS.md so a project doesn’t have to keep N copies of the same instructions in sync. Provider files exist only to satisfy specific harnesses’ auto-load conventions (Claude Code auto-loads CLAUDE.md at startup, etc.).

aibox init always creates AGENTS.md (write-if-missing — never overwrites). When the Claude harness is enabled, it also creates CLAUDE.md, either as a thin pointer (default) or with the full rich content (provider_mode = "full"). Other harnesses (Aider, Gemini, Codex, Copilot, Continue) use config files rather than markdown entries and are not affected by this section.

Existing files are never overwritten. If you already have a hand-written AGENTS.md or CLAUDE.md, aibox init leaves it alone.

[customization]#

Visual and layout configuration. See Themes and Layouts for details.

[audio]#

Audio bridging configuration.

Legacy [container.audio] input is still accepted for compatibility. Fresh scaffolding writes top-level [audio].

[integrations.github]#

GitHub integration behavior for generated runtime Git configuration.

This setting selects the generated Git credential helper; it does not select or store a GitHub token. Configure scoped tokens or a persistent GitHub CLI login through the local GitHub authentication guidance.

Apply Behavior#

Environment Variable Overrides#

Some settings can be overridden via environment variables:

Example:

AIBOX_WORKSPACE_DIR=/home/user/projects/my-app aibox up

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

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.5" }    # 0.7, 0.11.10, 0.11.11, 0.11.15, 0.11.19, 0.11.26, 0.12.0, 0.12.5
# poetry = { version = "2.4.1" } # Optional: 1.8, 2.0, 2.4.1
# pdm = { version = "2.28.1" }   # Optional: 2.22, 2.26.9, 2.27.0, 2.28.0, 2.28.1

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.22.0" }  # 9, 10, 11.1.3, 11.5.2, 11.10.0, 11.18.0, 11.20.0, 11.21.0, 11.22.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.6" }     # 1.25, 1.26, 1.26.3, 1.26.4, 1.26.5, 1.26.6

Installs Go and sets up GOPATH.

Production Go groups#

Go projects can compose production tooling without bloating the base runtime:

[addons.go]

[addons.go.infrastructure]

[addons.go.quality.tools]
staticcheck = { enabled = false } # optional per-tool override

[addons.go.supply-chain]

[addons.go.release]

# Optional nested container engine without the other infrastructure defaults:
[addons.go.infrastructure.tools]
opentofu = { enabled = false }
ansible = { enabled = false }
packer = { enabled = false }
podman = {}

quality installs goimports, staticcheck, golangci-lint, govulncheck, and gosec, plus the Linux compiler and libc headers required by go test -race ./.... supply-chain adds gitleaks, osv-scanner, syft, grype, and cosign. release adds GoReleaser, ShellCheck, and Hadolint. The built-in gofmt, go vet, go test, fuzzing, and coverage commands remain part of the Go toolchain and need no extra binary. The optional podman selection installs a rootless container engine and its Compose provider. The explicit disables keep OpenTofu, Ansible, and Packer out when the project only needs nested container operations.

The same infrastructure, security/supply-chain, and release group names are accepted below every language addon. Go additionally exposes quality and its lint alias.

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.

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 pinned brand-theme-hugo-vanilla module. Hugo Extended, Go, and Node.js are required; the project devcontainer enables all three through aibox addons.

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.

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
• local temporary-workspace E2E and isolated tmux/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/projectious.work brand-theme 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. 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 summarized in dist/RELEASE-TIMINGS.md; host-side timings are summarized in dist/RELEASE-HOST-TIMINGS.md. Each summary is a cumulative view of the append-only timing-events.tsv file beside the candidate evidence, so retries and resumed release commands retain failed, passed, and reused gate attempts instead of replacing the earlier timings.

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#

The container-side release prepares a checksummed source archive and provenance record under tmp/host-gates/aibox-release/<run-id>/input/. It writes the single owner command to dist/RELEASE-PROMPT.md:

./scripts/maintain.sh release-host tmp/host-gates/aibox-release/<run-id>

For an evidence-only rehearsal, append --dry-run. Validation still performs all candidate builds, probes, cleanup, SBOM generation, vulnerability scanning, and manifest hashing, but it does not invoke GitHub or GHCR publication. The validator prints the separate publisher command that can consume the verified run directory later.

Interactive terminals use the Textual dashboard by default (--ui=auto). Use --ui=textual to fail if the dashboard cannot start, or --ui=plain for redirected and captured output. The UI presents a high-level progress bar, a persistent task list, and a selectable task-filtered log. Space toggles follow, w toggles wrapping, Ctrl+A/C selects and copies, y copies the selected task log, End resumes the live tail, and p displays the authoritative evidence path. The UI is presentation rather than evidence; full output is retained in evidence/command-results.log.

Content-addressed container layers are reused by default. The Rust registry is shared in a dedicated credential-free host-gate cache, while compiled artifacts are isolated by candidate commit so a failed candidate can be retried without a full two-target rebuild. Use --cold-cache only when deliberately investigating cache behavior. Cold mode retains downloaded Rust packages but forces downstream container layers to rebuild.

To retry after a conditional addon or lifecycle check fails, prepare a new run and name the failed run as its checkpoint source:

NEW_RUN="$(./scripts/maintain.sh release-host-prepare X.Y.Z)"
./scripts/maintain.sh release-host \
  --retry-from=tmp/host-gates/aibox-release/<failed-run-id> "${NEW_RUN}"

The retry source must contain byte-identical immutable candidate inputs. Completed conditional checks are reused only when their candidate-bound checkpoint checksum is valid. The candidate lifecycle, SBOM, vulnerability scan, cleanup, manifest assembly, and publication verification remain fresh.

The reviewed entry point accepts only that run-directory path. It rejects traversal, symlinks, special files, hardlinks, unexpected inputs, unsafe permissions, checksum drift, and tag/commit mismatches. A previous partial run is never resumed in place: runtime/ and evidence/ must not exist in the new run when it starts. Retry imports only validated conditional checkpoints. The host checkout’s HEAD must match the attested candidate commit, but unrelated tracked worktree edits do not invalidate the gate because all builds and probes use the immutable checksummed source archive rather than worktree contents.

Validation and publication are separate security stages within the one owner invocation. Candidate-controlled native builds, build scripts, CLI commands, and the generated runtime smoke receive a fixed environment and run under a macOS sandbox that denies GitHub configuration, Docker configuration, SSH material, and Keychain services. Docker uses an empty per-run configuration; no publication credential, secret, broad mount, or runtime socket is exposed to the development container or candidate container.

The entry point accepts owner-installed uv from the official standalone path ~/.local/bin/uv or the architecture-native Homebrew prefix. It verifies ownership and rejects group/world-writable executables instead of searching an inherited PATH. It lets uv resolve, install when necessary, and run exact Python 3.14.6 under --no-project, fixed owner cache/managed-Python roots, and a fully rebuilt environment. The gate invokes python as uv’s command rather than handing the script to uv, so candidate inline script metadata is not processed. Candidate project metadata and inherited UV_* settings cannot select the interpreter or dependencies.

The validation stage builds both Darwin targets, natively smokes the current architecture, builds the actual candidate foundation/runtime images, exercises the generated Compose lifecycle and --forget-tmux-state, requires cleanup, generates a CycloneDX SBOM, and applies the reviewed Grype policy. High or Critical findings with a listed fixed version block the release; findings with no listed fix remain explicit non-blocking warnings in the evidence. It also verifies the checksummed comparison tag, commit, and changed-path list, then runs affected addon build groups, the LaTeX watcher/preview lifecycle, and the rootless Podman readiness probe when relevant inputs changed. The readiness probe verifies the unprivileged binaries, subordinate ID ranges, namespace helpers, storage/network helpers, and container configuration without granting the outer development container privileges for nested user-namespace execution. No comparison tag selects all three surfaces. Every command, selection reason, skip reason, and result is retained beneath evidence/ with toolchain metadata, image inspection, runtime logs, hashes, and a release manifest.

The terminal interface streams subprocess output as it is produced. Each high-level operation reports running, passed, or failed state with elapsed time, and quiet commands emit a heartbeat every ten seconds. The same transitions are retained in evidence/steps.log; full argv and output remain in commands.log and command-results.log, so interactive progress does not replace auditable evidence. The terminal groups High/Critical package matches by unique advisory and prints a bounded summary with severity, affected package names, and disposition. The complete scanner report remains at evidence/security/vulnerability-scan.json; counts, grouped advisories, package versions, fix versions, and the blocking or warning classification are publication-required evidence in evidence/security/vulnerability-policy.json.

The gate selects the first responsive runtime in this order: the docker CLI contract exposed by Docker Desktop or OrbStack, then Podman. All image builds, Compose lifecycles, exec probes, inspection, cleanup, scanning, and publication use that selected runtime. Docker-compatible builds explicitly enable BuildKit for features such as COPY --chmod; OrbStack does not need Docker Desktop’s separate Buildx component. When Compose and Buildx are installed as Docker CLI plugins, the gate copies only those owner/root-owned, non-group-writable executables into its empty per-run DOCKER_CONFIG. It does not copy the owner’s Docker configuration, registry credentials, contexts, or unrelated plugins.

Before the Darwin build, the gate fetches the exact locked Cargo dependency graph into a per-run credential-free Cargo home. The actual compilation remains offline, so a newly locked crate does not require a pre-warmed owner cache and candidate build scripts do not receive network access.

Only after every gate succeeds does the separate publisher receive normal host GitHub/GHCR authority. It revalidates the immutable manifest and can upload only the two Darwin archives plus checksums and push only the fixed aibox foundation-version, runtime-version, and runtime-latest tags. It cannot build, run tests, execute candidate code, commit, merge, or accept extra arguments. Remote asset and image inspection is mandatory.

On failure, keep the run directory as diagnostic evidence. Correct the source, create a new candidate commit/tag, and prepare a new run ID; do not edit the old input or selectively reuse its evidence. The owner must review changes to the gate and publisher before using a changed version.

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.

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.1
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.5" }

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