Reference

• 1: CLI Commands
• 2: Configuration
• 3: Local Config (.aibox-local.toml)
• 4: Cheatsheet
• 5: Compatibility
• 6:

1 - CLI Commands

CLI Commands

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

Global Options

Core Workflow

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

Command Grammar

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

init

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

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

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

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

apply

Reconcile generated project state with aibox.toml.

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

Runtime

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

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

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

aibox get runtime --resources includes:

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

Inspecting Resources

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

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

Preview projections

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

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

Mutating Resources

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

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

Delete explicit resources:

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

Reset And Backup

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

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

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

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

Diagnostics

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

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

LaTeX container scripts

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

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

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

Self Management

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

Removed Old Grammar

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

2 - Configuration

Configuration

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

Full Specification

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

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

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

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

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

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

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

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

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

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

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

[addons.python.tools]                 # Addon: Python runtime
python = { version = "3.14" }
uv     = { version = "0.12.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.

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

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

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

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

[container]

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

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

[container.resource_thresholds]

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

[[container.extra_volumes]]

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

Example — mount a personal host configuration directory:

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

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

.aibox-local.toml

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

Three sections are supported:

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

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

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

[context]

Selects the project context layer.

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

[context]
mode = "harness-only"

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

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

[latex]

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

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

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

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

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

[addons]

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

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

For interactive Git tooling:

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

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

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

[skills]

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

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

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

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

See the Skills page for the full processkit boundary.

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

[ai]

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

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

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

Provider env mapping:

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

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

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

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

[processkit]

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

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

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

[processkit.context]

Processkit-mode context-system metadata.

Fetch strategy

The fetcher tries strategies in priority order:

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

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

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

Example: consume a Gitea-hosted fork

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

[ai.mcp]

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

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

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

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

processkit Gateway: [ai.mcp.gateway]

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

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

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

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

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

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

Example:

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

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

Permission Configuration: [ai.mcp.permissions]

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

Global defaults:

Per-harness overrides (optional):

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

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

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

Example:

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

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

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

[ai.execution]

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

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

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

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

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

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

[ai.agents]

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

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

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

[customization]

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

[audio]

Audio bridging configuration.

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

[integrations.github]

GitHub integration behavior for generated runtime Git configuration.

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

Apply Behavior

Environment Variable Overrides

Some settings can be overridden via environment variables:

Example:

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

3 - Local Config (.aibox-local.toml)

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.

Location and gitignore

.aibox-local.toml lives in the project root, next to aibox.toml:

my-project/
├── aibox.toml               ← committed, shared
├── .aibox-local.toml        ← gitignored, personal
├── .devcontainer/
└── context/

aibox init and aibox apply automatically add .aibox-local.toml to .gitignore. You do not need to do this manually.

Supported sections

Three sections are supported. Everything else must remain in aibox.toml.

[container.environment]

Inject environment variables into the container. These are merged on top of any [container.environment] values in aibox.toml. If the same key appears in both files, the local value wins.

[container.environment]
GH_TOKEN            = "github_pat_xxxxxxxxxxxx"
ANTHROPIC_API_KEY   = "sk-ant-api03-..."
OPENAI_API_KEY      = "sk-proj-..."
AWS_PROFILE         = "my-dev-profile"

aibox apply writes these values to the gitignored .aibox-local.env, which Docker Compose loads into the container. The values therefore survive container replacement and image rebuilds. They are still normal container environment variables: processes running as the container user, including an AI agent, can read them.

[[container.extra_volumes]]

Personal bind mounts appended after any volumes declared in aibox.toml. Each entry requires source (host path) and target (container path). read_only defaults to false.

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

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

[mcp]

Personal MCP servers appended to the generated MCP client configs on aibox apply. Use this section for servers you want only on your machine — internal tools, local scripts, or servers that require credentials you don’t want to share.

Each server entry is an [[mcp.servers]] table with the same fields as committed [[ai.mcp.servers]] in aibox.toml:

[[mcp.servers]]
name    = "my-internal-tool"
command = "npx"
args    = ["-y", "@acme/internal-mcp-server"]

[[mcp.servers]]
name    = "local-notes"
command = "/home/user/bin/notes-mcp"
args    = ["--db", "~/notes.db"]

[[mcp.servers]]
name    = "stripe"
command = "npx"
args    = ["-y", "@stripe/mcp"]
[mcp.servers.env]
STRIPE_SECRET_KEY = "sk_test_..."

aibox apply merges personal servers with team servers (from aibox.toml [ai.mcp]) and, in processkit mode, built-in processkit servers, then regenerates all MCP client config files. The generated files are gitignored — they are never committed to version control, so personal keys and server definitions stay private.

Merge behavior

GitHub authentication

Choose the authentication model according to how much GitHub access the container and its AI agents should receive. A narrowly scoped personal access token (PAT) is the recommended default. An interactive GitHub CLI login is more convenient, but may grant the container substantially broader access.

Recommended: least-privilege PATs

Put the token used for normal GitHub CLI commands in GH_TOKEN. GitHub CLI reads it automatically:

[container.environment]
GH_TOKEN = "github_pat_default_project_token"

Grant this token only the repositories and permissions the project normally needs. When one workflow needs access to another repository or organization, add a second, purpose-specific variable instead of broadening the default token. For example, a derived project can receive permission to report issues to an upstream project without receiving wider upstream access:

[container.environment]
GH_TOKEN = "github_pat_default_project_token"
PROJECTXXX_ISSUES_TOKEN = "github_pat_upstream_issues_token"

Select the second credential only for the command that needs it:

GH_TOKEN="$PROJECTXXX_ISSUES_TOKEN" \
  gh issue create --repo projectious-work/aibox

The temporary assignment overrides GH_TOKEN for that invocation only. The default token remains active for subsequent commands. Give the additional PAT only the target repository’s Issues: read and write permission plus the metadata access GitHub requires.

This arrangement makes the authorization boundary visible in both the local configuration and the command. It also lets a human decide exactly which rights are available to an AI agent in the container.

For a fine-grained PAT that targets an organization repository, select that organization as the token’s resource owner and include the target repository. Organization policy may require an administrator to approve the token. The fact that the user can create an issue in a public repository through the GitHub website does not automatically authorize a repository-scoped PAT to do the same through the API.

Alternative: persistent GitHub CLI login

For a trusted personal workspace where broad account access is acceptable, log in from inside the running container:

gh auth login --hostname github.com --web --git-protocol https --insecure-storage

--insecure-storage tells GitHub CLI to store its OAuth token in its config file instead of a system keyring. In an aibox container that file is under /home/aibox/.config/gh/, backed by the project’s gitignored .aibox-home/.config/gh/ directory. It survives container restarts, replacements, and image rebuilds. The token is a GitHub bearer credential; it is not tied to a particular container ID or image.

env | grep -E '^(GH_TOKEN|GITHUB_TOKEN)='
gh auth status
gh api user --jq .login

The stored OAuth token is plaintext in .aibox-home/.config/gh/hosts.yml. Gitignore prevents accidental normal commits, but it does not encrypt the credential or protect it from the host user, container processes, AI agents, backups, malware, or an explicit git add --force. Treat .aibox-home/ as secret-bearing local state. Prefer scoped PATs when the container should not inherit the human user’s broader GitHub authority.

Full example

A typical .aibox-local.toml for a developer working with Claude, GitHub, and AWS, plus a personal MCP server:

[container.environment]
ANTHROPIC_API_KEY = "sk-ant-api03-..."
GH_TOKEN          = "github_pat_xxxxxxxxxxxx"
AWS_PROFILE       = "my-dev-profile"
AWS_REGION        = "eu-west-1"

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

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

[[mcp.servers]]
name    = "my-internal-tool"
command = "npx"
args    = ["-y", "@acme/internal-mcp-server"]

What is NOT supported

Everything outside of [container.environment], [[container.extra_volumes]], and [[mcp.servers]] is ignored. The following must remain in aibox.toml:

• Container name, hostname, user, lifecycle, image, and generated paths
• [context] — context mode and processkit package selection
• [addons] — addon configuration
• [processkit] — content source and version pin when processkit mode is enabled
• [skills] — enabled/disabled lists when processkit mode is enabled
• [ai] — harnesses, agents, and team MCP servers
• [customization] — theme, mode, prompt, layout
• [audio] — audio bridging

4 - Cheatsheet

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”

## tmux (Terminal Multiplexer)

Leader key: ++ctrl+b++ — press and release, then press the action key.

### Pane Navigation

| Key | Action |
|-----|--------|
| `Ctrl+g` `h` / `Left` | Focus pane left |
| `Ctrl+g` `j` / `Down` | Focus pane down |
| `Ctrl+g` `k` / `Up` | Focus pane up |
| `Ctrl+g` `l` / `Right` | Focus pane right |

### Pane Management

| Key | Action |
|-----|--------|
| `Ctrl+g` `n` | New pane (best direction) |
| `Ctrl+g` `d` | Split down |
| `Ctrl+g` `r` | Split right |
| `Ctrl+g` `x` | Close current pane |
| `Ctrl+g` `f` | Toggle fullscreen |
| `Ctrl+g` `e` | Toggle embed / floating |
| `Ctrl+g` `z` | Toggle pane frames |
| `Ctrl+g` `=` | Increase pane size |
| `Ctrl+g` `-` | Decrease pane size |

### Window Management

| Key | Action |
|-----|--------|
| `Ctrl+g` `t` | New window |
| `Ctrl+g` `w` | Close window |
| `Ctrl+g` `[` | Previous window |
| `Ctrl+g` `]` | Next window |
| `Ctrl+g` `1`..`5` | Jump to window by number |
| `Ctrl+g` `i` | Move window left |
| `Ctrl+g` `o` | Move window right |

### Scroll & Search

| Key | Action |
|-----|--------|
| `Ctrl+g` `u` | Enter scroll mode |
| `Ctrl+g` `/` | Search scrollback |

**In scroll mode:**

| Key | Action |
|-----|--------|
| `j` / `k` | Scroll down / up |
| `d` / `u` | Half-page down / up |
| `f` / `b` | Full page down / up |
| `g` / `G` | Top / bottom |
| `/` | Search |
| `q` or `Esc` | Exit scroll mode |

**In search mode:**

| Key | Action |
|-----|--------|
| `n` / `N` | Next / previous match |
| `c` | Toggle case sensitivity |
| `w` | Toggle wrap |
| `o` | Toggle whole word |

### Session

| Key | Action |
|-----|--------|
| `Ctrl+g` `s` | Session chooser |
| `Ctrl+g` `m` | Session manager |

### Quit

| Key | Action |
|-----|--------|
| `Ctrl+g` `q` | Quit tmux |
| `Ctrl+q` | Quit tmux (global) |

!!! info "Default layout windows"
    The generated `dev` layout opens with pre-configured tmux windows:
    **work** (Yazi, 1st harness, shell), optional **lazygit**,
    **ai** for further harnesses, and **shell**. Window numbers shift when
    optional windows are omitted.

=== “Yazi”

## Yazi (File Manager)

Yazi uses Vim-style navigation. The aibox config adds a few custom bindings on top of the defaults.

### Navigation

| Key | Action |
|-----|--------|
| `h` / `Left` | Go to parent directory |
| `j` / `Down` | Move cursor down |
| `k` / `Up` | Move cursor up |
| `l` / `Right` / `Enter` | Open file or enter directory |
| `g` `g` | Go to first item |
| `G` | Go to last item |
| `~` | Go to home directory |

### Opening Files (aibox custom)

| Key | Action |
|-----|--------|
| `Enter` | Open file in-place (suspends Yazi, `:q` returns) |
| `e` | Open in adjacent Vim pane (stays in Yazi) |
| `O` | Interactive opener selection |

### File Operations

| Key | Action |
|-----|--------|
| `a` | Create new file or directory (append `/` for directory) |
| `r` | Rename file |
| `d` | Trash selected files |
| `D` | Permanently delete selected files |
| `y` | Yank (copy) selected files |
| `x` | Yank (cut) selected files |
| `p` | Paste yanked files |
| `Space` | Toggle selection on current file |
| `v` | Visual mode (select range) |
| `V` | Invert selection |

### Search & Filter

| Key | Action |
|-----|--------|
| `/` | Search files in current directory |
| `f` | Filter files (fuzzy match) |
| `.` | Toggle hidden files |

### Preview & Tabs

| Key | Action |
|-----|--------|
| `Tab` | Switch preview pane |
| `t` | Create new tab |
| `1`..`9` | Switch to tab by number |
| `[` / `]` | Previous / next tab |

### Misc

| Key | Action |
|-----|--------|
| `z` | Jump to directory (zoxide) |
| `:` | Open command shell |
| `~` / `F1` | View all keybindings |
| `q` | Quit Yazi |

=== “Vim”

## Vim (Editor)

Leader key: `Space`

### Leader Commands

| Key | Action |
|-----|--------|
| `Space` `w` | Save file |
| `Space` `q` | Quit |
| `Space` `x` | Save and quit |
| `Space` `n` | Next buffer |
| `Space` `p` | Previous buffer |
| `Space` `l` | List buffers |
| `Space` `e` | Open netrw file explorer |

### Split Navigation

| Key | Action |
|-----|--------|
| `Ctrl+h` | Move to left split |
| `Ctrl+j` | Move to split below |
| `Ctrl+k` | Move to split above |
| `Ctrl+l` | Move to right split |

### Essential Motions

| Key | Action |
|-----|--------|
| `h` `j` `k` `l` | Left, down, up, right |
| `w` / `b` | Next / previous word |
| `0` / `$` | Start / end of line |
| `gg` / `G` | Top / bottom of file |
| `Ctrl+d` / `Ctrl+u` | Half-page down / up |
| `%` | Jump to matching bracket |
| `f{char}` | Jump to next {char} on line |

### Editing

| Key | Action |
|-----|--------|
| `i` / `a` | Insert before / after cursor |
| `I` / `A` | Insert at start / end of line |
| `o` / `O` | New line below / above |
| `dd` | Delete line |
| `yy` | Yank (copy) line |
| `p` | Paste after cursor |
| `u` / `Ctrl+r` | Undo / redo |
| `.` | Repeat last change |
| `ciw` | Change inner word |
| `>>` / `<<` | Indent / dedent line |

### Search

| Key | Action |
|-----|--------|
| `/pattern` | Search forward |
| `?pattern` | Search backward |
| `n` / `N` | Next / previous match |
| `Esc` `Esc` | Clear search highlight |
| `*` | Search word under cursor |

### Commands

| Key | Action |
|-----|--------|
| `:w` | Save |
| `:q` / `:q!` | Quit / force quit |
| `:wq` or `:x` | Save and quit |
| `:e <file>` | Open file |
| `:%s/old/new/g` | Find and replace in file |

!!! note "Dev-box Vim settings"
    - Relative line numbers are enabled for fast `&#123;N&#125;j`/`&#123;N&#125;k` jumps
    - Tabs expand to 4 spaces (2 for YAML, JSON, HTML, CSS, JS, TS)
    - Trailing whitespace is stripped on save
    - Persistent undo is enabled across sessions

=== “lazygit”

## lazygit (Git TUI)

lazygit is panel-based. Press `?` at any time to see context-sensitive keybindings.

### Panel Navigation

| Key | Action |
|-----|--------|
| `1` | Status panel |
| `2` | Files panel |
| `3` | Branches panel |
| `4` | Commits panel |
| `5` | Stash panel |
| `h` / `l` | Switch panels left / right |
| `j` / `k` | Move up / down within panel |
| `[` / `]` | Previous / next tab within panel |

### Files Panel

| Key | Action |
|-----|--------|
| `Space` | Stage / unstage file |
| `a` | Stage / unstage all files |
| `c` | Commit staged changes |
| `A` | Amend last commit |
| `d` | Discard changes to file |
| `e` | Edit file in editor |
| `o` | Open file in default application |
| `i` | Add to .gitignore |
| `S` | Stash all changes |
| `Enter` | Focus on file to see diff hunks |

### Branches Panel

| Key | Action |
|-----|--------|
| `Space` | Checkout branch |
| `n` | New branch |
| `d` | Delete branch |
| `M` | Merge into current branch |
| `r` | Rebase current branch onto selected |
| `R` | Rename branch |
| `f` | Fetch branch |
| `P` | Push |
| `p` | Pull |

### Commits Panel

| Key | Action |
|-----|--------|
| `s` | Squash commit into one below |
| `r` | Reword commit message |
| `R` | Reword with editor |
| `d` | Delete commit |
| `e` | Edit commit (interactive rebase) |
| `c` | Copy commit (cherry-pick) |
| `v` | Paste (cherry-pick) commit |
| `F` | Create fixup commit |
| `S` | Squash all fixup commits |
| `g` | Reset to this commit |
| `t` | Tag commit |

### Stash Panel

| Key | Action |
|-----|--------|
| `Space` | Apply stash (keep in list) |
| `g` | Pop stash (apply + remove) |
| `d` | Drop stash entry |

### Global

| Key | Action |
|-----|--------|
| `?` | Show keybindings for current panel |
| `+` | Show command log |
| `@` | Show command log menu |
| `P` | Push |
| `p` | Pull |
| `z` / `Ctrl+z` | Undo last action |
| `q` | Quit lazygit |

!!! tip "Accessing lazygit"
    lazygit is available only when the optional `git-ui` addon selects
    `lazygit`. In generated layouts, aibox adds it as a fullscreen **git**
    tab after any AI-agent tabs.

5 - Compatibility

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.

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:

Warning: processkit v0.24.0 is below the minimum recommended version v0.25.0 for aibox v0.23.0 ...

This is a warning, not an error — older processkit versions can still install successfully when their layout is still supported. The warning is a nudge to upgrade, not a blocker. Harness-only projects do not install processkit content, so this matrix only matters when [context].mode = "processkit".

Upgrading processkit

To upgrade processkit in an existing project:

1. Edit aibox.toml:

   [processkit]
   version = "v0.25.5"
   

2. Run aibox apply on the host — the 3-way diff will show changed content and generate processkit content migration documents in context/migrations/pending/.

3. Review and apply the pending migrations.

6 -

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:

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.

This review was consolidated for aibox issue #80. It is kept current through the local release gate and the public maintenance guide.

Data handling review

aibox does not provide a hosted service and does not send product telemetry. The CLI operates on the local project, generates container configuration, and contacts external services only for requested dependency, image, processkit, GitHub, documentation, or release operations.

• aibox.toml, generated .devcontainer/ files, and processkit context are project data and are normally committed.
• .aibox-local.toml, .aibox-home/, .aibox/, authentication state, SSH material, local caches, diagnostics, and release evidence are local state and must remain ignored unless a specific artifact has been reviewed for publication.
• Tokens enter containers through explicit local environment configuration. Prefer separate least-privilege tokens and select cross-account tokens per command instead of exposing a human account’s full authorization.
• Enabled AI harnesses and MCP servers execute with the container user’s access to the workspace and mounted credentials. Their providers may receive prompt, tool, and file content according to the provider’s own service terms.
• aibox doctor and pk-doctor inspect local state. Diagnostic reports must be reviewed and redacted before they are attached to public issues.

No generated local credential, cache, or diagnostic directory belongs in a release artifact. The release process builds from tracked source, verifies the exact commit, and publishes only the declared binaries, documentation output, and container images.

MCP Gateway Trust Scope

How processkit skills are registered

When [context].mode = "processkit" and aibox apply registers processkit skills (such as processkit-gateway, workitem-management, etc.), it calls into cli/src/mcp_registration.rs. For Codex, the generated project config sets:

[project]
trust_level = "trusted"

This means every installed skill’s mcp/server.py runs with project-user trust inside the aibox container — the same trust level as the project owner who launched the container. The MCP server process inherits the container filesystem and environment, including any mounted credentials.

When [context].mode = "harness-only", aibox does not install or register processkit skills, processkit hooks, processkit preauth rules, or the processkit MCP gateway. Team and personal MCP servers configured under [ai.mcp] / .aibox-local.toml [[mcp.servers]] are still generated for enabled harnesses and carry their own trust review burden.

Implications

• A skill’s mcp/server.py can read, write, and execute within the container with the same permissions as the project user.
• Skills can access mounted SSH keys (~/.ssh), API key env vars, and the full workspace at /workspace.
• Skills are registered at the Codex/Claude project scope — they are active for every session in the container.

Third-party skill review checklist

Before installing a skill from a third party (outside the processkit core), verify:

1. Source code is auditable: the skill’s mcp/server.py (and any imported modules) are readable and understandable.
2. No unexpected outbound network calls: the skill should not exfiltrate data to external endpoints.
3. No credential access beyond stated purpose: check for reads of ~/.ssh/, env vars (ANTHROPIC_API_KEY, etc.), or ~/.claude/~/.codex.
4. Tool list is minimal: the allowed_tools set registered by the skill should match only the capabilities the skill claims to need.
5. Dependency supply chain: if the skill uses uv or pip to install Python packages, review pyproject.toml / requirements.txt for unexpected dependencies.
6. Immutable or pinned source: prefer skills pinned to a specific git SHA or release tag over floating main/latest references.

Opting out of a skill

To remove a skill and deregister its MCP server:

1. Remove the skill from context/skills/ or update [processkit] config.
2. Run aibox apply — this rewrites the harness MCP configuration files and removes the skill’s allowed_tools entries.
3. Recreate the container (docker compose up -d --force-recreate) so the new MCP configuration takes effect.

seccomp=unconfined Consent Gate

The Codex CLI uses bubblewrap for Linux sandboxing. Some container runtime seccomp profiles block unprivileged user namespace creation before bubblewrap can set up its own sandbox. To work around this, aibox apply can emit seccomp=unconfined in the generated docker-compose.yml.

Explicit consent is required. Without the acknowledgement flag, aibox apply will error with a remediation pointer. To opt in, add to aibox.toml:

[security]
acknowledge_seccomp_unconfined = true

This setting:

• Allows aibox apply to emit seccomp=unconfined in docker-compose.yml.
• Suppresses the aibox doctor warning about unapproved seccomp relaxation.
• Documents in source control that the project owner has accepted the trade-off: reduced seccomp filtering in exchange for Codex bubblewrap user-namespace sandboxing, avoiding the broader privileged=true or CAP_SYS_ADMIN escalations.

seccomp=unconfined does not grant root or additional Linux capabilities — it only lifts the seccomp syscall filter, allowing bubblewrap to create user namespaces.