> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SSH

> SSH into a Linux computer with your key

A Linux computer can take a standard SSH connection: OpenSSH, an editor's remote mode, an agent app, or any tool that asks for a host, a port, a user and a key.

This is not the same as `orgo ssh` in the [CLI](https://docs.orgo.ai/guides/cli.md#ssh). `orgo ssh` opens a terminal over a WebSocket and needs no SSH key. Direct SSH, on this page, is a plain SSH server you connect to over TCP.

> [!NOTE]
>
> Direct SSH is for Linux computers. Mac, Windows, Android and iPhone computers don't have it.

## Turn it on

1. In the computer's **⋯** menu, choose **SSH**, or choose **Settings** and then **SSH**.
2. Paste your **public** key (the contents of a `.pub` file, for example `~/.ssh/id_ed25519.pub`). Never paste the private key.
3. Click **Enable SSH**.

The tab then shows the command to connect:

```bash theme={null}
ssh -p <port> root@<host>
```

Copy it as shown. The host is the address of the server your computer runs on, and the port is your computer's own.

> [!WARNING]
>
> Use the port the SSH tab shows. Port 22 on that address is not your computer.

If you see **Key saved. Restart to activate it.**, or the tab says **Restart this computer to activate SSH, then reopen this tab.**, restart the computer once (**Restart** in the computer's **⋯** menu), then reopen the SSH tab. The key is in place after the restart.

Don't have a key yet? The tab's **Find or create a key** section has the commands. You can also run:

```bash theme={null}
ssh-keygen -t ed25519
cat ~/.ssh/id_ed25519.pub
```

## Connect from another tool

Tools that ask for an SSH endpoint want these values:

| Field | Value |
| - | - |
| Host | The host in the SSH tab's command |
| Port | The port in the SSH tab's command |
| User | `root` |
| Authentication | Your private key |

## What to know

* **You log in as `root`, with your key.**
* **Accepted keys:** `ssh-ed25519`, `ssh-rsa`, `ecdsa-sha2-*` and the security key types `sk-ssh-ed25519@openssh.com` and `sk-ecdsa-sha2-*@openssh.com`. To allow more than one key, paste one key per line (16 KB at most).
* **Changing keys:** under **Manage access**, **Update key** replaces the keys on the computer with the ones you paste. If you're asked to restart, the old keys keep working until you do.
* **Turning it off:** under **Manage access**, **Disable SSH** removes your keys from the computer (`/root/.ssh/authorized_keys`, including any keys you added there yourself). Turning SSH back on means pasting the key again.
* **Who can turn it on:** the workspace owner and members who can edit. Can chat members and share link guests can't.
* **Keys on a computer that holds its own key.** A restricted key, or a key that expires, gets `403` with `code: "computer_key_held"` from the SSH endpoints there. Use a full access key that never expires, or sign in, as described in [Narrower keys on a computer with its own key](https://docs.orgo.ai/api-reference/api-keys/computer-keys.md#narrower-keys-on-a-computer-with-its-own-key).
* **Check the tab after a move.** If your computer moves to another server, its host and port can change. The SSH tab always shows the current command.
* **Asleep computers** don't take connections. SSH works again once the computer wakes.

## From the API

Everything in the SSH tab works with an API key, so a script or an agent can set up SSH on its own. The key needs the **Control** permission (read to get the settings, write to turn SSH on or off). A key limited to one computer can't use these endpoints.

| What | Endpoint | Reference |
| - | - | - |
| Add your public key and turn SSH on | `POST https://www.orgo.ai/api/computers/{id}/ssh` | [Turn on SSH](https://docs.orgo.ai/api-reference/computers/ssh-enable.md) |
| Get the host, port, user and command | `GET https://www.orgo.ai/api/computers/{id}/ssh` | [Get SSH settings](https://docs.orgo.ai/api-reference/computers/ssh-get.md) |
| Turn SSH off and remove the keys | `DELETE https://www.orgo.ai/api/computers/{id}/ssh` | [Turn off SSH](https://docs.orgo.ai/api-reference/computers/ssh-disable.md) |

**1. Add your public key.** Calling it again replaces the keys.

```bash theme={null}
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/ssh \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"public_key\": \"$(cat ~/.ssh/id_ed25519.pub)\"}"
```

If the answer has `"requires_restart": true`, restart the computer once. The key is in place after the restart.

**2. Get the command to connect.**

```bash theme={null}
curl https://www.orgo.ai/api/computers/$COMPUTER_ID/ssh \
  -H "Authorization: Bearer $ORGO_API_KEY"
```

Use `ssh_command` as it is, or `ipv4_host`, `ipv4_port` and `ssh_user` for a tool that asks for each one. Check that `enabled` is `true` first.

> [!WARNING]
>
> Connect on `ipv4_port`, never port 22. Port 22 on `ipv4_host` is the server your computer runs on, not your computer. Read the port from the API each time: it changes if the computer moves to another server.

## Troubleshooting

**`Permission denied (publickey)`**: open **Manage access** in the SSH tab, paste your public key again and click **Update key**. If you're asked to restart, restart once. Check that you connect with the matching private key (`ssh -i ~/.ssh/<key> -p <port> root@<host>`).

**`Connection refused` or a timeout**: make sure you use the port from the SSH tab, not 22, and that the computer is running.

**Still stuck?** Send us the output of `ssh -v -p <port> root@<host>` and we'll take a look.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.