# SSH

URL: https://heaven.dev/docs/ssh
Updated: 2026-11-21

Heaven's SSH gateway accepts connections at `heaven.dev`. Connect as `cli` for management commands or as a Computer's name for its shell.

## Register your key

In the [dashboard](https://heaven.dev/dashboard), open **Settings → SSH & API keys → Add SSH key** and paste your public key.

To create a key, run this locally:

```sh
ssh-keygen -t ed25519
```

Register the resulting `.pub` file.

A key restricted to a Computer or tag can reach matching Computers but cannot run management commands. The [CLI](https://heaven.dev/docs/cli#open-a-shell) can register and use its own SSH key during sign-in.

## Verify the host key

On your first connection, compare OpenSSH's displayed fingerprint with:

```
SHA256:Fn7e9Zl5/ECAnFgRbuP5FImqXidjTsfu4Ydsc9i1Gfw
```

Accept it only if it matches. If a saved key changes unexpectedly, contact [support](https://heaven.dev/docs/support).

## Management commands

```sh
ssh cli@heaven.dev 'help'
ssh cli@heaven.dev 'view'
ssh cli@heaven.dev 'view my-site --json'
```

`help` lists commands. `view` lists accessible Computers; a name selects one Computer. `--json` returns the management response envelope.

See [All commands](https://heaven.dev/docs/reference/commands) for syntax and [Errors](https://heaven.dev/docs/reference/errors) for recovery. Accepted operations continue after SSH disconnects.

## Computer shells

Connect to a running Computer:

```sh
ssh my-site@heaven.dev
```

The shell runs as the [image's login user](https://heaven.dev/docs/computers#default-image). Use a [service or session manager](https://heaven.dev/docs/connecting#sessions) for work that must continue after you disconnect.

If Heaven's command help appears instead of a shell, check the Computer's name and your access. An inaccessible destination can fall back to management. Read a stopped or paused Computer with `ssh cli@heaven.dev 'view my-site'` before starting or resuming it.

## Remote SSH

Install Microsoft's **Remote - SSH** extension in VS Code or Anysphere's **Remote SSH** extension in Cursor. With your [SSH key registered](https://heaven.dev/docs/ssh#register-your-key), run **Remote-SSH: Connect to Host…** from the editor's Command Palette and enter `my-site@heaven.dev`.

[Verify the host key](https://heaven.dev/docs/ssh#verify-the-host-key) when prompted. The editor installs its server inside the Computer on the first connection. Open a folder there to edit its files and run terminals in the Computer.

## Guest commands

For noninteractive commands, batch mode and a separate connection refuse inaccessible destinations:

```sh
ssh -S none -o ControlMaster=no -o BatchMode=yes my-site@heaven.dev 'printf "%s\n" "$HOME"'
```

SSH returns the guest command's exit status. After a lost connection or status `255`, inspect the result before repeating a command with side effects.

## Port forwarding

Forward a local port to a database listening on `127.0.0.1:5432` inside `my-site`:

```sh
ssh -S none -o ControlMaster=no -o BatchMode=yes -N \
  -L 127.0.0.1:15432:127.0.0.1:5432 my-site@heaven.dev
```

Connect your local database client to `127.0.0.1:15432`. The listener is accessible only from your computer.

## File transfers

Copy a file from the Computer's login home, replacing the local destination:

```sh
scp my-site@heaven.dev:notes.txt ./notes-from-my-site.txt
```

For interactive transfers:

```sh
sftp my-site@heaven.dev
```

Use [Export a Computer](https://heaven.dev/docs/reference/exec/export) for a whole-disk image.
