Get Started with the Devbox CLI

The Devbox CLI creates, connects to, and manages Devboxes from your terminal. Use it when you want to drive Devboxes from your existing shell workflow, script them, or open one in a local IDE. This page takes you from an empty machine to a Devbox you can run commands in. If you prefer to start in the browser, follow the Dashboard flow in the Introduction.

Getting Started

Install the Devbox CLI

macOS
Linux
Windows

curl -fsSL get.namespace.so/devbox/install.sh | bash

curl -fsSL get.namespace.so/devbox/install.sh | bash

Run the following command in PowerShell:

irm https://get.namespace.so/devbox/install.ps1 | iex

Restart your terminal if devbox is not available on your PATH after installation.Connecting over SSH also requires an OpenSSH client. Most modern Windows installations include one.

Confirm the installation:

devbox version

Authenticate with Namespace

devbox login

The command prints a login URL and opens it in your browser. Complete the flow there, and the CLI stores a user credential in your operating system’s user configuration directory.Check the stored credential at any time:

devbox auth check

Create a Devbox

devbox create provisions a Devbox and activates it, so it is ready to connect to when the command returns. Supply its configuration interactively or as flags.

Interactive
Non-interactive

The CLI prompts for a name, an image, and a machine size:

devbox create --checkout github.com/your-org/your-repo

Pass every value as a flag to skip the prompts:

devbox create --name my-devbox --image builtin:agents --size m --checkout github.com/your-org/your-repo

--checkout clones a repository into the Devbox and requires a connected GitHub organization. Omitting it applies the workspace default repository, and --no_checkout skips the checkout entirely.See devbox create for the full set of options, including Blueprints, ephemeral Devboxes, and specification files.

Connect to your Devbox

devbox ssh opens an interactive shell inside the Devbox. The connection is tunneled through the Namespace API, so no public IP address or open port is involved.

Connecting to a stopped Devbox starts it first, and your files persist across stop and start cycles.

Interactive
Non-interactive

Omit the name and the CLI lists your Devboxes so you can pick one:

devbox ssh

Pass the name to connect straight to a known Devbox:

devbox ssh my-devbox

Run devbox list to see the Devboxes in your workspace and their state.

And run ls to see the cloned files:

ls

Open an IDE

Open the Devbox in a local editor:

devbox open-ide my-devbox

See IDEs for JetBrains, and Remote Development for using your own SSH config.

Run a command without a shell

devbox exec runs a single command in the Devbox and streams the output back to your terminal:

devbox exec my-devbox -- go build ./...

For commands that outlive your connection, see Executing Commands and Running long tasks.

Devbox CLI reference

Every command, flag, and option is documented in the reference, starting with installation and updates.

devbox create

Images, sizes, Blueprints, and specification files.

devbox ssh

Interactive sessions, remote commands, and agent forwarding.

devbox exec

Detached executions and retrieving their logs.

Set this up with a coding agent

Namespace publishes Devbox agent skills in namespacelabs/agent-skills. A skill is an instruction pack that gives a coding agent a repeatable workflow for Devboxes: installing the CLI, logging in, creating and hydrating them, running commands, and tearing them down. Hand your agent the prompt below. It installs the skill, then follows it. You will need to complete the login in your browser when the agent reaches that step.

Agent Prompt

Install the Namespace devboxes agent skill, then use it to set me up:

  npx skills add namespacelabs/agent-skills

Following that skill:

1. Install the Devbox CLI for my operating system, then confirm it works.
2. Log me in to Devbox, then verify that the login succeeded.
3. Create a Devbox for me at size `m`. If we are working in a git repository,
   check that repository out in the Devbox so my code is already there.
4. List my Devboxes, then report the new one's name, its state, and how I can
   open a shell in it.

Do not delete or stop any Devbox that already exists in my workspace.

To install the skill yourself, or to install it globally rather than per project, see Agent Skills.

Next steps

Remote Development

SSH access and SSH config for a Devbox.

Devbox Lifecycle

Listing, starting, stopping, idleness, and deleting.

IDEs

Open a Devbox in VS Code, Cursor, JetBrains, or Zed.

Products

Platform

Administration

Getting Started

Install the Devbox CLI

Authenticate with Namespace

Create a Devbox

Connect to your Devbox

Open an IDE

Run a command without a shell

Devbox CLI reference

devbox create

devbox ssh

devbox exec

Set this up with a coding agent

Next steps

Remote Development

Devbox Lifecycle

IDEs

​Getting Started

Install the Devbox CLI

Authenticate with Namespace

Create a Devbox

Connect to your Devbox

Open an IDE

​Run a command without a shell

​Devbox CLI reference

devbox create

devbox ssh

devbox exec

​Set this up with a coding agent

​Next steps

Remote Development

Devbox Lifecycle

IDEs

Getting Started

Run a command without a shell

Devbox CLI reference

Set this up with a coding agent

Next steps