v1.3.3 · Lima ≥ 2.0

devbox

A practical VM boundary for AI-assisted development.

Claude, Codex, OpenCode, Pi, Stado, Herdr, and gh are preloaded. Open exactly the host-backed capabilities a task needs—then throw the box away while keeping only its resumable project sessions.

Read the docs

host — zsh

$ cd ~/code/some-project
$ devbox # clone → mount CWD → shell in → delete on exit
→ cloning devbox-golden-ubuntu-24-04 …
→ mounting ~/code/some-project (rw)
you@devbox:~/code/some-project$ ▊

WHY IT EXISTS

Agents should not run on your host.

Devbox makes isolation of AI agents and tools from your credentials and private files easy enough to use every time.

Agents read untrusted repositories, issues, webpages, and tool output. Prompt injection turns that input into instructions; even without an attacker, an agent can decide it needs to read, install, or run more than expected.

A VM boundary makes the answer structural: the agent sees the mounted project, its narrow per-project session store, and only the additional capabilities you explicitly select.

THE TRADE-OFF

A sealed box is useless. An open one is risky.

Devbox starts with no host access. Every feature below adds one named capability—so you can make the trade-off consciously, per task.

Fresh by default

No host credentials, desktop session, or SSH agent is exposed. Only this project's owner-only AI session store survives clone disposal; use -e to make that ephemeral too.

(default)

Non-secret agent context

Selected rules, prompts, settings, and custom agents cross in. Credentials, unrelated host histories, caches, and key directories do not.

--with-agent-config

Authenticated provider requests

The host proxy makes permitted AI and GitHub requests without putting the underlying host tokens in the VM—and records the requested action.

--proxy

Proxy-or-fail web egress

Ordinary web tools use an audited CONNECT proxy or fail on direct web ports. HTTPS audit data remains metadata-only.

--traffic-audit

SSH operations

The guest can ask loaded host identities to authenticate or sign commits, but private keys do not enter the VM.

--ssh-agent

Extra project material

Mount an additional host path read-only by default, or make a one-time copy into the guest.

--mount / --copy

Guest windows on your desktop

Waypipe gives a guest application access to your host compositor. Useful for trusted code; deliberately not part of -a.

--gui

Credentials in the VM

API keys or OAuth files can be copied in when required. This intentionally weakens the host-only credential boundary.

--api-keys / --with-creds

Capabilities combine. A malicious process can use every capability you enable; use the smallest set that lets the task work. Read the threat model

HOST-LOCAL AUDIT LOG

See the action, not just the connection.

Every request that reaches the authenticated AI or GitHub proxy produces a private host-side record. AI prompts and queries, GitHub REST and GraphQL payloads, the requested action, its final status, and its duration are retained for review.

GitHub writes are classified as create, modify, delete, or GraphQL mutation. Known credential fields are redacted; request headers and response bodies are never recorded.

Audit data model and retention guidance

DETAILED REQUEST AUDIT

AI + GitHub through `--proxy`

Capture the real submitted prompt or API payload, then see whether a remote mutation succeeded.

$ devbox proxy audit show
$ devbox proxy audit export audit.html

JSONL and the optional HTML report are owner-only files on the host.

OPAQUE HTTPS METADATA

General web traffic through `--traffic-audit`

The CONNECT tunnel logs destination, timing, and byte counts. HTTPS paths, prompts, and bodies remain end-to-end encrypted.

Proxy-unaware tools fail on direct TCP/UDP web ports rather than silently bypassing this audit.

Disposable

Each box is deleted on exit by default. Nothing accumulates.

Isolated

Real development work happens in a VM boundary, not in your host session.

Fast

A one-time golden carries the toolchain; each run is a cheap clone.

Deterministic

A folder always maps to the same box name, so kept boxes are easy to find.

Credential-safe

Host tokens can remain on the host behind a request capability.

Multi-distro

Base provisioning adapts to apt, dnf, or pacman.

Sparse

Disk is a ceiling, not an allocation—only written data consumes space.

Preloaded

The CLIs, gh, and Homebrew are baked into the golden image.

WAYLAND GUI FORWARDING

Guest GUI apps, on your host.

devbox gui and devbox --gui use Waypipe over the instance SSH transport. The raw host Wayland socket and GPU device nodes are never mounted into the guest.

This still widens the trust boundary: a forwarded app becomes a client of your host compositor. Use it only with code and GUI applications you trust.

GUI forwarding security

$ devbox --gui
→ launch GUI apps from the shell

$ devbox gui -- weston-terminal
→ one app; returns when it exits

$ devbox --gui -a -- code .

HOW IT WORKS

Build once, clone per folder.

devbox build provisions a persistent golden image. Every project gets a deterministic clone from it—without re-installing the toolchain.

01
Build
Provision Homebrew, AI CLIs, gh, and build essentials into a golden image.
02
Clone
Attach to a kept box or quickly clone the golden image for the project directory.
03
Mount
Mount the project plus its narrow resumable-session store, apply approved configuration, and enter.
04
Destroy
Exit to delete the clone while retaining project sessions, unless you explicitly used --keep.

$ devbox [DIR] [FLAGS]                     # enter a disposable development VM
$ devbox gui [DIR] [FLAGS] [-- APP ...]  # open a GUI-ready shell or app
$ devbox build [--image N] [--force]      # create or refresh a golden image
$ devbox sessions path|clear [DIR]       # inspect or remove resumable state
$ devbox destroy NAME | --all | --goldens

KEY FLAGS

The ones you’ll reach for.

Flags make host-backed capabilities explicit. They work on a new box and, where applicable, refresh or remove state in an existing kept box.

--keep, -k

Leave the box running when the shell exits.

--ephemeral-sessions, -e

Keep this run's AI transcripts on the disposable guest disk.

--proxy[=URL], -p

Use host-side AI and GitHub authentication without exposing real tokens in the VM.

--traffic-audit, -T

Route normal web tooling through the audited proxy or fail on direct web ports.

--ssh-agent, -s

Forward the host SSH agent for authentication and SSH-signed commits.

--gui, -G

Open a GUI-ready shell or a guest Wayland application through Waypipe.

-a

The common trusted-code preset: agent config, host credential proxy, and SSH agent—never GUI.

--no-auth, -n

Remove Devbox-managed proxy, API-key, and copied-credential profiles from a kept box.

--image NAME, -i

Select a Lima template, configuration file, or cloud image for the golden.

All flags and examples

PROJECT MANIFEST

`.devbox.toml`

Keep project-local packages, resource settings, mounts, and startup commands with the project. Devbox summarizes host-affecting requests and asks before applying them.

See the annotated example

image = "ubuntu-24.04"

[resources]
cpus = 8
memory = "12GiB"

packages = ["just", "watchexec"]
start = "just dev"

READY WHEN YOU ARE

One command away.

Clone the golden, mount your project, and give the task only the capabilities it needs.

View on GitHub