Skip to content
d_devboxby 508.dev/ DocumentationDashboard ↗
Browse documentation
DOCUMENTATION / Quickstart

From repository to workspace

Use an existing Linux machine, a trusted SSH alias, Git on your laptop, and Git/tmux on the host. Install and sign in to your preferred coding tool on the host separately.

1. Install the client on your laptop

The client requires Node.js 24 or newer and curl on macOS or Linux. It does not install Node or run sudo.

TERMINAL
curl -fsSL https://devbox.508.dev/install.sh | sh
devbox --help

If the command is not found, add the printed installation directory to your PATH. Installation details.

2. Verify SSH

Create your SSH alias using your existing SSH or VPN configuration. Independently verify the host fingerprint before accepting its key. The hostname below is an example: replace it with your own alias.

TERMINAL
ssh my-box

If the host needs prerequisites, follow host setup. Devbox does not copy your laptop's SSH keys onto the host.

3. Save the connection

Run on your laptop:

TERMINAL
devbox connection add home --ssh my-box
devbox connection list --json

The connection records the machine and development account, and pins its verified host key. A different machine or account is rejected rather than silently reused.

4. Prepare your repository

Start in a local Git repository with at least one commit:

TERMINAL
cd ~/src/my-app
devbox setup --computer home

A Git bundle transfers the exact revision, including private or unpushed history. Ignored files are excluded. Setup refuses divergent existing remote work instead of overwriting it. Transfer boundaries.

5. Open your editor or agent

TERMINAL
devbox open --computer home --with code
# Or use a vendor CLI already installed and authenticated on the host:
devbox open --computer home --with codex

VS Code needs its Remote SSH support. Agent and shell launches use stable host tmux sessions. Detach with Ctrl+B, then D; closing the laptop does not stop that session.

6. View your development server

Start your app using its normal development command on the host. Then, on your laptop:

TERMINAL
devbox preview --computer home

Automatic service selection requires a current host inventory and an attributable HTTP listener. On a plain SSH host, specify the remote port explicitly:

TERMINAL
devbox preview 3000 --computer home

Private previews explains discovery, local ports, HMR and recovery.

Choose a folder or native desktop app

TERMINAL
devbox setup --computer home --remote-dir '~/src/payments' --existing reuse
devbox open --computer home --remote-dir '~/src/payments' --with claude-desktop
devbox open --computer home --remote-dir '~/src/payments' --with codex-desktop

Custom paths expand on the host. Read the existing-code and recovery rules before choosing update, merge or replace. Claude Desktop asks you to confirm a new SSH session in the exact folder; Codex desktop opens connection setup and still requires manual folder selection. See the tool capability matrix for versions and conversation limits.

Development machines. Your code. Your control.
Private pilot · Feature availability is called out in each guide.