# Desktop SSH Guide

Connect to your Adom containers from your personal computer via SSH.

## Overview

```
Your Desktop --SSH--> adom.cloud:22 --routes--> Adom Container
                      (gateway)
```

All you need:
1. The SSH keypair from your Adom container copied to your desktop
2. An SSH config entry for easy access

## Recommended: Claude Code Prompt (easiest)

Every Adom user has Claude Code. The fastest way to set up desktop SSH is to generate a prompt from inside your Adom container, then paste it into Claude Code on your desktop.

### Step 1: Generate the prompt (in your Adom container)

Run this in your Adom container's Claude Code to generate a ready-to-paste prompt:

```
Generate a Claude Code prompt I can paste on my desktop to set up SSH access to my Adom containers. Include:
1. My private key contents (from ~/.ssh/id_ed25519)
2. My public key contents (from ~/.ssh/id_ed25519.pub)
3. Instructions to save them as ~/.ssh/id_ed25519_adom on the desktop (use _adom suffix to avoid clobbering existing keys)
4. SSH config entries for my containers (get them from: adom-cli carbon containers list)
5. The icacls command to lock down permissions (Windows) or chmod 600 (Mac/Linux)
6. A test command to verify the connection
```

Claude will read your keys and container list, then produce a self-contained prompt.

### Step 2: Paste the prompt on your desktop

Open Claude Code (or any Claude interface) on your desktop machine and paste the generated prompt. Claude will:
1. Save the private key to `~/.ssh/id_ed25519_adom`
2. Save the public key to `~/.ssh/id_ed25519_adom.pub`
3. Set correct file permissions
4. Create SSH config entries for all your containers
5. Test the connection

That's it -- no manual file editing, no PuTTYgen, no confusion.

### Example generated prompt

The prompt Claude generates will look like this:

```
I need to set up SSH access to my Adom containers from this machine.

Save this private key to ~/.ssh/id_ed25519_adom:

-----BEGIN OPENSSH PRIVATE KEY-----
<key contents>
-----END OPENSSH PRIVATE KEY-----

Save this public key to ~/.ssh/id_ed25519_adom.pub:

ssh-ed25519 AAAA... adom-container

After saving both files, lock down permissions:
- Windows: icacls %USERPROFILE%\.ssh\id_ed25519_adom /inheritance:r /grant:r "%USERNAME%:(R)"
- Mac/Linux: chmod 600 ~/.ssh/id_ed25519_adom

Then create or append to ~/.ssh/config:

Host adom-myproject
    HostName adom.cloud
    User john-myproject-abc123
    IdentityFile ~/.ssh/id_ed25519_adom

Then test: ssh adom-myproject
```

---

## Alternative: Manual Setup

If you prefer to set things up manually without Claude Code on your desktop.

### Step 1: Get your keys from your Adom container

In your Adom container terminal:

```bash
cat ~/.ssh/id_ed25519      # Private key -- copy this
cat ~/.ssh/id_ed25519.pub  # Public key -- copy this
```

If no keys exist yet, generate and register them first:

```bash
ssh-keygen -t ed25519 -C "adom" -f ~/.ssh/id_ed25519 -N ""
adom-cli carbon user ssh-key-add --display-name "My Key" "$(cat ~/.ssh/id_ed25519.pub)"
```

### Step 2: Save keys on your desktop

Create these files on your desktop:
- `~/.ssh/id_ed25519_adom` -- paste the private key
- `~/.ssh/id_ed25519_adom.pub` -- paste the public key

Set permissions:

**macOS / Linux:**
```bash
chmod 600 ~/.ssh/id_ed25519_adom
chmod 644 ~/.ssh/id_ed25519_adom.pub
```

**Windows (PowerShell as Administrator):**
```powershell
icacls $env:USERPROFILE\.ssh\id_ed25519_adom /inheritance:r /grant:r "$env:USERNAME:(R)"
```

### Step 3: Find your container SSH usernames

In your Adom container:

```bash
adom-cli carbon containers list
```

Look for the `ssh_credentials.command` field for each container.

### Step 4: Configure SSH

Edit `~/.ssh/config` (macOS/Linux) or `%USERPROFILE%\.ssh\config` (Windows):

```
Host adom-myproject
    HostName adom.cloud
    User john-myproject-abc123
    IdentityFile ~/.ssh/id_ed25519_adom
```

Add one `Host` block per container you want quick access to.

### Step 5: Connect

```bash
ssh adom-myproject
```

---

## Alternative: Generate fresh keys on your desktop

If you prefer not to copy keys from your container, generate new ones on your desktop and register them with Adom.

### macOS / Linux

```bash
ssh-keygen -t ed25519 -C "my-desktop" -f ~/.ssh/id_ed25519_adom
```

### Windows (OpenSSH -- built into Windows 10/11)

```powershell
ssh-keygen -t ed25519 -C "my-desktop" -f $env:USERPROFILE\.ssh\id_ed25519_adom
```

### Windows (PuTTY)

1. Open **PuTTYgen**
2. Select **EdDSA** (Ed25519) at the bottom
3. Click **Generate** and move the mouse
4. Click **Save private key** as a `.ppk` file
5. Copy the public key text from the top box

### Register with Adom

Give the public key to Claude Code in your Adom container:

```
Register this SSH public key with my Adom account:
ssh-ed25519 AAAA... my-desktop
```

Claude will run:
```bash
adom-cli carbon user ssh-key-add --display-name "My Desktop" "ssh-ed25519 AAAA..."
```

---

## PuTTY Users

If you use PuTTY instead of OpenSSH on Windows:

1. **Convert the key:** Open PuTTYgen > File > Load > select your `id_ed25519_adom` file > Save private key as `.ppk`
2. **Configure PuTTY:**
   - Session: Host Name = `adom.cloud`, Port = `22`
   - Connection > Data: Auto-login username = `john-myproject-abc123`
   - Connection > SSH > Auth > Credentials: Browse to your `.ppk` file
   - Session: Save as "Adom MyProject"
3. **Connect:** Double-click the saved session

---

## VS Code Remote SSH

You can edit files on Adom containers directly from VS Code:

1. Install the **Remote - SSH** extension
2. `Ctrl+Shift+P` > "Remote-SSH: Connect to Host"
3. Select from your SSH config or enter `john-myproject-abc123@adom.cloud`

---

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| "Permission denied (publickey)" | Key not registered with Adom, or wrong key file on desktop |
| "Connection timed out" | Firewall may be blocking port 22 outbound |
| PuTTY "server refused our key" | Convert to `.ppk` with PuTTYgen |
| "Host key verification failed" | `ssh-keygen -R adom.cloud` and retry |
| Works from container but not desktop | Different keypair -- copy keys from container or register desktop key |
| "Connection refused" | Container may not be running -- check on https://hydrogen.adom.inc |
| Windows: "ssh is not recognized" | Settings > Apps > Optional Features > Add "OpenSSH Client" |