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

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

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.

​
Keep a session alive with mosh

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

Public and private ports

An HTTPS URL for a web server in the machine.

Desktop

Watch and drive the machine’s desktop.