aibox

Base Image

Mon, 01 Jan 0001 00:00:00 +0000

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

Tool	Version / Source	Purpose
tmux	Debian package	Terminal multiplexer
Yazi	25.4.8 (prebuilt binary from GitHub releases)	Terminal file manager
Vim	Debian package (`vim` + `vim-runtime`)	Editor
Git	Debian package	Version control
Claude CLI	Official install script	AI assistant
ripgrep (`rg`)	Debian package	Fast recursive search (grep replacement)
fd	Debian package	Fast file finder (find replacement)
bat	Debian package	Syntax-highlighting cat replacement
eza	Debian package	Modern ls replacement with git integration
zoxide	Debian package	Smarter cd that learns your habits
fzf	Debian package	Fuzzy finder for files, history, and more
delta	Debian package	Syntax-highlighting diff viewer (used by git)
starship	Prebuilt binary	Minimal, fast shell prompt with context
curl	Debian package	HTTP client
jq	Debian package	JSON processor
less	Debian package	Pager
unzip	Debian package	Archive extraction
iproute2	Debian package	Network route/interface inspection for status segments
iputils-ping	Debian package	ICMP latency checks for status segments
bash-completion	Debian package	Shell completions
ca-certificates	Debian package	TLS root certificates
locales	Debian package	Locale support (en_US.UTF-8)
tzdata	Debian package	Timezone data

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.

CLI Commands

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

aibox uses a small verb/resource grammar. aibox.toml is desired state. The established v0 runtime uses apply then up; v1 orchestration uses image, deploy, up (apply-only), and an explicit connect.

Global Options

Option	Environment Variable	Default	Description
`--config <PATH>`	–	`./aibox.toml`	Path to configuration file
`--log-level <LEVEL>`	`AIBOX_LOG_LEVEL`	`info`	Log verbosity
`-y`, `--yes`	–	–	Skip confirmation prompts

Core Workflow

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

Command Grammar

aibox init [NAME] [OPTIONS]
aibox apply [RESOURCE] [NAME] [OPTIONS]
aibox up [OPTIONS]
aibox down [--legacy-runtime]
aibox image <build|inspect> [--output human|json]
aibox deploy <plan|apply|status|destroy|logs> [OPTIONS]
aibox connect <NAME> [-- COMMAND...]
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.

Context Overview

Mon, 01 Jan 0001 00:00:00 +0000

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.

Create a local project with processkit

Mon, 01 Jan 0001 00:00:00 +0000

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.

Installation

Mon, 01 Jan 0001 00:00:00 +0000

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.

Overview

Mon, 01 Jan 0001 00:00:00 +0000

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.

Overview

Mon, 01 Jan 0001 00:00:00 +0000

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.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

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.0" }

