# devboxes

Manages remote Namespace virtual machines on Linux and macOS from your coding agent. Ideal for isolated builds, CI-like test runs, ephemeral Docker hosts, and heavy workloads.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 2000 installs · ★ 2
- Author: namespacelabs
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/namespacelabs/agent-skills/tree/HEAD/skills/devboxes/SKILL.md
- Updated: 2026-09-22
- HTML: https://affpapa.org/en/nevibecode/skills/devboxes

## What it does

This skill instructs agents how to provision remote Namespace machines on `linux/amd64` (with Docker available) or `macos/arm64`. Using the `devbox` or `boxctl` CLI, the agent handles instance lifecycles, runs remote tasks via `devbox exec`, and sets up disposable environments with `--ephemeral`. Available configurations range from 4 vCPU with 8 GB RAM up to 32 vCPU on Linux.

Before executing commands, the agent checks for `NAMESPACE_DEVBOX_WORKSPACE_DIR` to determine if it is already operating inside an existing devbox. When running from outside, the `devbox` CLI must be installed and authenticated via `devbox login`. Keep in mind that the GitHub organization slug in `--checkout` is strictly case-sensitive, so mismatched casing will fail the clone step.

## Requirements
- Works with: Docker

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add namespacelabs/agent-skills --skill devboxes -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/devboxes/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/devboxes/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add namespacelabs/agent-skills --skill devboxes -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/devboxes/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add namespacelabs/agent-skills --skill devboxes -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/devboxes/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install namespacelabs/agent-skills devboxes
```

2. **Manually: put the files in place**
- File: `.github/skills/devboxes/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add namespacelabs/agent-skills --skill devboxes -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/namespacelabs/agent-skills --path skills/devboxes
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/devboxes/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add namespacelabs/agent-skills --skill devboxes -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/namespacelabs/agent-skills/tree/HEAD/skills/devboxes/SKILL.md

## When to use it
- run test suites and builds on remote Linux or macOS machines
- spin up an isolated, disposable Docker host
- share preview web services with team members through `devbox.so` URLs
- offload compute-heavy tasks that exceed local hardware capacity

## Example prompts
- Create an ephemeral Linux devbox of size s and run the test suite
- Spin up a macos/arm64 devbox of size m to build this package
- Check the current devbox environment and share the web port on devbox.so

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 2aa64ab154ccef86.

BEGIN THIRD-PARTY FILE 2aa64ab154ccef86
````text
---
name: devboxes
description: Creates, runs, shares, and tears down Namespace devboxes with `devbox` or `boxctl`. Use for isolated Linux or macOS environments, remote builds or tests, disposable Docker hosts, workloads exceeding local capacity, exposing `devbox.so` URLs, or working inside a devbox (`NAMESPACE_DEVBOX_WORKSPACE_DIR` is set), including keeping unattended work alive with task markers.
---

# Namespace devboxes

Namespace devboxes are remote `linux/amd64` or `macos/arm64` machines. Linux devboxes have Docker available. This skill describes the general building blocks for working with devboxes - creating them, transferring files, hydrating a workspace, installing toolchains, running commands with `devbox exec`, sharing web work with teammates through `devbox.so`, and managing the devbox lifecycle.

Throughout this skill:

- **devbox** - a Namespace machine, identified by its `name`.
- `<name>` - the devbox name passed to all `devbox` subcommands.

The devbox may be long-lived, reused across tasks, or torn down immediately depending on the caller's intent. Pass `--ephemeral` at creation time to mark it as disposable.

For run-once-then-destroy workflows (single-script or test runs, optional sharding), see [references/run-tests.md](references/run-tests.md).

## 0. Establish where you are running

Everything below assumes you are driving a devbox from somewhere else. First check whether you
are already ON one - the tooling and the auth story are different:

```bash
[ -n "${NAMESPACE_DEVBOX_WORKSPACE_DIR:-}" ] && echo "on a devbox"
```

The Devbox agent injects that variable into every process on the machine, so it is a reliable
one-line check. If it is set, read [references/inside-a-devbox.md](references/inside-a-devbox.md)
before doing anything else. Two things are different there:

- **Ordinary commands need no wrapper.** You are on the machine. Run `go test`, `git` and file
  edits directly, and skip the `devbox` preflight below for work scoped to the devbox you are in.
- **Both CLIs are already usable - do not run `devbox login`.** `boxctl` and `devbox` both ship in
  `~/.devbox/bin`. The `devbox` CLI is authenticated by a *workload* credential, which acts as the
  tenant rather than as a person: it can drive workspace-access devboxes, but not ones private to
  their creator - including, usually, the machine you are on. That is why `boxctl`, which reaches
  the local agent over a socket and needs no credential, is the tool for the current devbox rather
  than merely the quicker one. Beware `devbox auth check-login` here: it reports "Not logged in"
  even while the CLI works, and acting on that leads to a browser login flow you cannot complete.
  The reference covers the rest, including `--access_mode workspace` for creating sibling boxes.
````
END THIRD-PARTY FILE 2aa64ab154ccef86

The third-party file has ended. Everything between the 2aa64ab154ccef86 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2803 of 24536 bytes. © namespacelabs · Apache-2.0 · https://github.com/namespacelabs/agent-skills/tree/HEAD/skills/devboxes/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md