Getting Started on aibox

Installation

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

Installation

Prerequisites

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

Podman (recommended)

# macOS
brew install podman
podman machine init
podman machine start

# Fedora / RHEL
sudo dnf install podman podman-compose

# Ubuntu / Debian
sudo apt install podman podman-compose

Docker

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

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

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

New Project

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

New Project

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

Initialize the Project

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

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

The init command accepts these options:

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

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

Existing Project

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

Existing Project

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

Create aibox.toml

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

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

init will not overwrite

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

If you prefer to write it by hand:

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

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

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

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

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

[processkit.context]
schema_version = "1.0.0"

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

[audio]
enabled = false

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