Devboxes turns Kubernetes capacity into ready-to-use development machines. Create one from your terminal, connect over SSH, and return to the same tmux session after a disconnect. Compute is disposable; the home volume persists until you explicitly purge it.
For the recommended production-shaped setup and fastest daily workflow, follow the golden path. The complete documentation map is in docs/index.md.
$ devbox create atlas --preset medium --repo owner/project --ssh
→ preparing atlas…
atlas ready
storage: 30Gi
ssh: ssh -t dev@192.0.2.40Each workspace includes Rust, Node.js, Python, uv, GitHub CLI, Codex CLI, Claude Code, Git, zsh, tmux, compilers, and common terminal tools. GitHub and AI-provider credentials are optional runtime secrets; none are baked into the image.
- A Rust
devboxCLI for create, list, inspect, SSH, start, stop, delete, and opt-in Insights workflows. - A FastAPI controller with an authenticated API, accessible browser workbench, Insights dashboard, documentation, metrics, health checks, and TTL cleanup.
- A versioned Helm chart with values schema validation and namespace-scoped RBAC.
- Multi-architecture controller and workspace images for
linux/amd64andlinux/arm64. - Persistent SSH host identity, shell state, tool installs, account state, and source under
/home/dev. - GitHub Releases with macOS and Linux CLI binaries and SHA-256 checksums.
Devboxes is currently a single-operator system: one shared token controls every box in one installation. It is suitable for a trusted personal cluster or trusted operator group, not mutually untrusted tenants.
- Kubernetes 1.29 or newer.
- Helm 3.14+ or Helm 4.
- A default
ReadWriteOnceStorageClass, or an explicitworkspace.storageClass. - One of these ways to reach SSH services:
LoadBalancersupport from your cloud, MetalLB, kube-vip, or another implementation; or- reachable Kubernetes nodes and
workspace.sshService.type=NodePort.
- An SSH public key.
- An ingress controller and TLS certificate only if you expose the dashboard through ingress. Port-forwarding works without either.
The workspace container intentionally supports passwordless sudo for the trusted development user. Its pod drops all capabilities and adds back a small set needed by sudo and OpenSSH PTY auditing, but it is not compatible with the Kubernetes restricted Pod Security profile. Use the baseline profile or an equivalent policy in the Devboxes namespace.
The quickest supported path is the repository installer. It creates or updates the required Secrets, installs the local Helm chart, and waits for the controller.
git clone https://github.com/vicotrbb/devboxes.git
cd devboxes
./scripts/install.shBy default, the dashboard is available only through a local port-forward and each workspace requests a LoadBalancer SSH service.
kubectl -n devboxes port-forward service/devboxes 8000:8000
open http://127.0.0.1:8000 # macOS; use your browser elsewhereRetrieve the generated access token without relying on platform-specific base64 flags:
kubectl -n devboxes get secret devboxes-auth \
-o go-template='{{index .data "access-token" | base64decode}}{{"\n"}}'Run the post-install check:
./scripts/verify-install.shIf you manage Secrets separately, install the published chart directly:
kubectl create namespace devboxes
kubectl -n devboxes create secret generic devboxes-auth \
--from-literal=access-token="$(openssl rand -hex 32)"
kubectl -n devboxes create secret generic devboxes-workspace \
--from-file=SSH_AUTHORIZED_KEYS="$HOME/.ssh/id_ed25519.pub"
helm install devboxes oci://ghcr.io/vicotrbb/charts/devboxes \
--version 0.3.0 \
--namespace devboxesThe chart never embeds credential values. It references existing Kubernetes Secrets so it also works with External Secrets Operator, Sealed Secrets, SOPS, Infisical, Vault, and other secret-management workflows.
This example uses a generic nginx ingress class and an existing TLS Secret:
./scripts/install.sh \
--set ingress.enabled=true \
--set ingress.className=nginx \
--set ingress.host=devboxes.example.com \
--set ingress.tls.enabled=true \
--set ingress.tls.secretName=devboxes-tls \
--set controller.externalUrl=https://devboxes.example.com \
--set controller.cookieSecure=trueUse your cluster's ingress class. The controller intentionally does not offer an insecure TLS bypass in the CLI.
LoadBalancer is the default. Provider-specific annotations and source ranges are supported:
workspace:
sshService:
type: LoadBalancer
annotations:
service.beta.kubernetes.io/example-private-load-balancer: "true"
externalTrafficPolicy: Local
loadBalancerSourceRanges:
- 192.0.2.0/24For clusters without a load balancer, let Kubernetes allocate a distinct NodePort for each box and provide a node address reachable from CLI clients:
./scripts/install.sh \
--set workspace.sshService.type=NodePort \
--set workspace.sshService.host=dev-node.example.comSee configuration for every supported value and platform examples.
Insights is disabled by default. Enable it to collect privacy-bounded local AI metrics and aggregate Git activity into a persistent controller database:
insights:
enabled: true
storage:
storageClass: fast-rwo
size: 2Gi
retainOnDelete: trueNew and normally restarted workspaces receive a loopback-only collector sidecar. The collector uses a durable outbox on the workspace PVC and a scoped write-only credential. It never collects prompts, responses, commands, paths, file contents, Git authors, commit messages, or provider identities.
Open /insights or query the same data through the CLI:
devbox metrics --since 7d
devbox metrics status
devbox metrics activity --box atlasInsights is personal operational visibility, not billing, compliance, employee monitoring, or a productivity score. Read Insights before enabling it for metric semantics, trust boundaries, storage, backup, retention, and purge behavior.
Release binaries support macOS and Linux on Intel/AMD and ARM64:
curl -fsSLO https://raw.githubusercontent.com/vicotrbb/devboxes/main/scripts/install-devbox-cli.sh
less install-devbox-cli.sh
sh install-devbox-cli.shYou can also build from source:
cargo install --locked --git https://github.com/vicotrbb/devboxes devbox-cliAuthenticate and create a box:
devbox login --url https://devboxes.example.com
devbox create atlas --preset medium --ttl 24 --repo owner/project --sshLogin opens the system browser, asks the current Devboxes browser session to approve the CLI, exchanges a one-time PKCE authorization code, verifies the resulting scoped token, and stores it without displaying it. If the browser is not already signed in, the existing operator login page appears first. This removes token pasting from the terminal; it does not add SSO or unauthenticated LAN trust.
For a machine where the CLI cannot open a browser, print the URL and open it manually:
devbox login --url https://devboxes.example.com --no-openFor a port-forwarded controller, localhost HTTP is deliberately allowed:
devbox login --url http://127.0.0.1:8000The daily lifecycle is small and explicit:
devbox list
devbox status atlas
devbox ssh atlas
devbox stop atlas # ends processes; keeps /home/dev
devbox start atlas # renews the original TTL
devbox delete atlas # removes compute; keeps /home/dev
devbox delete atlas --purge # permanently deletes the home volumePass OpenSSH options after --, for example:
devbox ssh atlas -- -L 3000:127.0.0.1:3000The CLI stores its configuration at the platform config directory under devbox/config.toml with mode 0600 on Unix. DEVBOX_URL, DEVBOX_TOKEN, and DEVBOX_CONFIG support non-interactive and multi-profile workflows.
Existing automation can continue to use the master token through DEVBOX_TOKEN or an
explicit --token. Browser login receives an expiring CLI token instead of the master
credential.
Only SSH_AUTHORIZED_KEYS is required. Add optional values to the devboxes-workspace Secret to prepare GitHub, Git, Codex, or Claude Code. Public GitHub repositories clone without GH_TOKEN.
| Secret key | Purpose |
|---|---|
SSH_AUTHORIZED_KEYS |
Required OpenSSH authorized keys file |
GH_TOKEN |
Private GitHub clones and authenticated gh/Git operations |
GIT_USER_NAME, GIT_USER_EMAIL |
Git author identity |
CODEX_AUTH_JSON |
Seed Codex account state on a new home volume |
CODEX_ACCESS_TOKEN or OPENAI_API_KEY |
Codex non-interactive bootstrap alternatives |
CLAUDE_CREDENTIALS_JSON |
Seed Claude Code account state on a new home volume |
CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY |
Claude Code runtime authentication alternatives |
Provider sessions can expire, and account-file portability may change. API tokens are the most automation-friendly option. Review your providers' current credential and usage policies before sharing any account material. See credentials for safe setup patterns.
devbox CLI / browser
│ HTTPS + bearer/session auth
▼
Devboxes controller ─── Kubernetes API
│ │
│ ├─ Secret (scoped Insights ingest credential)
│ ├─ Deployment (disposable compute)
│ ├─ Service (LoadBalancer or NodePort SSH)
│ └─ PVC (persistent /home/dev)
├─ TTL cleanup and lifecycle state
└─ Insights SQLite PVC (optional central history)
The controller watches only its release namespace and receives namespace-scoped RBAC. Workspace pods do not receive Kubernetes service-account tokens. See architecture for resource ownership, persistence, readiness, and threat boundaries.
make bootstrap
make lint
make test
make helm
make imagesCI repeats these gates and performs a clean Kind-cluster Helm install with an authenticated API smoke test. Release tags publish four CLI targets, two multi-architecture images, checksums, provenance attestations for images, and the OCI Helm chart.
Read CONTRIBUTING.md before proposing a change. Security reports belong in a private GitHub security advisory, not a public issue.
- Golden path for a performance-oriented installation and daily workflow.
- CLI reference and API reference for client contracts.
- Insights for telemetry semantics, privacy, storage, backup, and purge.
- Configuration and credentials for installation details.
- Operations and troubleshooting for production ownership.
- Architecture and development for maintainers.
Devboxes is at v0.3: useful and installable, with an intentionally narrow trust model. Compatibility follows semantic versioning after v1.0; before then, minor releases may include documented configuration or API changes. PVC data is never automatically deleted, including at TTL expiry.