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

# SSH

> Open a shell, run a command or forward a port into a machine.

You connect in one of two ways. With the `instabox` CLI, you need no token. Without the CLI, create an
SSH token first.

| You connect from | Do this |
| - | - |
| A computer with the CLI | Run `instabox ssh dev`. The CLI handles the certificate and `known_hosts`. |
| A terminal without the CLI | [Create an SSH token](#connect-from-any-terminal-without-the-cli), then paste its line. |
| An editor or ADE | Follow [ADEs](https://instabox.sh/docs/use-cases/ade). |

```bash theme={null}
instabox ssh dev                 # certificate, known_hosts and ssh in one step
instabox ssh dev -- uname -a     # run one command
instabox mosh dev                # like instabox ssh, with mosh
instabox ssh-config dev          # print a ~/.ssh/config Host block
instabox ssh-cert dev            # refresh only the certificate
```

## Connect from any terminal without the CLI

Create the token in the dashboard or with the CLI on another computer:

* **Dashboard:** in a machine's **Connect** section, open **SSH tokens** and select **Create token**.
  The line stays in that section, ready to copy.
* **CLI:** run `instabox ssh-token dev`. A token works for 7 days by default. `--ttl` sets another
  time, up to 30 days, or `never`.

Either way you get one `ssh ibssh_…@<host>` line to paste anywhere, with no CLI or SSH key needed. The
first time you connect, ssh asks you to confirm the gateway's host key.

> [!WARNING]
>
> Anyone with the line can open a shell in the machine. To revoke every token of a machine, run
> `instabox ssh-token --revoke dev`.

## Forward a port to your computer

```bash theme={null}
instabox port-forward dev 8080:3000         # machine port 3000 at http://127.0.0.1:8080
instabox port-forward dev 3000              # LOCAL defaults to REMOTE
instabox port-forward dev 8080:3000 5432    # several ports at once
```

The forward runs until you press Ctrl-C. `forward` is an alias, and `--remote 3000 --local 8080`
spells the same forward as flags.

A forward is `ssh -N -L` with the instabox certificate, so it reaches any TCP service. Only you can use
it, because it listens on `127.0.0.1` unless `--address` or `--bind` says otherwise. For a URL other
people can open, publish the port instead: [Public and private ports](https://instabox.sh/docs/access/ports.md).

## Keep a session alive with mosh

[mosh](https://mosh.org) keeps a session alive through sleep, network changes, and packet loss.
Install it on your computer (macOS: `brew install mosh`). Then run `instabox mosh dev`, or the mosh
command that **Create token** shows.

On a machine from a snapshot made before mosh was added, run `sudo apt install mosh` once.

## Paste images

In `instabox ssh` on macOS, or on Linux with `xclip` or `wl-paste`, press Ctrl+V with a PNG image on
your clipboard. The CLI uploads the image to the machine's `/tmp` and pastes its path, which Claude
Code attaches as an image.

> [accordion] Ctrl+V details and turning it off
>
> Ctrl+C cancels a slow upload, and a failed paste rings the terminal bell. A clipboard without an
> image, or with a JPEG, sends Ctrl+V as usual.
>
> To let Ctrl+V reach vim (visual block) or readline (quoted insert) while an image is on the
> clipboard, pass `--no-paste` or set `INSTABOX_NO_PASTE=1`.

## Copy large files with the CLI, not scp

For large uploads, use `instabox push` or `instabox cp`. They use the HTTP API, which sends a file of
64 MiB or more as 4 parallel PUTs. scp or rsync over `ssh.instabox.sh` keeps about 2 MiB in flight per
connection, so it slows with distance.

> [accordion] Measured throughput
>
> At a 5 ms round trip, both paths do about 104 MB/s. At 305 ms, the API does 11-13 MB/s per stream and
> SSH does 3-6 MB/s. Together, 4 parallel API PUTs did 39 MB/s.

## How it works

The instabox gateway terminates SSH. A connection is `ssh -p <port> <machine-id>@<host>`, with a
short-lived user certificate and a `known_hosts` line `@cert-authority [<host>]:<port> <host CA key>`
that trusts the gateway. The gateway relays mosh's UDP too, so only the gateway has to be reachable.

* **Supported:** sessions (pty, shell, exec, subsystem, env, and signals) and local port forwarding.
* **Not supported:** agent forwarding, X11, and remote forwarding.
* Connections close when the machine stops, pauses, or is deleted.

> [card] [Public and private ports](https://instabox.sh/docs/access/ports.md)
>
> An HTTPS URL for a web server in the machine.

> [card] [Desktop](https://instabox.sh/docs/access/desktop.md)
>
> Watch and drive the machine's desktop.