Container on aibox

Base Image

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

Base Image

The base image is the foundation for all aibox container flavors. It provides a complete, opinionated development environment built on Debian Trixie Slim.

Installed Tools

Tool	Version / Source	Purpose
tmux	Debian package	Terminal multiplexer
Yazi	25.4.8 (prebuilt binary from GitHub releases)	Terminal file manager
Vim	Debian package (`vim` + `vim-runtime`)	Editor
Git	Debian package	Version control
Claude CLI	Official install script	AI assistant
ripgrep (`rg`)	Debian package	Fast recursive search (grep replacement)
fd	Debian package	Fast file finder (find replacement)
bat	Debian package	Syntax-highlighting cat replacement
eza	Debian package	Modern ls replacement with git integration
zoxide	Debian package	Smarter cd that learns your habits
fzf	Debian package	Fuzzy finder for files, history, and more
delta	Debian package	Syntax-highlighting diff viewer (used by git)
starship	Prebuilt binary	Minimal, fast shell prompt with context
curl	Debian package	HTTP client
jq	Debian package	JSON processor
less	Debian package	Pager
unzip	Debian package	Archive extraction
iproute2	Debian package	Network route/interface inspection for status segments
iputils-ping	Debian package	ICMP latency checks for status segments
bash-completion	Debian package	Shell completions
ca-certificates	Debian package	TLS root certificates
locales	Debian package	Locale support (en_US.UTF-8)
tzdata	Debian package	Timezone data

GitHub CLI (gh) and lazygit are provided by the optional git-ui addon, not by the base image. Add [addons.git-ui.tools] to aibox.toml when a project needs those tools.

Container Configuration

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

Container Configuration

The [container] section in aibox.toml controls per-project container settings.

Container Identity

[container]
name = "my-project" # Container name (used by compose)
hostname = "my-project" # Container hostname
user = "aibox" # Container user (default: aibox)

The user field determines the non-root user inside the container. The default aibox user (UID 1000) is recommended. Set user = "root" only if needed for specific tools.

aibox apply generates a Compose file with an explicit top-level project name, an explicit service image, and container_name = [container].name. Docker Desktop, OrbStack, and Compose UIs therefore group aibox projects by their project/container names instead of under a generic devcontainer identity.

Audio Support

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

Audio Support

aibox can enable audio support for voice-capable tools. Audio is bridged from the container to the host via PulseAudio over TCP, and the required container packages live in the optional audio-voice addon.

Why Audio Matters

Claude Code supports voice interaction. For this to work inside a container, audio output (and optionally input) must be forwarded to the host’s sound system. aibox handles this by installing PulseAudio client utilities in the container and connecting them to a PulseAudio server running on the host.

File Preview

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

File Preview

aibox containers ship with Yazi preview configuration and can install TUI-native preview tools for raster images, vector graphics, PDF, archives, and video through optional addons. Several formats also support watch-mode preview, where the rendered output updates automatically whenever the source file changes.

Overview

There are two independent preview mechanisms:

Mechanism	When to use
Yazi file preview	Browsing files — preview appears automatically in the right panel as you navigate
Standalone TUI viewers	Viewing a specific file in a pane, or piping output from a build tool

Watch-mode (live-updating preview) is available via the standalone tools — see Watch-Mode Preview.

Runtime Operations

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

Runtime Operations

The generated devcontainer is standard Compose output, but the normal workflow should go through aibox so generated files, runtime home state, and diagnostics stay aligned.

Start and Attach

aibox up
aibox up --layout focus
aibox up --apply

aibox up creates or starts the container and attaches through tmux. Use --layout for a one-session layout override. Use --apply when you want aibox to reconcile configuration before starting.

Stop or Remove

aibox down
aibox delete runtime

down stops the Compose project. delete runtime removes the container while preserving project files and .aibox-home/.