[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 = "gruvbox" # Theme family; concrete legacy names still parse
mode = "auto" # Theme mode: auto, light, dark
prompt = "default" # Starship preset (8 options)
layout = "dev" # tmux layout (4 options)

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

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

Container Configuration

Mon, 01 Jan 0001 00:00:00 +0000

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.

Language Runtimes

Mon, 01 Jan 0001 00:00:00 +0000

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.

Maintenance

Mon, 01 Jan 0001 00:00:00 +0000

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.

New Project

Mon, 01 Jan 0001 00:00:00 +0000

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:

Option	Default	Description
`--base`	`debian`	Base image
`<NAME>`	Current directory name	Container and hostname
`--profile`	`human-dev`	Usage profile: `human-dev` or warning-mode `headless-runner`
`--harness`	`claude`	AI harnesses (can be repeated): `claude`, `codex`, `gemini`, `aider`, etc.
`--addon`	—	Addon names (can be repeated): `python`, `rust`, `node`, `go`, `latex`, etc.
`--theme`	`gruvbox`	Theme family
`--context-mode`	`processkit`	Context layer: `processkit` or `harness-only`
`--processkit-version`	latest stable tag	processkit content release to pin; explicit prerelease pins are supported

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

Prompt Presets

Mon, 01 Jan 0001 00:00:00 +0000

Starship Prompt Presets

aibox includes 8 Starship prompt presets that work with any theme. Set a preset in aibox.toml:

[customization]
prompt = "default"

Available Presets

default

Full-featured two-line prompt with directory, git branch/status, language versions, and command duration. Uses Nerd Font symbols.

 ~/workspace/myproject main ✓ v1.75.0 took 2s
❯

plain

Same information as default but uses ASCII characters only — no Nerd Font or special font needed. Works in any terminal.

~/workspace/myproject [main +1 !2] [v1.75.0] took 2s
>

Good for remote SSH sessions or environments without font customization.

Skill Selection

Mon, 01 Jan 0001 00:00:00 +0000

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.

Mon, 01 Jan 0001 00:00:00 +0000

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:

Audio Support

Mon, 01 Jan 0001 00:00:00 +0000

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.

Custom Themes

Mon, 01 Jan 0001 00:00:00 +0000

Creating Custom Themes

aibox ships 7 built-in themes. You can create a custom theme by adding entries to the CLI source code.

Theme Structure

Each theme defines colors for 5 tools:

Tool	Config Location	Format
tmux	`.config/tmux/themes/<name>.conf`	tmux style settings
Vim	`.vim/colors/<name>.vim`	Vim colorscheme
Yazi	`.config/yazi/theme.toml`	TOML with hex colors
lazygit	`.config/lazygit/config.yml`	YAML gui.theme section
Starship	`.config/starship.toml`	TOML with palette

Color Mapping

A theme needs these terminal color slots for tmux:

E2E Test Catalogue

Mon, 01 Jan 0001 00:00:00 +0000

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	Where it runs	What it needs
Tier 1	Local temp directory	The compiled `aibox` binary only
Tier 1 + Mock	Local temp directory	Binary + mock `docker`/`podman` scripts on PATH
Tier 2	Remote SSH companion	`aibox-e2e-testrunner` container reachable (feature flag `e2e`)

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.

Existing Project

Mon, 01 Jan 0001 00:00:00 +0000

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

init will not overwrite

If aibox.toml already exists, init will refuse to run. Either delete the existing file or edit it directly.

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:

Layouts

Mon, 01 Jan 0001 00:00:00 +0000

Layouts

aibox ships four tmux layouts. Harness placement follows [ai].harness_order: the 1st harness is the first enabled harness in that order, then the 2nd, 3rd, and so on. Enabled harnesses missing from harness_order are appended in canonical order.

Generated layouts can include an extended PowerKit status bar with host, network, development, cloud, resource, and aibox runtime segments.

Available Layouts

ai

Window	Contents
1 · work	left 50%: yazi · right 50%: 1st harness
2 · ai	all further harnesses, split as full-height even horizontal panes
3 · lazygit	lazygit, when `git-ui` selects `lazygit`
3/4 · shell	bash

dev

Window	Contents
1 · work	left 50%: yazi top 50% / 1st harness bottom 50% · right 50%: shell
2 · lazygit	lazygit, when `git-ui` selects `lazygit`
2/3 · ai	all further harnesses, split as full-height even horizontal panes
final · shell	bash

focus

Window	Contents
1 · files	yazi
2..n · harness name	one fullscreen window per harness in `harness_order`
next · lazygit	lazygit, when `git-ui` selects `lazygit`
final · shell	bash

cowork

Window	Contents
1 · work	left 50%: yazi · right 50%: shell
2 · ai	all harnesses, split as full-height even horizontal panes
3 · lazygit	lazygit, when `git-ui` selects `lazygit`

Setting The Default Layout

[customization]
layout = "dev"

Options: dev, focus, cowork, ai.

Local Config (.aibox-local.toml)

Mon, 01 Jan 0001 00:00:00 +0000

Local Config (.aibox-local.toml)

.aibox-local.toml is a personal, gitignored overlay that sits next to aibox.toml in the project root. It exists for secrets and per-developer settings that must never be committed to version control — API tokens, personal credential paths, and similar values that differ between contributors.

Why it exists

aibox.toml is committed and shared across the team. That’s the right place for project-wide settings: container name, context mode, processkit version when processkit is enabled, addons, shared environment variables, and so on. But tokens and personal bind mounts don’t belong there. .aibox-local.toml gives every developer a private escape valve without requiring .gitignore discipline on every secret.

Migration

Mon, 01 Jan 0001 00:00:00 +0000

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.

v0.16.0 — `context/AIBOX.md` is gone

Pre-v0.16 releases generated a context/AIBOX.md “universal baseline” file on every aibox apply. That file has been removed as part of the aibox⇄processkit split. The canonical agent entry document is now AGENTS.md at the project root. In processkit mode it is rendered from processkit scaffolding; in harness-only mode it is a minimal aibox-owned file. In both modes aibox init writes it only when missing.

Tool Bundles

Mon, 01 Jan 0001 00:00:00 +0000

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.

Cheatsheet

Mon, 01 Jan 0001 00:00:00 +0000

Keyboard Shortcuts

Quick reference for all tools in the aibox environment. Press the tab for the tool you need.

!!! tip “In-app help” - tmux: The status bar always shows available keys for the current mode - Yazi: Press ~ or F1 to see all keybindings - Vim: Type :help for built-in help - lazygit: Press ? to see context-sensitive keybindings when the optional git-ui addon is enabled

=== “tmux”

Custom Prompts

Mon, 01 Jan 0001 00:00:00 +0000

Creating Custom Prompts

aibox generates Starship prompt configurations from the selected preset and theme. You can customize the prompt by editing the generated config.

Generated Config Location

After aibox apply, the Starship config is at:

.aibox-home/.config/starship.toml

Manual Customization

Edit .aibox-home/.config/starship.toml directly with any valid Starship configuration. Changes take effect immediately in new shell sessions.

Apply overwrites

aibox apply regenerates starship.toml from the preset and theme. To preserve manual edits, either avoid running apply or back up your config first.

Documentation Frameworks

Mon, 01 Jan 0001 00:00:00 +0000

Documentation Framework Addons

Documentation addons install static site generators and documentation tools.

Addon	Tool	Install Method
`docs-mkdocs`	MkDocs + Material theme	uv
`docs-zensical`	Zensical	uv
`docs-docusaurus`	Docusaurus	npm
`docs-starlight`	Starlight (Astro)	npm
`docs-mdbook`	mdBook	Binary download
`docs-hugo`	Hugo Extended	Binary download

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

File Preview

Mon, 01 Jan 0001 00:00:00 +0000

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:

Mechanism	When to use
Yazi file preview	Browsing files — preview appears automatically in the right panel as you navigate
Standalone TUI viewers	Viewing a specific file in a pane, or piping output from a build tool

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

Claude

Mon, 01 Jan 0001 00:00:00 +0000

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.

Runtime Operations

Mon, 01 Jan 0001 00:00:00 +0000

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

Aider

Mon, 01 Jan 0001 00:00:00 +0000

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

Gemini

Mon, 01 Jan 0001 00:00:00 +0000

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

Mon, 01 Jan 0001 00:00:00 +0000

V1 deployment boundaries and prerequisites

V1 is a deployment control plane for immutable workspace images; it is not a cluster, DNS-zone, ingress-controller, secret-manager, or processkit installer. It compiles typed desired state, records ownership, and asks an already-provisioned backend to reconcile only the resources it owns.

Infrastructure supplied by the operator

Before enabling a Kubernetes target, supply all of the following outside aibox:

a reachable kube context with a namespace aibox is allowed to manage;
an existing ingress class or gateway class when ingress is configured;
an existing DNS zone when DNS reconciliation is configured;
credential references that the selected backend can resolve, never secret values in aibox.toml;
an immutable image reference and sha256: digest;
a least-privilege identity limited to the target namespace and the selected DNS record scope.

Aibox refuses foreign, unlabeled, digest-mismatched, or missing-record resources during guarded destroy. These checks protect against accidental deletion; they are not a replacement for namespace policy, admission control, or credential rotation.

Mistral

Mon, 01 Jan 0001 00:00:00 +0000

Mistral (SDK)

SDK addon — not an interactive CLI

The ai-mistral addon installs the mistralai Python SDK, not an interactive coding CLI. It is intended for projects that call the Mistral API programmatically. For an interactive coding experience, use Claude, Gemini, OpenAI Codex, or Copilot instead.

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:

Version-line porting

Mon, 01 Jan 0001 00:00:00 +0000

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.

OpenAI (Codex CLI)

Mon, 01 Jan 0001 00:00:00 +0000

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.

V1 support, deprecation, and retirement

Mon, 01 Jan 0001 00:00:00 +0000

V1 support, deprecation, and retirement

V1 prereleases are evaluation releases. Until a stable v1 release satisfies every candidate-bound readiness gate, v0 remains supported as the stable line. V1 and v0 may coexist while projects evaluate migration; neither line may manage or destroy the other line’s deployment records or resources.

Product boundaries

ainfra provisions accounts, hosts, networks, clusters, identities, DNS zones, and other infrastructure, then exposes non-secret target references.
aibox deploys immutable AI workspace images onto existing Compose or Kubernetes targets. It does not provision infrastructure.
processkit owns process distribution, installation, migrations, MCP, skills, schemas, and harness projections. Aibox’s v1 integration is disabled or delegates one opaque request to the processkit CLI.

These boundaries are release requirements. The portfolio audit fails if the v1 production path begins interpreting processkit policy or provisioning infrastructure.

Copilot (GitHub)

Mon, 01 Jan 0001 00:00:00 +0000

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

Continue

Mon, 01 Jan 0001 00:00:00 +0000

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

V1 adoption pilots

Mon, 01 Jan 0001 00:00:00 +0000

V1 adoption pilots

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

a new Compose workspace can compile and render a deterministic plan;
a representative v0 project can preview, apply, and roll back a reviewed v1 intent without exposing secrets or touching v1 deployment records;
an existing Kubernetes target passes the complete live M7c lifecycle;
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:

Compatibility

Mon, 01 Jan 0001 00:00:00 +0000

Compatibility

aibox ↔ processkit Version Matrix

Each aibox release is tested against a specific processkit version. The table below shows the minimum compatible processkit version for each aibox release.

aibox version	Min. processkit	Notes
1.0.0-alpha.1	v0.28.4 stable bridge; v1.0.0-alpha.3 installer exact pin	opt-in v1 orchestration alpha with signed opaque processkit installer delegation; the v0 bridge remains until parity, rollback, interruption, migration, and secret-safety gates pass
0.28.14	v0.28.4	ensures `pk-reconcile` and `pk-repo-reconcile` install their `project-reconciliation` and `repo-management` skill dependencies
0.28.15	v0.28.4	refreshes bundled maintenance tools, locks `cargo-audit` installation for Rust compatibility, and publishes the Hugo/Docsy documentation site
0.28.13	v0.28.4	adds open GitHub Discussion counts to the tmux Forge status segment and restores the complete generated Codex command projection set
0.28.12	v0.28.4	integrates processkit v0.28.4 and makes companion E2E validation work from linked release worktrees
0.28.11	v0.28.3	adds the `cloudflare` addon, which installs cloudflared from Cloudflare’s signed package repository rather than Debian’s archive
0.28.10	v0.28.3	reconciles standard processkit skills, recommends tooling-linked skills interactively, upgrades prerelease processkit surfaces, and serializes release Tier 2 E2E validation
0.28.6	v0.28.3	fixes Kubernetes addon checksum verification for Helm, Kustomize, and k9s archives on amd64 and arm64; and integrates processkit v0.28.3 authenticated GitHub repository reconciliation
0.28.5	v0.28.1	fixes Hermes Agent installation under the non-root runtime model; restores configured lazygit runtime surfaces; completes processkit reconciliation; and enforces traceable ports between maintained v0.x and v1.x lines
0.28.4	v0.28.1	integrates processkit v0.28.1 and refreshes the maintained v0.x processkit compatibility baseline
0.28.3	v0.27.6	integrates processkit v0.27.6; makes GitHub CLI authoritative for `github.com` HTTPS credentials; exposes exact GitHub SSH aliases through Forge; and preserves LaTeX preview state across rebuilds
0.28.2	v0.27.5	integrates derived-project doctor applicability fixes, Git-ignore-aware sensitive-data scanning, 30-day archive-age enforcement, generated schema foundations, migration drafting, repository portfolio review, and refreshed gateway metadata
0.28.1	v0.27.4	restores Codex processkit aliases through `/prompts:pk-*`; adds local fuzzy documentation search; moves LaTeX build and watch ownership into the development container; and adds a hardened read-only, multi-document preview sidecar with full lifecycle coverage
0.28.0	v0.27.4	adds named LaTeX build, watch, status, and EmbedPDF live-preview workflows; manages preview lifecycle through `aibox up`/`down`; generates project-local agent guidance; and documents persistent, least-privilege GitHub authentication with explicit per-destination tokens
0.27.8	v0.27.2	integrates processkit derived-project remediation: project-local `pk-commands` preservation/schema validation, timestamped role-slot binding IDs, explicit doctor confirmation forwarding, archive remediation metadata, migration archive policy documentation, and refreshed gateway metadata
0.27.7	v0.27.1	fixes the TeX Live historic installer mirror, resolves pk-doctor false positives, preserves disabled harness state, and accepts context mode in schema validation
0.27.6	v0.27.1	refreshes tool and harness pins, updates generated runtime/docs references, and adds the GitHub CLI credential-helper integration for HTTPS Git operations
0.27.5	v0.27.1	refreshes the shipped docs-hugo pin to Hugo 0.162.1 and aligns release-state/docs inventory with the current addon and harness defaults from v0.27.4
0.27.4	v0.27.1	refreshes all shipped addon and harness tool defaults to current upstream releases; fixes Yarn 4 and Python 3.14 installation paths; moves Hermes to the current `hermes-agent` package installer; updates Rust/docs dependencies; and quiets actionable pk-doctor false positives while making release-integrity checks bounded
0.27.3	v0.27.1	integrates processkit v0.27.1 derived-project health cleanup, including quieter pk-doctor sensitive-data checks, gateway-aware preauth validation, sqlite-vec availability for pk-doctor MCP runs, supply-chain policy no-policy INFO handling, and a Codex processkit-gateway startup timeout so uv-backed gateway startup does not trip Codex’s 30-second default
0.27.2	v0.27.0	fixes the `docs-hugo` addon checksum verification so Hugo archives downloaded to `/tmp/hugo.tar.gz` are checked against the matching release checksum entry instead of the upstream asset filename
0.27.1	v0.27.0	refreshes addon and user-facing toolchain pins, including documentation generators, language package managers, infrastructure tooling, Kubernetes tools, Helm, and OpenCode; adds release-state coverage for addon pins plus LaTeX and apt-managed inputs; keeps Python interpreter selection tied to the Debian base image package set; fixes OpenCode release asset naming and checksum verification; updates docs-site dependencies and clears npm audit findings
0.27.0	v0.27.0	integrates processkit v0.27.0 and the v0.26.17 supply-chain audit surface; switches the next-minor GHCR image scheme to foundation/runtime tags, stops publishing public source-hash marker tags, preserves legacy `base-debian-v0.26.x` compatibility, adds GHCR source-tag cleanup tooling, adds release LICENSE guardrails, and fixes pasted host newlines by removing global tmux `C-j` navigation
0.26.8	v0.26.16	integrates processkit v0.26.16; refreshes the processkit template mirror, provenance, MCP manifest, TeamMember privacy defaults, and team consistency checks; makes latest image resolution skip GHCR tags whose multi-arch manifest children have been pruned
0.26.7	v0.26.15	integrates processkit v0.26.15; adds provider-neutral AI execution policy axes and per-harness overrides, maps execution policy to Codex settings, preserves the processkit MCP manifest in derived installs, and refreshes documentation recordings
0.26.6	v0.26.14	integrates processkit v0.26.14; updates processkit metadata to the new release and preserves tmux/Vim/cheatsheet and clipboard behavior consistency
0.26.5	v0.26.13	re-architects theme selection around theme families plus mode/variant, adds the 61-theme gallery and per-theme recordings, ships PowerKit/cheatsheet/runtime theme fixes, and preserves legacy concrete theme intent during standardization
0.26.4	v0.26.10	integrates processkit v0.26.10; makes explicit tmux model-provider status elements render even without global provider polling; preserves Claude Code OAuth/state across container rebuilds via Claude XDG cache/config/state mounts; enables terminal extended-key passthrough for Alt-Enter; adds PowerKit GitHub issue/PR counts; and fixes `aibox-status` AI agent counting so vendor helper processes do not inflate provider instance totals
0.26.3	v0.26.9	fixes GHCR latest-version resolution by requesting larger tag-list pages and following Docker Registry v2 pagination links so freshly-published images are visible to `aibox apply`
0.26.2	v0.26.9	fixes duplicate `[customization.tmux.status]` table parsing, routes tmux helper scripts through the managed socket, removes structurally broken capture-pane visual tests, and keeps visual layout/theme work tracked for asciinema coverage
0.26.1	v0.26.9	verifies GHCR release-host image pushes, fixes Yazi rich-preview API/cache behavior, suppresses recurring legitimate processkit template mirror repair warnings, emits migration affected files, and integrates processkit v0.26.9
0.26.0	v0.26.7	refreshes themes, live tmux layout/theme choosers, Yazi rich preview, Vim Alt-key handling, model-provider agent counts, statusline structure, and processkit v0.26.7 integration
0.25.14	v0.26.5	integrates processkit v0.26.5; restores generated and image fallback Alt-word movement in Vim/readline; adds managed `.inputrc` runtime projection; carries tmux clipboard/terminal feature improvements into generated and image fallback configs; keeps Rust cache mounts from shadowing image-provided cargo/rustc shims; and keeps the stricter processkit schema/file-layout migration path clean under pk-doctor
0.25.13	v0.26.2	fixes stale runtime-home propagation by making aibox-managed `.aibox-home` files authoritative on apply and clean runtime recreation; broadens generated runtime mounts for Vim and Cargo cache directories; updates generated compose/docs coverage; and adds regression coverage for stale tmux/Yazi managed file refresh
0.25.12	v0.26.2	fixes fresh-project tmux/PowerKit runtime projection by using broad writable runtime-home mounts, refreshing managed theme/Yazi/Codex files on apply, scoping preauth/MCP writes to enabled harnesses, recognizing nested processkit skill catalogs in doctor, and reducing host-side doctor probes for container-owned dependencies
0.25.11	v0.26.2	fixes source-checkout addon discovery, PowerKit status cache writability, generated runtime writability diagnostics, disabled-harness migration schema metadata, and tmux/Yazi status glyph defaults
0.25.10	v0.26.2	integrates processkit v0.26.2; adds configurable tmux status labels/layouts and model-provider health segments; reduces PowerKit refresh churn; stabilizes runtime MCP diagnostics; verifies release checksum sidecars; and improves image layer/cache reuse across apply/up and host release publishing
0.25.9	v0.26.1	integrates processkit v0.26.1; retires yazi-omp runtime support; migrates tmux status configuration to list-based slot ordering; preserves user-selected themes during standardization; suppresses Kubernetes/cloud PowerKit auth/probe flashes; and improves Yazi directory git status behavior
0.25.8	v0.26.0	improves the tmux log viewer, filters aibox log counts to the current container session, emits low-volume diagnostics sidecar lifecycle samples, moves PowerKit metrics into the owner-specified two-row layout, and updates generated tmux layouts around ordered harness semantics
0.25.7	v0.25.8	introduces generated-container cleanup controls, prunes SSH companion nested runtime state around Tier 2 E2E tests, adds `aibox prune`, and documents managed runtime cleanup policy
0.25.6	v0.25.8	expands tmux/PowerKit theme coverage with light/dark partner handling, generated theme comments, Docusaurus theme documentation, and runtime border/status color improvements
0.25.5	v0.25.8	refreshes managed tmux runtime files when recreating sessions so `aibox.toml` status/layout settings take effect, preserves the delayed Yazi pane startup path, and suppresses stale default-socket tmux kill-session noise on host attach
0.25.4	v0.25.8	repairs tmux release-host smoke probing after the managed tmux socket migration and fixes generated tmux status-right rendering by preserving the aibox runtime status segment
0.25.3	v0.25.8	fixes Yazi `e` editor handoff for tmux by targeting the existing Vim pane/window, documents tmux status modes and element toggles, makes skill-finder discover deselected skills from the template catalog, and tightens SSH companion guidance
0.25.2	v0.25.8	adds tmux-native `prefix ?` keybinding popup, upgrades the two-line PowerKit status with pane context/mode detail, labels status metrics in `aibox-status`, fixes startup layout targeting by selecting named tmux windows instead of `$session:1`, extends release/runtime caching behavior, and documents provider endpoint base URL hints (`ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL`, `GEMINI_BASE_URL`, `MISTRAL_BASE_URL`)
0.25.0	v0.25.8	replaces the prior multiplexer runtime with tmux-native layouts and status, keeps the diagnostics sidecar and visual testing gates, documents TPM as a user convenience layer only, preinstalls and pins aibox-managed tmux plugins, and ships `tmux-resurrect`/`tmux-continuum` installed but disabled by default until persistence policy is decided
0.24.1	v0.25.8	fixes generated compose so the main service starts with the image default root entrypoint user again, allowing `entrypoint.sh` to remap/drop to `aibox` instead of failing with `failed switching to "aibox": operation not permitted` during release-host runtime smoke
0.24.0	v0.25.8	adds the bounded diagnostics sidecar, replaces the shell fan-out `aibox-status` helper with Rust snapshot readers, wires sidecar-backed Zellij status rows, adds `aibox emergency <harness>`, keeps legacy `native`/`hidden` status aliases while emitting `sidecar`/`disabled`, and reduces host release smoke to a minimal default tier with opt-in addon/full tiers
0.23.21	v0.25.8	repairs generated Yazi git/status initialization for Yazi 26; preserves native Zellij plugin permission caches across runtime starts; adds doctor and E2E guardrails for native Zellij permission-cache projection drift; installs the Yazi `ya` companion entrypoint in runtime images; slims visual E2E release gates with per-case progress logging and an opt-in exhaustive matrix
0.23.20	v0.25.8	makes the release runtime smoke harness host-safe by defaulting to shell Zellij status mode, capturing raw TUI output into logs instead of streaming escape sequences to the host terminal, and asserting on structured probe markers rather than terminal transcripts
0.23.19	v0.25.8	hardens generated runtime startup by keeping Vim eager while disabling its startup cursor-position probe; removes suspended generated AI panes; pre-seeds native Zellij plugin permissions; fixes service-specific Codex bubblewrap seccomp fallback; updates Yazi git/preview config; adds generated-runtime and opt-in visual E2E release gates
0.23.18	v0.25.8	updates generated Yazi config and theme filetype rules for Yazi 26’s url/mime matcher schema; provides writable XDG state mounts for lazygit and similar TUIs; records follow-up runtime diagnostics and host-phase runtime smoke work
0.23.17	v0.25.8	installs Claude Code from Anthropic’s signed apt repository with a stable `/usr/local/bin/claude` path; makes the native aibox Zellij status/key-hint plugin the generated default; starts shell and lazygit tabs hot across layouts; refreshes Zellij, Yazi, uv, and Cargo dependencies; improves release-state reporting and harness version-pin support
0.23.16	v0.25.8	moves Claude processkit command shims to Claude Code’s current Skills layout, cleans legacy managed `.claude/commands` files, fixes native Zellij key-hint rendering, keeps Vim editor panes hot for Yazi edit handoff, and adds a pre-release dependency/harness state report
0.23.15	v0.25.8	fixes a 0.23.14 `--standardize-config` regression where a blank `[ai.harness.<name>]` table could re-enable a commented-out harness; standard config rewrites also restore the standard processkit skill list instead of leaving every skill commented
0.23.14	v0.25.8	canonical generated `aibox.toml` now uses `[ai.harness.<name>]` tables instead of the compact harness list; `aibox apply --standardize-config` performs an opt-in schema-clean canonical rewrite; stale/deprecated generated comments were removed; Yazi `e` again opens files in the dedicated Vim pane/tab
0.23.13	v0.25.8	fixes 0.23.11-to-0.23.12 generated-config upgrades where a moved tool, such as `gh`, still sits under its old addon owner; `aibox apply` now migrates misplaced addon tool entries to their unique current catalog owner before strict validation and comment refresh
0.23.12	v0.25.8	processkit v0.25.8 Xiaomi MiMo model-routing content and cleanup-hint provenance, native aibox Zellij key/status bar refinements, semantic AI/audio config sections, stable Claude CLI install path, addon tool validation, and stale processkit-managed skill detection
0.23.11	v0.25.7	grouped `aibox.toml` schema around aibox, container, processkit, and ai sections; catalog-style AI harness/model-provider controls; generated path settings; product skill defaults; and managed Zellij status runtime repair
0.23.10	v0.25.7	processkit v0.25.7 model-routing content, apply-time `aibox.toml` structure migration, self-documenting generated config comments, addon-backed image-slimming switches, and generated-runtime release finalization
0.23.9	v0.25.6	restores shell-backed Zellij status rows as the default, hardens `aibox-status` against `/proc` races, fixes Yazi edit actions, applies addon dependency fallback handling to `aibox up`, and integrates processkit v0.25.6 provider-neutral pk command projections
0.23.8	v0.25.5	native aibox Zellij status plugin now exports the literal WASM entrypoints Zellij loads, uses theme-default readable foreground text, and has no-container E2E coverage for the load/visibility regression
0.23.7	v0.25.5	host-generated Codex processkit-gateway MCP paths now target the devcontainer workspace mount, preserving subagent-safe absolute paths without leaking host-only paths; doctor warns about stale host-side Codex MCP script paths
0.23.6	v0.25.5	processkit v0.25.5 active interlocutor runtime binding, subagent MCP lifecycle guardrails, Codex MCP path fixes, addon fallback migrations, doctor schema/runtime-template diagnostics, lazygit-disabled cleanup, native Zellij status visibility, and stronger E2E coverage
0.23.5	v0.25.4	generated Dockerfile lazygit disablement cleanup no longer aborts when lazygit is absent as an apt package, while still removing inherited lazygit binaries
0.23.4	v0.25.4	processkit v0.25.4 gateway stdio-proxy daemon startup fixes, Codex pre_tool_use hook generation, Zellij status presentation control, and stale status-layout runtime sync repair
0.23.3	v0.25.3	processkit v0.25.3 model-spec/model-profile migrations and Codex seccomp fallback for bubblewrap
0.23.2	v0.25.1	processkit v0.25.1 model-recommender lifecycle metadata, task suitability classes, task-class-aware routing, and refreshed model roster
0.23.1	v0.25.0	stale runtime cleanup for old Compose project names, lazygit disablement fixes, and procps runtime diagnostics
0.23.0	v0.25.0	processkit v0.25.0 gateway integration, daemon-proxy mode, runtime pressure diagnostics, init reaping, optional git UI tools, and profile-aware environment metadata
0.22.0	v0.24.0	processkit v0.24.0: context archiving, richer model routing metadata, semantic task-router scoring, archive-aware index metadata
0.21.2	v0.23.1	processkit v0.23.1 release-audit cleanup and skill metadata fixes
0.21.1	v0.23.0	processkit v0.23.0 model governance and release-audit integration
0.21.0	v0.22.0	multi-harness slash-command scaffolding and content-diff safety fixes
0.20.0	v0.22.0	processkit install integrity, preauth merge, and no-container scaffold mode
0.19.0	v0.21.0	MCP permission configuration and processkit v0.21 content integration
0.17.16	v0.13.0	BREAKING: rename `providers = ["codex"]` → `["openai"]`; fix zellij `--layout` flag; fix Rust x86_64 cross-compile target
0.17.15	v0.13.0	MCP config model, zjstatus hints, Zellij Ctrl+q, processkit v0.13.0
0.17.5	v0.8.0	processkit v0.8.0 GrandLily src/ restructure
0.17.4	v0.6.0	content migration documents (pending/in-progress/applied)
0.17.3	v0.6.0	Claude Code slash-command adapters
0.17.2	v0.6.0	core skill enforcement, processkit v0.6.0 compat
0.17.0	v0.5.0	aibox.lock sectioned format
0.16.1	v0.4.0	sync auto-install added
0.16.0	v0.4.0	initial processkit integration

How compatibility is enforced

In processkit mode, aibox apply compares the [processkit].version in your aibox.toml against the minimum required version for the running aibox binary. If the pinned processkit version is older than the minimum, a warning is emitted:

Mon, 01 Jan 0001 00:00:00 +0000

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.

Mon, 01 Jan 0001 00:00:00 +0000

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.

Mon, 01 Jan 0001 00:00:00 +0000

Security Reference

This page documents aibox’s security model and trust boundaries.

Support and vulnerability reporting

aibox is actively maintained. The latest minor release line is supported; security and correctness fixes are released on the newest version rather than backported across older minor lines. See the repository SECURITY.md for private reporting instructions and response expectations.

Dependency and asset provenance review

The project uses several independent integrity layers:

Surface	Provenance control	Release validation
Rust CLI	`cli/Cargo.lock` pins the complete dependency graph	`cargo test`, Clippy with warnings denied, and `cargo audit`
Documentation	`docs-site/package-lock.json` and the Docsy submodule pin dependencies	clean `npm ci`, production Hugo build, and npm audit
processkit	source, version, and release-asset SHA-256 are recorded in `aibox.lock` and live provenance	installer hash verification, three-way content comparison, and pk-doctor integrity checks
Base images	release-specific image tags, OCI source/profile labels, and generated version markers	cross-platform build, GHCR publication verification, and downstream runtime smoke
Addon downloads	pinned versions plus SHA-256, signed checksum, or upstream sidecar verification where available	release-state inventory and real container lifecycle tests
Release binaries	locally cross-compiled artifacts attached to a signed release tag	version smoke tests and evidence-bound artifact checksums

The release-state report records floating inputs and available updates before each release. A clean security audit is mandatory; routine non-security drift may be deferred only into a processkit WorkItem. Provenance exceptions are documented next to the relevant installer instead of being silently accepted.

Color Themes

Mon, 01 Jan 0001 00:00:00 +0000

Themes

aibox supports consistent color theming across all terminal tools. Set a theme in aibox.toml:

[customization]
theme = "gruvbox-dark"
mode = "auto"

Or during project initialization:

aibox init --theme catppuccin-mocha

The selected theme is applied to tmux, Vim, Yazi, lazygit, and Starship simultaneously.

mode = "auto" follows the host OS light/dark appearance when a host signal is detectable during aibox apply, aibox up, or aibox set theme.*. Containers do not receive live macOS/Windows/Linux appearance-change events, so rerun one of those commands to regenerate mounted runtime theme files after changing the host appearance. If the host appearance cannot be detected, auto preserves the selected concrete theme.

LaTeX Build and Preview

Mon, 01 Jan 0001 00:00:00 +0000

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.

Roadmap

Mon, 01 Jan 0001 00:00:00 +0000

Roadmap

This page outlines planned features and improvements for aibox. The internal source of truth is the processkit work item index under context/; this page is the public-facing summary.

Current Focus

Current work is focused on making long-running AI workspaces cheaper and more predictable:

explicit Compose project and image names for each aibox project
optional tool bundles so idle containers do not carry unnecessary CLIs
suspended non-focused tmux panes
runtime resource snapshots and doctor thresholds
init-reaper support for orphaned helper processes
processkit MCP gateway adoption and daemon validation in real projects

Planned — Near Term

processkit Gateway Follow-Through

Keep validating the gateway-mode MCP defaults in downstream projects and tune daemon guidance as more host/container runtime combinations are exercised.