SSH Access

Every Rigbox workspace is a Linux VM you can reach over SSH. The CLI sets up access for you: after rig login, ssh <workspace> opens a shell in any running workspace, and the same name works with scp, sftp, rsync, and tools that read your SSH config.

Prerequisites

The Rigbox CLI, signed in with rig login.
OpenSSH on your machine (ssh, ssh-keygen, and ssh-keyscan). macOS and most Linux distributions include it.
A running workspace. List yours with rig workspace ls.

How the CLI sets up SSH

rig login, rig ssh add, and the workspace commands that print an SSH command (rig workspace spawn, start, restart, and ssh-info) set up SSH access from the machine you run them on:

Your key. The CLI uses ~/.ssh/id_ed25519.pub, or ~/.ssh/id_rsa.pub if that is the key you have. When you have neither, it creates an ed25519 key pair at ~/.ssh/id_ed25519, without a passphrase. It registers the public key on your account as laptop-<hostname> unless the key is already there, and waits for running workspaces to pick it up.
A host entry per workspace. The CLI writes ~/.config/rigbox/ssh_config with one Host entry for each of your workspaces, and adds an Include line for that file, with a comment, to the top of ~/.ssh/config. That is the only change it makes to your own SSH config.
Trusted host keys. The first time the CLI sets up a host, it records the gateway’s host keys in ~/.config/rigbox/known_hosts, so SSH clients connect without a first-connect prompt. That matters for tools that can’t answer one.

The first time you sign in, the CLI reports what it set up:

  → No SSH key found — generated /Users/you/.ssh/id_ed25519 for you
  ⓘ Auto-registered /Users/you/.ssh/id_ed25519.pub as laptop-mbp (one-time setup for SSH-backed deploys)
  ✓ Propagated to my-project
  ⓘ Added `Include ~/.config/rigbox/ssh_config` to ~/.ssh/config — `ssh <workspace>` now works

Each entry in ~/.config/rigbox/ssh_config looks like this:

Host my-project my-project-ctbxi8lb
    HostName eu-west-1.rigbox.dev
    User my-project-ctbxi8lb
    IdentityFile /Users/you/.ssh/id_ed25519
    UserKnownHostsFile /Users/you/.config/rigbox/known_hosts
    StrictHostKeyChecking accept-new
    CheckHostIP no
    ServerAliveInterval 30
    ServerAliveCountMax 4

An entry answers to the workspace’s name (lowercased, with anything other than letters, digits, and dashes turned into dashes) and to its login name, <name>-<id suffix>. When two workspaces share a name, or you already use that name for a host in your own SSH config, the entry keeps only the login name. rig workspace ssh-info shows which alias to use. The CLI rewrites the file from your workspace list, so edits to it are lost; rig workspace ls and rig workspace rm keep it current. Stopped workspaces have entries too. Nothing is set up inside a workspace, on a CI runner (CI or GITHUB_ACTIONS set), or when the CLI authenticates with a deploy token.

Connect to a workspace

Use the workspace name:

ssh my-project

Run a single command, or ask for a terminal with -t when the command needs one, such as an interactive program or a sudo prompt:

ssh my-project 'cd ~/app && npm test'
ssh -t my-project tmux attach

Editors and apps that read ~/.ssh/config, including SSH connections in the Claude desktop app, can use the same alias. SFTP is available, so tools that browse or copy files over SFTP work too. To print the connection details for a workspace:

rig workspace ssh-info --workspace my-project

SSH Info

  Workspace: my-project
  Status:    running
  Host:      eu-west-1.rigbox.dev
  SSH:       ssh my-project
             ssh my-project-ctbxi8lb@eu-west-1.rigbox.dev
  Config:    /Users/you/.config/rigbox/ssh_config (Host my-project)

The second ssh line is the full command, which works without the managed config. For scripts, --output json returns the same details, including ssh_target and, once access is set up, ssh_alias.

Connecting to the right region

