Reference on aibox

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.

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.

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.

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”

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.

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.

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

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.