Skip to main content

​
SSH Access

Every Rigbox workspace is a full Linux VM with SSH access. Connect from any terminal to get a shell or transfer files.

​
Prerequisites

Before connecting via SSH, you need:
  1. An SSH key pair on your local machine (e.g., ~/.ssh/id_ed25519)
  2. A Rigbox account with an API key
  3. At least one running workspace
If you don’t have an SSH key yet, generate one: 
ssh-keygen -t ed25519 -C "your-email@example.com"

​
Register an SSH Key

To connect via SSH, you first need to register your public key with Rigbox.

​
Via the API

curl -X POST https://api.rigbox.dev/api/ssh-keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "laptop",
    "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... your-email@example.com"
  }'

​
Via the CLI

If you have the Rigbox CLI installed: 
rig ssh-key add laptop
This reads your default public key (~/.ssh/id_ed25519.pub) and registers it automatically.
You can register multiple SSH keys for different machines — for example, one for your laptop and one for your desktop. Give each a descriptive name so you can identify them later.

​
Sync Keys to a Workspace

When you create a workspace, your registered SSH keys are typically synced automatically. If you add a new key while a workspace is already running, sync it manually: 
curl -X POST https://api.rigbox.dev/api/workspaces/{workspace_id}/ssh-keys/sync \
  -H "Authorization: Bearer YOUR_API_KEY"
This copies all your registered public keys into the workspace VM’s ~/.ssh/authorized_keys file.
Keys are synced automatically on workspace start for most templates. You only need the sync endpoint if you add a key to an already-running workspace.

​
Connect to a Workspace

When you create a workspace, Rigbox gives you an SSH command in this format: 
ssh {workspace-name}-{workspace-id}@{region}.rigbox.dev
For example, if your workspace is named my-project with ID ws-ctbxi8lb in the eu-west-1 region: 
ssh my-project-ctbxi8lb@eu-west-1.rigbox.dev
The SSH server identifies you by your registered key and routes the connection directly to your workspace VM.
The SSH command is shown in the dashboard when you create a workspace. You can also construct it from the workspace name, ID (strip the ws- prefix), and region.

​
Region-direct vs gateway routing

There are two ways to connect:
MethodExampleLatency
Region-directssh user@eu-west-1.rigbox.devLowest — connects directly to the compute node in your workspace’s region
Gatewayssh user@rigbox.devHigher — routes through the central gateway, which forwards to the correct region
Use the region-specific hostname (e.g., eu-west-1.rigbox.dev) for the best experience. The gateway hostname (rigbox.dev) works from anywhere but adds latency proportional to the distance between the gateway and your workspace’s region.
The region is part of the SSH command shown in the dashboard. As Rigbox expands to more regions, your workspace will always include the correct region hostname.

​
Specify an identity file

If your key is not in the default location, specify it explicitly: 
ssh -i ~/.ssh/my_rigbox_key my-project-ctbxi8lb@eu-west-1.rigbox.dev

​
SSH config shortcut

Add this to your ~/.ssh/config for easier access: 
Host my-project
  HostName eu-west-1.rigbox.dev
  User my-project-ctbxi8lb
  IdentityFile ~/.ssh/id_ed25519
Then connect with: 
ssh my-project

​
File Transfer

Use scp to transfer files between your local machine and a workspace.

​
Upload a file

scp ./local-file.txt my-project-ctbxi8lb@eu-west-1.rigbox.dev:/home/developer/

​
Download a file

scp my-project-ctbxi8lb@eu-west-1.rigbox.dev:/home/developer/output.txt ./

​
Upload a directory

scp -r ./my-project my-project-ctbxi8lb@eu-west-1.rigbox.dev:/home/developer/

​
Using rsync

For larger transfers or syncing directories, rsync is more efficient: 
rsync -avz ./my-project/ my-project-ctbxi8lb@eu-west-1.rigbox.dev:/home/developer/my-project/

​
Managing SSH Keys

​
List your registered keys

curl https://api.rigbox.dev/api/ssh-keys \
  -H "Authorization: Bearer YOUR_API_KEY"

​
List keys synced to a workspace

curl https://api.rigbox.dev/api/workspaces/{workspace_id}/ssh-keys \
  -H "Authorization: Bearer YOUR_API_KEY"
This returns the keys currently in the workspace’s authorized_keys file.

​
Remove a key

curl -X DELETE https://api.rigbox.dev/api/ssh-keys/{key_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
Removing a key from the API does not immediately remove it from running workspaces. The key will be removed the next time the workspace restarts or you manually trigger a sync.

​
Troubleshooting

​
Connection refused

If you get Connection refused, verify:
  1. Your workspace is running (check with GET /api/workspaces/{id} or rig ls)
  2. Your SSH key is registered and synced
  3. You’re using the correct username format: {workspace-name}-{id}@{region}.rigbox.dev

​
Permission denied

If you get Permission denied (publickey):
  1. Check that your key is registered: GET /api/ssh-keys
  2. Sync keys to the workspace: POST /api/workspaces/{id}/ssh-keys/sync
  3. Verify you are using the correct identity file: ssh -v my-project-ctbxi8lb@{region}.rigbox.dev

​
Slow connection

If connections feel slow:
  1. Check your network connection
  2. Try connecting with -o ServerAliveInterval=60 to prevent timeouts
  3. For file transfers, prefer rsync over scp for large datasets

​
API Reference