The full SSH target is <WORKSPACE_NAME>-<WORKSPACE_ID_SUFFIX>@<REGION>.rigbox.dev: the workspace name, its ID without the leading ws-, and the host of the region the workspace runs in (today eu-west-1). The CLI takes the host from the workspace record, and the dashboard shows the same command. There is no central rigbox.dev:22 gateway to fall back on.

Older ssh <name>+rig@rigbox.dev instructions referred to a gateway router that is no longer deployed. If a third-party guide or older script still uses that format, replace it with the workspace alias or the region hostname.

Stopped workspaces

A workspace accepts connections only while it is running. Connecting to a stopped workspace fails with a message on standard error that names the command to start it:

Error: Workspace 'my-project-ctbxi8lb' is not running (status: stopped).
Start it with: rig workspace start --workspace my-project
or from https://rigbox.dev/workspaces

While a workspace is still starting, the message says so; try again in a few seconds. These messages never go to standard output, so a script or SFTP client sees a clean failure rather than stray text in its data.

Forwarding isn’t available

Workspace logins don’t allow port forwarding (-L, -R, -D), agent forwarding (-A), X11 forwarding, or tunnels. Editors that reach their remote server through a forwarded port, such as VS Code Remote-SSH, can’t use this connection. To reach a server running in the workspace, expose it as an app. For Git or other credentials inside the workspace, create them there instead of forwarding your local agent.

Specify an identity file

The managed entries name the key the CLI registered. To use a different key, register it first, then pass it to ssh:

rig ssh add --name my-other-key --file ~/.ssh/my_rigbox_key.pub
ssh -i ~/.ssh/my_rigbox_key my-project

SSH config shortcut

The CLI writes these entries for you (see How the CLI sets up SSH). If you turn that off, add your own entry to ~/.ssh/config:

Host my-project
  HostName eu-west-1.rigbox.dev
  User my-project-ctbxi8lb
  IdentityFile ~/.ssh/id_ed25519

File Transfer

scp, sftp, and rsync accept the workspace alias, just like ssh.

Upload a file

scp ./local-file.txt my-project:/home/developer/

Download a file

scp my-project:/home/developer/output.txt ./

Upload a directory

scp -r ./my-project my-project:/home/developer/

For an interactive session, run sftp my-project.

Using rsync

For larger transfers or repeated syncs, rsync copies only what changed:

rsync -avz ./my-project/ my-project:/home/developer/my-project/

To update a deployed app, use rig deploy instead of copying files into its release directory.

Register an SSH Key

rig login registers your default key, so you only need rig ssh add for another key or another machine:

rig ssh add

Without --file, it uses your default public key and creates one if you have none. Without --name, the key is named laptop-<hostname>. To register a specific key under a name you choose:

rig ssh add --name work-laptop --file ~/.ssh/work_ed25519.pub

rig ssh add also sets up the host entries on this machine. If the key is already on your account, rig says so and doesn’t add it again.

Sync Keys to a Workspace

Running workspaces pick up a newly registered key automatically; rig ssh add and rig login wait for them and report each one. If a workspace didn’t pick the key up in time, push your keys to it:

rig ssh sync --workspace my-project

This copies your registered public keys into the workspace’s ~/.ssh/authorized_keys file.

Managing SSH Keys

List your registered keys

rig ssh ls

The list includes each key’s ID.

List keys synced to a workspace

rig ssh ls --workspace my-project

This returns the keys currently in the workspace’s authorized_keys file.

Remove a key

rig ssh rm --name <KEY_NAME_OR_ID>

Removing a key with the CLI does not immediately remove it from running workspaces. The key will be removed the next time the workspace restarts or you run rig ssh sync.

Turn off automatic setup

To manage SSH yourself:

rig config set ssh-setup false

