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

# Editor & SSH workflows

> SSH straight into your VMs. Cursor, VS Code, Antigravity, or any Remote-SSH editor.

Every VM is reachable over plain SSH through a managed `name.boxd` host alias the CLI keeps in `~/.ssh/config` (auto-synced on `boxd machine new` / `list` / `fork`). Cursor, VS Code, Antigravity — any Remote-SSH editor — see your boxes in their pickers. Enable the [client utilities](/reference/client-utilities) (`boxd config set client-utils.enable true`) on your Mac for clipboard sync, local file access, and a real Chrome browser controllable from inside the VM.

## How it works

Each VM listens on a dedicated SSH **port** (in the 10000–30000 range) on the shared proxy IP. The CLI writes a `Host name.boxd` alias into `~/.ssh/config` for each VM — carrying the right `HostName`, `Port`, and `User boxd` — so editors that read SSH config (all the popular ones do) get them automatically. You land as the `boxd` user with passwordless sudo, and standard SSH features all work: SCP, port forwarding, rsync, agent forwarding, and remote-development modes in editors.

`boxd machine new`, `fork`, `list`, and `remove` refresh the managed block automatically, so the aliases stay in sync as VMs come and go. The [client utilities](/reference/client-utilities) (`boxd config set client-utils.enable true`) run a small background agent on your Mac that bridges local resources (clipboard, files, browser) into the VMs you enter.

<Note color="#E05A6D">
  Use the `name.boxd` **alias**, not the bare `name.boxd.sh` domain. The domain on its default port (22) doesn't reach the machine — it just prints a notice to use the CLI; the alias carries the per-VM port that routes you to the machine.
</Note>

## Set up

<Steps>
  <Step title="Install boxd">
    ```bash theme={"theme":"github-dark"}
    curl -fsSL https://boxd.sh/downloads/install.sh | sh
    ```

    One installer brings the `boxd` CLI **and** the built-in client utilities bridge (clipboard sync, local file access, local browser control — macOS Apple Silicon for now; turn it on with `boxd config set client-utils.enable true`). The CLI then writes managed `~/.ssh/config` entries for you — automatically on every `boxd machine new` / `list` / `fork` / `remove`:

    ```text theme={"theme":"github-dark"}
    Host myapp.boxd
        HostName myapp.boxd.sh
        Port 21000
        User boxd
    ```

    The CLI manages this block for you — it's refreshed on every `boxd machine new` / `fork` / `list` / `remove` / `rename`, so you never edit it by hand.
  </Step>

  <Step title="Pair your SSH key">
    ```bash theme={"theme":"github-dark"}
    boxd auth login
    ```

    First run prints a GitHub sign-in URL. After linking, the key on your machine is your identity.
  </Step>
</Steps>

## Connect your editor

<Tip>
  **One click from the console:** open [boxd.sh/app](https://boxd.sh/app), find your machine, and hit **Open in Terminal** or **Open in Editor** (VS Code, Cursor, Antigravity). It launches straight into the VM. The tabs below are the manual equivalents.
</Tip>

<Tabs>
  <Tab title="VS Code / Cursor / Antigravity">
    Open the command palette, run **Remote-SSH: Connect to Host**, and pick `myapp.boxd`. Your VM opens as a remote workspace; extensions install into it the first time.
  </Tab>

  <Tab title="Terminal">
    ```bash theme={"theme":"github-dark"}
    ssh myapp.boxd
    ```

    Lands you in a shell as `boxd`. Run vim, neovim, tmux, whatever you like. (No SSH config yet? `boxd connect myapp` gets you a shell without one.)
  </Tab>
</Tabs>

Any other editor that reads `~/.ssh/config` works the same way — JetBrains Gateway, Zed, etc. Pick `myapp.boxd` from its Remote-SSH list.

## Recipes

### Paste a screenshot into Claude Code inside the VM

With the client utilities enabled (`boxd config set client-utils.enable true`), your Mac's clipboard is reachable from inside the VM via an `xclip` shim. Paste images directly into `claude` running over SSH.

```bash theme={"theme":"github-dark"}
ssh myapp.boxd       # from your laptop
claude               # now inside the VM — paste a screenshot from your Mac
```

### Read a file off your laptop, no scp

From inside the VM, `boxd local` reaches back to your Mac through the client agent:

```bash theme={"theme":"github-dark"}
boxd local ls ~/Documents
boxd local read ~/notes.txt --tail=50
```

Access is scoped to your home directory and macOS temp directories.

### Drive a real Chrome from inside the VM

```bash theme={"theme":"github-dark"}
boxd local browser open
# prints "CDP WebSocket: <url>" — point Puppeteer/Playwright at that URL
```

Sessions persist across `open`/`close`, so logged-in state survives.

### Port-forward a service to your laptop

```bash theme={"theme":"github-dark"}
ssh -L 5432:localhost:5432 myapp.boxd   # from your laptop
```

Postgres in the VM, on `localhost:5432` on your Mac.

## FAQ

<AccordionGroup>
  <Accordion title="Does Remote SSH need any special setup?">
    No. Once the CLI has written the managed block (it does this automatically), the host appears in your editor's Remote SSH list. The editor handles its own server install inside the VM the first time you connect.
  </Accordion>

  <Accordion title="Can multiple machines share the same identity?">
    Yes. SSH from a different machine with a new key and go through the link flow again. The new key attaches to your existing account via your GitHub identity.
  </Accordion>

  <Accordion title="What's the difference between `ssh name.boxd` and `boxd connect name`?">
    `ssh name.boxd` is direct SSH into the VM, through the host alias the CLI writes (it carries the VM's per-VM port). `boxd connect name` opens a shell through the control plane — no SSH config needed. Same result, pick whichever fits your flow.
  </Accordion>

  <Accordion title="Are the client utilities available on Linux/Windows?">
    macOS (Apple Silicon) today. Linux is on the roadmap.
  </Accordion>
</AccordionGroup>

## Next

<Columns cols={2}>
  <Card title="CLI reference" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/command.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=6c33d9e29e4e937c0950311233ec5659" href="/reference/external-cli" width="16" height="16" data-path="images/icons/command.svg">
    Every command, every flag.
  </Card>

  <Card title="Client utilities" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/laptop.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=c8b9b157a17a9295dc35a5b783fe8498" href="/reference/client-utilities" width="16" height="16" data-path="images/icons/laptop.svg">
    Full reference for `boxd local` and the client utilities toggle.
  </Card>
</Columns>