Note
Project status: actively maintained. The latest minor release line is supported; security and correctness fixes are released on the newest version. See SECURITY.md for reporting and support details.
Branches: main is the v1 line, which is in development and not yet
released. The current release is v0.35.4, maintained on
lts/v0; read that
branch's README for the released product. The install command below
installs the latest release (v0).
aibox is a Rust CLI for projects that want a dependable terminal-first AI
development environment without hand-maintaining devcontainer glue. It turns a
declarative aibox.toml into standard .devcontainer/ files, a project image,
runtime UI configuration, selected AI harnesses, and pinned processkit context
under context/.
The design goal is simple: a fresh clone plus aibox apply should reproduce the
same workspace, with the same tools, the same agent entry points, and the same
project context.
AI-assisted work fails quickly when the environment is half-local, half-memory, and only reproducible on one machine. aibox keeps the moving parts explicit:
- One project contract:
aibox.tomldeclares the base image, container identity, addons, AI harnesses, theme, layout, and processkit source/version. - Standard container output: generated
.devcontainer/Dockerfile,docker-compose.yml,docker-compose.override.yml, anddevcontainer.jsonremain understandable to Docker, Podman, OrbStack, and VS Code. - Composable tools: addons install language runtimes, AI CLIs, preview tools, infrastructure CLIs, and documentation frameworks only when selected.
- Provider-neutral context:
AGENTS.mdis the canonical agent entry point; provider files such asCLAUDE.mdare thin pointers. - Pinned process layer: processkit supplies skills, schemas, state machines, processes, and package definitions. aibox installs and updates that content.
- Runtime visibility:
aibox get runtime --resourcesandaibox doctorsurface memory pressure, OOM signals, and process count risks before they turn into unexplained agent exits.
Install a supported container runtime first:
- Podman, including a Compose provider
- Docker or Docker Desktop
- OrbStack with Docker-compatible Compose
Install the stable CLI:
curl -fsSL https://raw.githubusercontent.com/projectious-work/aibox/main/scripts/install.sh | bash
aibox --versionThis branch documents the v1 preview. After v1.0.0-alpha.1 is published,
install that exact prerelease instead of relying on the stable channel:
curl -fsSL https://raw.githubusercontent.com/projectious-work/aibox/main/scripts/install.sh |
VERSION=1.0.0-alpha.1 bash
aibox --versionPrerelease installation and rollback are covered in the v1 installation guide.
mkdir my-project && cd my-project
git init
aibox init my-project --harness claude --addon python
aibox apply
aibox upThis creates:
aibox.tomlas the source of truth- generated
.devcontainer/files .aibox-home/for persistent runtime config, ignored by gitcontext/with processkit-managed project context- root-level
AGENTS.mdplus thin provider pointers - a tmux workspace mounted at
/workspace
For an existing project, start with the existing-project guide.
aibox apply # reconcile config, processkit content, files, and image
aibox apply --no-cache # rebuild image without cached layers
aibox up # start or attach to the workspace
aibox up --layout focus # override layout for one session
aibox get runtime --resources # inspect memory/process pressure
aibox doctor # validate project and runtime postureOlder command names such as aibox sync, aibox start, and aibox status
were replaced by the current verb/resource grammar. See the
CLI reference
for the mapping.
| Layer | Owned by | What it contains |
|---|---|---|
| Project contract | aibox | aibox.toml, aibox.lock, .aibox-version |
| Container output | aibox | .devcontainer/, generated Compose, devcontainer JSON |
| Runtime home | aibox | .aibox-home/ tmux, shell, theme, and tool config |
| Addons | aibox | YAML definitions for installable tools and runtimes |
| Process content | processkit | skills, processes, schemas, state machines, AGENTS.md template |
| Project context | shared | editable context/ content plus immutable upstream snapshots |
aibox intentionally does not own process semantics. If a behavior is about how agents plan, record decisions, or manage work items, it belongs in processkit. If it is about generating containers, selecting addons, wiring harness config, or launching the workspace, it belongs in aibox.
Full documentation for this v1 preview line lives at projectious-work.github.io/aibox/v1.x/ (the stable v0.x docs are at the site root).
| Section | Contents |
|---|---|
| Getting Started | Installation, new project, existing project |
| Container | Base image, configuration, runtime operations, audio, file preview |
| Addons | Overview, language runtimes, tool bundles, documentation frameworks |
| Providers | Claude, OpenAI, Gemini, Copilot, Continue, Aider, Mistral |
| Context System | Overview, skill selection, migration |
| Customization | Themes, layouts, prompts |
| Reference | Configuration, CLI commands, compatibility, cheatsheet, v1 deployment boundaries |
| Contributing | Maintenance, e2e tests, version-line porting |
This repository is developed inside its own devcontainer.
cd cli && cargo build
cd cli && cargo test
cd cli && cargo clippy --all-targets -- -D warnings
cd cli && cargo fmt -- --checkFor full container lifecycle tests:
cd cli && cargo test --features e2eRelease quality expectations are strict:
- zero Clippy warnings
- all tests passing
cargo auditclean before tagging- tracked release notes, compatibility metadata, and a successful Hugo production build before publication
- releases created through
./scripts/maintain.sh release <version>
| Path | Purpose |
|---|---|
cli/ |
Rust CLI source for the aibox binary |
addons/ |
YAML addon definitions for runtimes, tools, docs frameworks, and AI CLIs |
images/ |
Base image recipes published for downstream projects |
docs-site/ |
Hugo documentation site using the pinned projectious.work brand theme |
context/ |
This repository's processkit-managed project context |
scripts/ |
Release, install, and maintenance tooling |
.devcontainer/ |
This repository's own development container |
Long-lived main, v0.x, and v1.x branches are PR-only. Before contributing,
read AGENTS.md, CONTRIBUTING.md, and the docs
under docs-site/content/docs/contributing/.
Do not hardcode processkit vocabulary in production Rust code. Add constants to
cli/src/processkit_vocab.rs instead.
All build, test, documentation, and release gates run locally. This repository does not use GitHub Actions; see the v1 maintenance guide for the exact commands and release phases.
MIT. See LICENSE.
Unless otherwise noted, the copyright holder grants the MIT License for all versions of this repository, including historical commits and tags.
Brand and design system © projectious.work. The aibox mark is derived from that system.
