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:

  1. The Namespace CLI installed and authenticated (nsc login)
  2. The Devbox CLI installed:
$curl -fsSL get.namespace.so/devbox/install.sh | bash
  1. A running devbox (create one if you haven't already)

Terminal Access

Direct SSH

The fastest way to get a shell in your devbox:

$devbox ssh main

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

$devbox ssh -A main

Configure SSH

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

$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:

$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:

$devbox port-forward main --ports 3000,8080

Remap ports with local:remote syntax:

$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 two ways to get started:

  • 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), 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.

VS Code / Cursor

Open your devbox directly in VS Code or Cursor:

$devbox open-ide main
$devbox open-ide main --flavor cursor

This will:

  1. Configure local SSH access to your devbox
  2. Ensure the Remote - SSH extension is installed (see the VS Code Remote-SSH documentation for more details)
  3. Open a new window connected to your devbox

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

From the dashboard: Click the "Open VSCode" dropdown on your devbox to choose between VS Code (desktop), Cursor (desktop), or VS Code on the Web (browser-based).

JetBrains

JetBrains IDEs support remote development through JetBrains Gateway or the built-in remote development features in IDEs like IntelliJ IDEA, GoLand, PyCharm, and WebStorm. See the JetBrains remote development documentation for more details.

  1. Configure SSH access. This writes the SSH key and proxy config so Gateway can connect without manual setup:
$devbox configure-ssh main
  1. Open JetBrains Gateway and select SSH Connection
  2. Create a new connection with the host main.devbox.namespace and username devbox
  3. 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:

$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 support.

Next Steps

Sessions → Learn about persistent terminal sessions that survive disconnections.

Core Concepts → Learn about base images and lifecycle management.

Last updated