> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt

# Connect with SSH

Last updated 3 November 2026

> Machines are not open yet. These pages describe Machines as they will open; until then, a create answers [`region_not_offered`](https://tonbo.dev/docs/machines/troubleshooting/manage.md#region_not_offered) (422), “Machines are not offered in any region yet.”

Open a terminal in a Machine with `ssh`, copy files with `sftp`, or connect an editor that works over SSH, with a short-lived certificate Tonbo signs for your key. There are no keys to register and none to remove.

> Planned Not served yet. This page describes how it will work, as decided; until it is served, the certificate requests answer 404 at `https://api.tonbo.dev/v1`, and Machines take no SSH login. The [Machines API reference](https://tonbo.dev/docs/reference/management/machines.md) lists each operation, marked Planned.

## Connect

```shell
# A key for Tonbo, once
ssh-keygen -t ed25519 -f ~/.ssh/tonbo -N ""

# A certificate for it, valid 12 hours by default
curl -sS https://api.tonbo.dev/v1/ssh/certificates \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"public_key\": \"$(cat ~/.ssh/tonbo.pub)\"}" \
  | jq -r .data.certificate > ~/.ssh/tonbo-cert.pub

# Trust Tonbo's host keys, once
curl -sS https://api.tonbo.dev/v1/ssh/host-ca -H "Authorization: Bearer $TONBO_API_KEY" >> ~/.ssh/known_hosts

# Connect
ssh -i ~/.ssh/tonbo hello.<account>@tonbo.sh
```

The user is the Machine’s name and your account’s name, and the host is the same for every region. A login wakes an asleep Machine, with the same checks and credit as any wake, and runs as the image’s user.

## Certificates

- A certificate names one account and is valid for `ttl_seconds`: 12 hours by default, from 5 minutes to 24 hours, and never past the expiry of the token that asked for it. It needs a key that is not narrowed.
- Keys are ssh-ed25519 or ecdsa-sha2-nistp256; any other type answers 422 `certificate_key_unsupported`.
- `GET /v1/ssh/certificates` lists your live ones, and `DELETE /v1/ssh/certificates/<id>` revokes one; owners and admins may list and revoke anyone’s. Revoking the key that asked for a certificate revokes it too. Logins stop within 60 seconds of a revocation.
- The host lines name the current host key and the next, so a rotation never breaks your `known_hosts`.

## What a session can do

- A shell, a terminal, a command, sftp, and remote forwarding (-R).
- Local forwarding (-L) to a port on the Machine’s own loopback only. Dynamic forwarding (-D), agent forwarding and X11 are off, so a Machine never becomes a proxy.
- Jump hosts (ProxyJump) work.
- Typing keeps the Machine awake; a session left idle closes when the Machine would sleep.

## Every login after a sleep starts fresh

Each wake starts the Machine from its image, so a home directory outside the Volume is new at every login after a sleep, and so is anything you installed there. Keep work on the Volume, and state in the [database](https://tonbo.dev/docs/machines/database.md) (see [What lasts](https://tonbo.dev/docs/machines/files.md#lasts)).

## Who sees the session

Tonbo’s edge ends the SSH connection and opens one to the Machine, so it handles your session in the clear, as it handles a request to a private port over HTTPS (see [Isolation guarantees](https://tonbo.dev/docs/machines/guarantees/isolation.md)).