Getting Started

• 1: Installation
• 2: New Project
• 3: Existing Project

1 - Installation

Installation

Prerequisites

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

Podman (recommended)

# macOS
brew install podman
podman machine init
podman machine start

# Fedora / RHEL
sudo dnf install podman podman-compose

# Ubuntu / Debian
sudo apt install podman podman-compose

Docker

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

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

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

Install script (recommended)

Install the latest stable release:

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

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

Install the v1 alpha

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

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

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

Roll back from the alpha

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

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

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

Other options

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

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

Manual download

Download the binary for your platform from the releases page:

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

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

Available binaries:

Build from source

Requires a Rust toolchain:

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

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

Verify

aibox --version
# aibox X.Y.Z

Shell completion scripts

# Add to your shell profile for persistent completion scripts:

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

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

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

Next steps

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

2 - New Project

New Project

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

Initialize the Project

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

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

The init command accepts these options:

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

What Gets Created

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

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

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

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

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

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

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

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

The Generated aibox.toml

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

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

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

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

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

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

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

[processkit.context]
schema_version = "1.0.0"

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

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

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

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

After editing, regenerate devcontainer files:

aibox apply

Build and Start

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

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

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

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

VS Code Integration

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

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

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

Next Steps

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

3 - Existing Project

Existing Project

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

Create aibox.toml

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

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

If you prefer to write it by hand:

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

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

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

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

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

[processkit.context]
schema_version = "1.0.0"

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

[audio]
enabled = false

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

[context]
mode = "harness-only"

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

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

Apply Devcontainer Files

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

aibox apply

This creates:

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

Replacing Hand-Written Devcontainer Files

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

Option A: Let aibox take over

1. Back up your existing files:

   cp -r .devcontainer .devcontainer.bak
   

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

Option B: Keep hand-written files

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

Running Diagnostics

Use doctor to validate your project structure:

aibox doctor

This checks:

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

Example output:

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

Migrating from .root/ to .aibox-home/

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

mv .root .aibox-home

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

Migrating Context Structure

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

Common gaps to watch for

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

Build and Start

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

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

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

Next Steps

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