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

# Remote Development

Connect to your Devbox from your local environment using SSH, your preferred terminal, or a full IDE. All remote connections are tunneled securely through the Namespace API. No public IP addresses or open ports are required.

## Prerequisites

Before connecting, make sure you have completed [Getting Started](/docs/devbox#getting-started) — the Devbox CLI must be installed and authenticated. You'll also need a running Devbox.

## Terminal Access

### Direct SSH

The fastest way to get a shell in your Devbox:

```bash theme={null}
devbox ssh main
```

This establishes an interactive SSH session directly to your Devbox. Use the `-A` flag to forward your local SSH agent:

```bash theme={null}
devbox ssh -A main
```

### Configure SSH

To use the standard `ssh` command (and enable any tool that relies on SSH config), run:

```bash theme={null}
devbox configure-ssh main
```

This sets up your local `~/.ssh/config` with an `Include` directive pointing to `~/.namespace/ssh/`, writes the SSH key and a host config for your Devbox. After running this, you can connect with:

```bash theme={null}
ssh main.devbox.namespace
```

This also enables tools like `scp`, `rsync`, and any program that reads your SSH config.

### Port Forwarding

Forward ports from your Devbox to localhost:

```bash theme={null}
devbox port-forward main --ports 3000,8080
```

Remap ports with `local:remote` syntax:

```bash theme={null}
devbox port-forward main --ports 4000:3000
```

If your Devbox has configured port forwards in its blueprint, running `devbox port-forward main` without `--ports` will forward all of them automatically.

## IDEs

All IDE integrations connect over SSH. There are three ways to get started:

* **Dashboard:** Open VS Code or Cursor directly from the Devbox dashboard.
* **Automatic:** `devbox open-ide` configures SSH and opens your IDE in one step. Available for VS Code, Cursor, Zed, and others.
* **Manual:** Run `devbox configure-ssh` first (see [Configure SSH](#configure-ssh)), then connect from your IDE using the SSH host. You may need to specify a working directory. Use `/workspaces/{repo-name}` if you created your Devbox with `--checkout`.

<h3 id="vs-code--cursor">
  VS Code / Cursor
</h3>

#### Open from the dashboard

1. In the Devbox dashboard, click **Open VSCode** and choose VS Code (desktop) or Cursor (desktop)

VS Code installs the Namespace Devbox extension automatically. On first use, the extension will open your browser to authenticate with Namespace. Once authenticated, it connects to your Devbox.

#### Open from the CLI

Open your Devbox directly in VS Code or Cursor:

```bash theme={null}
devbox open-ide main
```

```bash theme={null}
devbox open-ide main --flavor cursor
```

This will:

1. Configure local SSH access to your Devbox
2. Ensure the [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) extension is installed (see the [VS Code Remote-SSH documentation](https://code.visualstudio.com/docs/remote/ssh) for more details)
3. Open a new window connected to your Devbox

You can also use `--flavor vscode-insiders`, `--flavor codium`, `--flavor positron`, `--flavor windsurf`, or `--flavor zed`.

### JetBrains

JetBrains IDEs support remote development through [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/) or the built-in remote development features in IDEs like IntelliJ IDEA, GoLand, PyCharm, and WebStorm. See the [JetBrains remote development documentation](https://www.jetbrains.com/help/idea/remote-development-starting-page.html) for more details.

1. Configure SSH access. This writes the SSH key and proxy config so Gateway can connect without manual setup:

```bash theme={null}
devbox configure-ssh main
```

2. Open JetBrains Gateway and select **SSH Connection**
3. Create a new connection with the host `main.devbox.namespace` and username `devbox`
4. Select the IDE and project directory on the remote host

JetBrains Gateway installs the IDE backend on your Devbox and streams the UI to your local machine.

### Zed

Open your Devbox in Zed:

```bash theme={null}
devbox open-ide main --flavor zed
```

This opens Zed with a remote SSH connection to your Devbox. Zed connects using its [native SSH remote development](https://zed.dev/docs/remote-development) support.

## Next Steps

**[Sessions →](/docs/devbox/sessions)**
Persistent terminal sessions that survive disconnections and Devbox restarts.

**[Managing Devboxes →](/docs/devbox/managing)**
Lifecycle operations, machine sizes, workspace defaults, and monitoring.

**[Custom Images →](/docs/devbox/images)**
Build custom base images with your tools and runtimes pre-installed.