The CLI then stops registering keys and writing SSH config when you sign in, run rig ssh add, or run the workspace commands. Deploys that copy files over SSH still register your key when they need it. The files it already wrote stay in place: remove the Include line from ~/.ssh/config and delete ~/.config/rigbox/ssh_config if you don’t want them. Turn setup back on with rig config set ssh-setup true.

Troubleshooting

Could not resolve hostname

ssh my-project needs the managed entry. Run rig workspace ssh-info --workspace my-project to write it, then check that ~/.ssh/config includes ~/.config/rigbox/ssh_config. If the CLI couldn’t edit ~/.ssh/config, it printed the line to add. When the plain name is taken, the alias is the login name (my-project-ctbxi8lb); ssh-info shows it.

Connection refused

If ssh reports that the workspace is not running, start it with the command in the message. For other connection failures:

Check that the workspace is running with rig workspace ls.
Connect to the host rig workspace ssh-info prints; don’t hardcode one.
Check that your network allows outbound SSH on port 22.

Permission denied

If you get Permission denied (publickey):

Check that your key is registered: rig ssh ls. If it isn’t, run rig ssh add.
Push your keys to the workspace: rig ssh sync --workspace my-project.
See which keys ssh offers: ssh -v my-project.

The gateway waits up to about ten seconds for your workspace’s keys while the platform restarts a service, so a login at that moment connects late instead of failing. A Permission denied that persists is about the key.

Host key warnings

The CLI keeps workspace host keys in ~/.config/rigbox/known_hosts, separate from ~/.ssh/known_hosts. When a new scan disagrees with a key already on file, the CLI adds nothing, and your SSH client reports the mismatch. Check the change through a trusted channel before editing that file, and don’t turn off host key checking to get past it.

Slow connection

If connections feel slow:

Check your network connection.
Managed entries already send keepalives (ServerAliveInterval 30). With the full user@host command, add -o ServerAliveInterval=60.
For large transfers, prefer rsync over scp.

API Reference

Add SSH Key - Register a new SSH key
List SSH Keys - List registered SSH keys
Delete SSH Key - Remove an SSH key
Sync Workspace SSH Keys - Sync keys to a workspace
List Workspace SSH Keys - List keys on a workspace

Start here

Deploy applications

Configure applications

Workspaces and storage

AI and tools

Operate and troubleshoot

Examples

CLI reference

Build on Rigbox

Prerequisites

How the CLI sets up SSH

Connect to a workspace

Connecting to the right region

Stopped workspaces

Forwarding isn’t available

Specify an identity file

SSH config shortcut

File Transfer

Upload a file

Download a file

Upload a directory

Using rsync

Register an SSH Key

Sync Keys to a Workspace

Managing SSH Keys

List your registered keys

List keys synced to a workspace

Remove a key

Turn off automatic setup

Troubleshooting

Could not resolve hostname

Connection refused

Permission denied

Host key warnings

Slow connection

API Reference

​Prerequisites

​How the CLI sets up SSH

​Connect to a workspace

​Connecting to the right region

​Stopped workspaces

​Forwarding isn’t available

​Specify an identity file

​SSH config shortcut

​File Transfer

​Upload a file

​Download a file

​Upload a directory

​Using rsync

​Register an SSH Key

​Sync Keys to a Workspace

​Managing SSH Keys

​List your registered keys

​List keys synced to a workspace

​Remove a key

​Turn off automatic setup

​Troubleshooting

​Could not resolve hostname

​Connection refused

​Permission denied

​Host key warnings

​Slow connection

​API Reference

Prerequisites

How the CLI sets up SSH

Connect to a workspace

Connecting to the right region

Stopped workspaces

Forwarding isn’t available

Specify an identity file

SSH config shortcut

File Transfer

Upload a file

Download a file

Upload a directory

Using rsync

Register an SSH Key

Sync Keys to a Workspace

Managing SSH Keys

List your registered keys

List keys synced to a workspace

Remove a key

Turn off automatic setup

Troubleshooting

Could not resolve hostname

Connection refused

Permission denied

Host key warnings

Slow connection

API Reference