# High-Performance Developer Environments with Devboxes

Devboxes are managed Linux and macOS development environments for people and AI coding agents. Each Devbox is a remote machine with persistent storage, reachable over SSH or from your local IDE.

Linux Devboxes run from a container image you choose and include Docker. macOS Devboxes run on Apple Silicon, with a choice of macOS and Xcode versions. Because the environment comes from a shared definition, your team and your agents work on the same setup.

> **[With an agent](#getting-started)**  
> Let a coding agent install the CLI and create your first Devbox.
> 
> **[With the CLI](#getting-started-cli)**  
> Install the CLI, create a Devbox, and start an agent in a session.
> 
> **[With the Dashboard](#getting-started-dashboard)**  
> Create a Devbox in the browser, with nothing to install.

## Get Started with an Agent

The quickest way to get started is to let a coding agent do it for you.

### 1. Install the agent skill

Install the [Namespace devboxes skill](/content/docs/reference/devbox-cli/agent-skills.md) for your coding agent.

**Global**

Installs the skill for every project on this machine:

```bash
npx skills add namespacelabs/agent-skills --global
```

**Project**

Installs the skill into the current project only. Run this from the project directory:

```bash
npx skills add namespacelabs/agent-skills
```

The skill gives the agent a repeatable workflow for creating Devboxes, loading source code, running commands, and cleaning up after the task.

### 2. Create a Devbox with the agent

Ask your agent to create a Devbox:

```text wrap Agent Prompt
devbox create
```

> [!NOTE]
> If the [Devbox CLI](/content/docs/reference/devbox-cli.md) is not installed, the agent installs it and runs `devbox login`. Complete the login in your browser when prompted.

## Get Started with the CLI

Follow these steps to install the CLI and create a Devbox from your terminal.

### 1. Install the Devbox CLI

**macOS**

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

**Linux**

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

**Windows**

Run the following command in PowerShell:

```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](https://learn.microsoft.com/windows-server/administration/openssh/openssh_install_firstuse). Most modern Windows installations include one.

Confirm the installation:

```bash
devbox version
```

### 2. Authenticate with Namespace

```bash
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:

```bash
devbox auth check
```

### 3. 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**

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

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

**Non-interactive**

Pass every value as a flag to skip the prompts:

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

`--checkout` clones a repository into the Devbox and requires a [connected GitHub organization](#getting-started-dashboard). Omitting it applies the workspace default repository, and `--no_checkout` skips the checkout entirely.

See [`devbox create`](/content/docs/reference/devbox-cli/create/index.html) for the full set of options, including Blueprints, ephemeral Devboxes, and specification files.

### 4. Connect to your Devbox

Connect to a [session](/content/docs/devbox/connecting.md#sessions/index.html) on the Devbox. A session keeps running when you close your terminal or disconnect, so work you start in it carries on without you.

```bash
devbox session connect --session agent
```

The CLI lists your Devboxes and their sessions, with an option to start a new session.

> [!NOTE]
> Connecting to a stopped Devbox starts it first, and your files persist across stop and start cycles.

### 5. Start your favorite agent

Start a coding agent in the Devbox and give it a task. The agent works on the Devbox itself, with its own files, tools, and terminal:

**Amp**

```bash
amp
```

**Claude Code**

```bash
claude
```

**Codex**

```bash
codex
```

**Copilot**

```bash
copilot
```

**Cursor**

```bash
cursor-agent
```

**OpenCode**

```bash
opencode
```

## Get Started with the Dashboard

The Dashboard needs no local installation. Follow these steps to create your first Devbox in the browser and open a shell in it.

### 1. Connect a code provider

Open [Devboxes](https://cloud.namespace.so/workspace/devboxes) in the Namespace Dashboard and connect a code provider so Namespace can clone your repositories. Devboxes can check out from GitHub and [Cursor Origin](https://cursor.com).

If you have not connected a provider yet, choose one from the Devboxes page:

* For GitHub, press **Connect with GitHub** and follow the instructions to install the Namespace GitHub app.
* For Cursor Origin, press **Other providers**, then select Cursor Origin on the Code Providers page.

After you connect a provider, use [Code Providers](https://cloud.namespace.so/workspace/code/providers) to connect another one.

> [!NOTE]
> Connecting a provider lets Namespace clone your repositories into a Devbox, which is how you work on your own code. To look around first, select **create a Devbox from scratch** and connect a provider later.

### 2. Create a Devbox

Press **+ Create** on the Devboxes page.

Give your Devbox a name or keep the generated one. Then press **Repository** and select the repository to check out.

> [!NOTE]
> The list shows the repositories Namespace can reach through the GitHub app. If the one you want is missing, or you skipped the previous step, use the **Connect an organization** entry at the end of the list.

Press **Create Devbox**. After a few seconds, your Devbox will be ready to use.

### 3. Connect and develop

The Devbox page shows its state and its initialization log while it starts.

Once the log reaches **Ready**, open the **Terminal** tab (for a shell in the Devbox without installing anything locally) and run `ls` to see the cloned files:

```bash
ls
```

### 4. Open VS Code

Use the **Open VSCode** dropdown to open the Devbox in VS Code, Cursor, or VS Code for the Web. See [IDEs](/content/docs/devbox/ides.md) for the full list of supported editors, including JetBrains and Zed.

## Next Steps

> **[Devbox Lifecycle](/content/docs/devbox/lifecycle.md)**  
> Create, list, stop, and delete Devboxes.
> 
> **[SSH & Sessions](/content/docs/devbox/connecting.md)**  
> Open a shell on a Devbox with SSH or a session.
> 
> **[IDEs](/content/docs/devbox/ides.md)**  
> Open a Devbox in VS Code, Cursor, JetBrains, or Zed.
> 
> **[Services](/content/docs/devbox/services.md)**  
> Keep dev servers and other processes running on a Devbox.

## Enterprise Support

Need dedicated capacity, custom machine shapes, or specialized support for your development team? Contact our [support team](mailto:support@namespace.so) for consultation on complex development environment requirements.