> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# High-Performance Developer Environments with Devboxes

Devboxes are managed Linux, macOS, and Windows development environments for people and AI coding agents. Each Devbox is a remote machine, 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. Windows Devboxes run from Namespace-managed Windows images. Because the environment comes from a shared definition, your team and your agents work on the same setup.

> [!NOTE]
>
> Windows Devboxes are in early access. This release supports [ephemeral Devboxes](https://namespace.so/docs/devbox/blueprint.md#ephemeral) only.

> [card] [With an agent](#getting-started)
>
> Let a coding agent install the CLI and create your first Devbox.

> [card] [With the CLI](#getting-started-cli)
>
> Install the CLI, create a Devbox, and start an agent in a session.

> [card] [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](https://namespace.so/docs/reference/devbox-cli/agent-skills.md) for your coding agent.

> [tab] Global
>
> Installs the skill for every project on this machine:
>
> ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> npx skills add namespacelabs/agent-skills --global
> ```

> [tab] Project
>
> Installs the skill into the current project only. Run this from the project directory:
>
> ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> 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 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
create a devbox
```

> [!NOTE]
>
> If the [Devbox CLI](https://namespace.so/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

> [tab] macOS
>
> ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> curl -fsSL get.namespace.so/devbox/install.sh | bash
> ```

> [tab] Linux
>
> ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> curl -fsSL get.namespace.so/devbox/install.sh | bash
> ```

> [tab] Windows
>
> Run the following command in PowerShell:
>
> ```powershell theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> 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.

> [tab] Homebrew
>
> Alternatively, install with Homebrew on macOS or Linux:
>
> ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> brew install namespacelabs/devbox/cli
> ```
>
> See [installation and updates](https://namespace.so/docs/reference/devbox-cli/installation.md) for Homebrew trust settings and upgrade instructions.

Confirm the installation:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
devbox version
```

### 2. Authenticate with Namespace

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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.

> [tab] Interactive
>
> The CLI prompts for a name, an image, and a machine size:
>
> ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> devbox create --checkout github.com/your-org/your-repo
> ```

> [tab] Non-interactive
>
> Pass every value as a flag to skip the prompts:
>
> ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> devbox create --name my-devbox --image builtin:default --size m --checkout github.com/your-org/your-repo
> ```

For a Windows Devbox, pick a Windows image:

```bash wrap theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
devbox create --image windows-2022 --size m --name my-windows-devbox
```

`--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`](https://namespace.so/docs/reference/devbox-cli/create) for the full set of options, including Blueprints, ephemeral Devboxes, and specification files.

### 4. Connect to your Devbox

Connect to a [session](https://namespace.so/docs/devbox/connecting.md#sessions) 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 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
devbox session connect --session agent
```

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

> [!NOTE]
>
> For persistent Devboxes, 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:

> [tab] Amp
>
> ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> amp
> ```

> [tab] Claude Code
>
> ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> claude
> ```

> [tab] Codex
>
> ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> codex
> ```

> [tab] Copilot
>
> ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> copilot
> ```

> [tab] Cursor
>
> ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> cursor-agent
> ```

> [tab] OpenCode
>
> ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> 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.

![Devboxes empty state with options to connect GitHub, select another provider, or create a Devbox from scratch](https://mintcdn.com/namespace-labs/DmrnXcQln8ee4bAT/images/devboxes/devbox-connect-provider.webp?fit=max\&auto=format\&n=DmrnXcQln8ee4bAT\&q=85\&s=49167a06f6ffd7805977b90ecc09afbe)

> [!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.

![The Devboxes page with the + Create button in the top right](https://mintcdn.com/namespace-labs/gFazvjcdlAyUqYv5/images/devboxes/devbox-create-1.webp?fit=max\&auto=format\&n=gFazvjcdlAyUqYv5\&q=85\&s=85c14353f6fe5e4c0c7d49618adc9084)

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

![The New devbox dialog with the repository list expanded](https://mintcdn.com/namespace-labs/gFazvjcdlAyUqYv5/images/devboxes/devbox-create-2.webp?fit=max\&auto=format\&n=gFazvjcdlAyUqYv5\&q=85\&s=72a722e85c2b11b70779f8a0edd323aa)

> [!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.

![Devbox dashboard with initialization log](https://mintcdn.com/namespace-labs/gFazvjcdlAyUqYv5/images/devboxes/devbox-dashboard.webp?fit=max\&auto=format\&n=gFazvjcdlAyUqYv5\&q=85\&s=5fa9d5837d59c30592ad60e06d4e8b91)

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 theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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](https://namespace.so/docs/devbox/ides.md) for the full list of supported editors, including JetBrains and Zed.

## Next Steps

> [card] [Devbox Lifecycle](https://namespace.so/docs/devbox/lifecycle.md)
>
> Create, list, stop, and delete Devboxes.

> [card] [SSH & Sessions](https://namespace.so/docs/devbox/connecting.md)
>
> Open a shell on a Devbox with SSH or a session.

> [card] [IDEs](https://namespace.so/docs/devbox/ides.md)
>
> Open a Devbox in VS Code, Cursor, JetBrains, or Zed.

> [card] [Services](https://namespace.so/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.