Skip to main content

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:

OptionDefaultDescription
--basedebianBase image
<NAME>Current directory nameContainer and hostname
--profilehuman-devUsage profile: human-dev or warning-mode headless-runner
--harnessclaudeAI harnesses (can be repeated): claude, codex, gemini, aider, etc.
--addon—Addon names (can be repeated): python, rust, node, go, latex, etc.
--themegruvboxTheme family
--context-modeprocesskitContext layer: processkit or harness-only
--processkit-versionlatest available tagprocesskit content release to pin

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.

.aibox-local.toml — secrets and per-developer overrides

.aibox-local.toml is added to .gitignore by aibox init. Use it for API keys and host-specific bind mounts that should not be committed:

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

Shared settings stay in aibox.toml; personal secrets go here. Use narrowly scoped PATs by default. For the alternative persistent gh auth login flow and multi-token commands, see GitHub authentication.

processkit version

By default, the interactive aibox init picker offers latest first, then the 10 newest concrete processkit tags. Choosing latest writes version = "latest" to aibox.toml so aibox apply tracks the newest compatible content. Use --processkit-version to pin a specific tag non-interactively:

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

This picker is skipped when --context-mode harness-only is selected.

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

# 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​