SSH Into Your Sandbox

The mental model: it's the AWS PEM flow

If you've ever launched an EC2 instance and SSH'd in, you already know everything you need. Sandbox Platform uses the same mechanics:

The dashboard generates an ed25519 key pair on our server. We keep the public half and bake it into your sandbox's ~/.ssh/authorized_keys when the VM boots. We give you the private half once as a downloadable .pem file, then forget it. Save the .pem, run ssh, you're in.

Quickstart: 5 clicks and you're in

chmod 600 ~/Downloads/MacBook.pem

ssh -i ~/Downloads/MacBook.pem ec2-user@<sandbox-ip>

First time only, SSH asks if you trust the host fingerprint. Type yes and press Enter. You're in.

Usernames: ec2-user vs ubuntu vs root

Sandboxes use Amazon Linux 2 by default. The right username depends on the image:

If you get Please login as the user "ec2-user" rather than the user "root", the server is telling you which user to use. Re-run with that one.

Why is opening port 22 safe?

Sandbox public IPs are reachable from anywhere on the internet. That sounds scary — "the SSH port is open to the world!" — until you remember that SSH passwords are off. The only way in is with the matching private key.

This is the same posture used by:

• GitHub.com when you git clone git@github.com:... — their 22 is open globally; the keys are the auth.
• Every AWS EC2 quickstart tutorial — default Lightsail / EC2 SGs open 22 to the world; the .pem is the auth.
• DigitalOcean droplets, Linode, Vultr, Hetzner — same model.

The cryptographic boundary (your key) is enforced at the SSH layer; the network boundary (a public port) is incidental. We tested this explicitly: anonymous and wrong-key SSH attempts are rejected at the auth layer with Permission denied (publickey), not at the connection layer.

How it actually works (under the hood)

If you're curious what's happening when you click Generate:

1. The dashboard calls POST /api/ssh-keys/generate on Sandbox Platform.
2. Our backend asks the resource service to generate an ed25519 key pair. The private half is returned once, in PEM format. We never persist it — it goes straight to your browser as a download.
3. The public half is recorded in our database, scoped to your user and current organization.
4. When you create a sandbox, our backend looks up your public keys for the current org and passes them in the EC2 launch request as metadata.ssh_authorized_keys.
5. cloud-init on the EC2 reads that metadata, writes your public key to /home/ec2-user/.ssh/authorized_keys, sets correct permissions, and starts sshd.
6. You SSH in. sshd challenges you with a public-key auth handshake. Your .pem signs the response. sshd verifies against authorized_keys and lets you in.

Multiple keys (laptop + work + CI)

Each key is independent. You can have a key per machine you SSH from:

• MacBook — for your laptop
• WorkLinux — for your office workstation
• CI — for an automated pipeline

All of them get baked into every new sandbox you create. Delete one and it's removed from future sandbox launches; existing sandboxes keep working until you destroy them.

Already have a key? Upload your public key instead

If you already have an SSH key on your laptop (e.g. ~/.ssh/id_ed25519), you don't need a new one. Upload the public half and SSH with the private half you already have:

# If you don't have a key yet, generate one:
ssh-keygen -t ed25519 -C "your-email@example.com"

# Copy the public key to your clipboard:
cat ~/.ssh/id_ed25519.pub | pbcopy   # macOS
cat ~/.ssh/id_ed25519.pub | xclip    # Linux

In the dashboard, click Add Key → Upload Existing Key, paste the public key, give it a name, click Upload. Now SSH in without the -i flag — your local SSH agent finds the matching private key automatically:

ssh ec2-user@<sandbox-ip>

Power-user alternative: short-lived certificates

The .pem flow is simple and matches what most people already know. There's a second path that some teams prefer: OpenSSH certificates. Instead of a long-lived .pem on disk, the dashboard issues a 10-minute cert against an in-VM CA. The cert is signed, time-bounded, and never written to your filesystem unless you choose to.

You'd reach for this if:

• You don't want any long-lived private key material on your laptop.
• You want auditable, time-bounded SSH access (the cert expires; no manual revocation needed).
• You want to grant temporary access to a teammate without sharing a .pem.

The flow is in the dashboard's Ephemeral SSH Certificate panel. Paste your local public key, pick a TTL (60–1800 seconds), get back a cert, then ssh -i your_key -o CertificateFile=fresh_cert ec2-user@<ip>. Re-issue when the cert expires.

Troubleshooting

Permission denied (publickey)

The most common SSH failure. Means the key isn't being accepted. Check:

• Wrong username. Default is ec2-user for Amazon Linux. Try ubuntu on Ubuntu images.
• Wrong PEM file. Verify with ssh-keygen -lf MacBook.pem — the fingerprint should match what the dashboard shows for that key.
• Key not baked in. If you generated the key after the sandbox launched, it isn't in authorized_keys. Generate the key first, then create the sandbox. (Or use the cert flow.)
• You're in the wrong workspace. Keys are scoped to your current org. Switch back to the workspace where the key lives.

Connection timed out

SSH never reaches the server. The sshd never sees you. Check:

• Sandbox isn't running yet. Status must be running with a real public IP (not pending). Refresh the dashboard.
• Your network blocks outbound TCP/22. Some corporate / coffee-shop networks restrict SSH. Try a hotspot or VPN.
• cloud-init still running. First-boot scripts can take 60–90 seconds. If the IP is up but SSH refuses, wait another minute.

Bad permissions on the .pem

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@         WARNING: UNPROTECTED PRIVATE KEY FILE!          @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

Fix: chmod 600 your-key.pem

I deleted the key — can I get it back?

No. The private key was returned to your browser exactly once at generation time and was never persisted on our side. If you lost the .pem, generate a new key. Existing sandboxes still authorize the old key until you destroy them, so you can either keep the old sandboxes accessible via the still-valid old key (if you have it) or recreate them with the new key.

Multiple sandboxes — do I need a key per sandbox?

No. One key works for every sandbox in your workspace. The same public key is baked into every new sandbox at launch.

Doing it from the API

Everything in the dashboard is a thin wrapper over a public API. If you're scripting:

export SANDBOX_API_KEY="ab0t_sk_live_..."
export SANDBOX_URL="https://sandbox.dev.ab0t.com"

# 1. Generate a key pair (returns the PEM exactly once)
curl -sS -X POST "$SANDBOX_URL/api/ssh-keys/generate" \
  -H "Authorization: Bearer $SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-laptop","key_type":"ed25519"}' \
  | jq -r .private_key_pem > ~/Downloads/my-laptop.pem
chmod 600 ~/Downloads/my-laptop.pem

# 2. Create a sandbox
SBX=$(curl -sS -X POST "$SANDBOX_URL/api/sandboxes" \
  -H "Authorization: Bearer $SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"demo","instance_type":"ab0t.micro"}')
SID=$(echo "$SBX" | jq -r .sandbox_id)

# 3. Wait for RUNNING and grab the IP
while :; do
  STATUS=$(curl -sS "$SANDBOX_URL/api/sandboxes/$SID" \
    -H "Authorization: Bearer $SANDBOX_API_KEY")
  STATE=$(echo "$STATUS" | jq -r .status)
  IP=$(echo "$STATUS" | jq -r .instance_ip)
  [ "$STATE" = "running" ] && break
  sleep 5
done

# 4. SSH in
ssh -i ~/Downloads/my-laptop.pem ec2-user@$IP

Full API reference at /documentation#api-ssh.

What's next

You can SSH in. What you do once you're there is up to you: