SSH Connection Guide

End-to-end guide for SSH access to Adom containers.

Architecture

All Adom containers are accessible via SSH through a centralized gateway:

Your Machine --SSH--> adom.cloud:22 --routes--> Target Container (sshd)
                      (gateway)

The gateway routes connections based on the SSH username, which encodes the container identity:

ssh <owner>-<repo>-<slug>@adom.cloud

Example: ssh [email protected]

Prerequisites: SSH Keys

SSH requires two things:

1. A private key at ~/.ssh/id_ed25519 on the machine you're connecting FROM
2. The matching public key registered with your Adom account

One key works for all containers. Authentication happens at the adom.cloud gateway (jumphost) against your Adom account's registered keys -- not per-container. You do not need separate keys for each container.

Note: Containers must have been created with the --ssh flag to be reachable via the gateway. Older containers created without --ssh may return "Could not connect to your container" and need to be recreated with --ssh.

Important: ssh-key-add is additive — it adds a new key alongside existing ones. It does NOT replace or remove existing keys. You can safely register a desktop key without breaking container-to-container SSH. Verify registered keys with adom-cli carbon user ssh-keys.

Auto-detect and fix missing keys

Run this to check and fix your SSH key setup:

# Check for local private key
if [ ! -f ~/.ssh/id_ed25519 ]; then
  echo "No SSH key found. Generating..."
  ssh-keygen -t ed25519 -C "adom" -f ~/.ssh/id_ed25519 -N ""
  echo "Key generated."
else
  echo "SSH key exists at ~/.ssh/id_ed25519"
fi

# Check if any keys are registered with Adom
KEYS=$(adom-cli carbon user ssh-keys 2>/dev/null)
if [ "$KEYS" = "[]" ]; then
  echo "No keys registered with Adom. Registering..."
  adom-cli carbon user ssh-key-add --display-name "auto-generated" "$(cat ~/.ssh/id_ed25519.pub)"
  echo "Key registered."
else
  echo "Keys registered with Adom:"
  echo "$KEYS" | python3 -c "import sys,json; [print(f'  - {k[\"display_name\"]} ({k[\"fingerprint\"]})') for k in json.load(sys.stdin)]"
fi

Verify local key matches a registered key

# Local key fingerprint
ssh-keygen -lf ~/.ssh/id_ed25519.pub

# Registered key fingerprints
adom-cli carbon user ssh-keys

If the fingerprints don't match, register the local key:

adom-cli carbon user ssh-key-add --display-name "My Container" "$(cat ~/.ssh/id_ed25519.pub)"

Finding Container SSH Credentials

List all your containers

adom-cli carbon containers list

Each container has an ssh_credentials field:

{
  "ssh_credentials": {
    "command": "ssh [email protected]",
    "hostname": "adom.cloud",
    "port": 22,
    "username": "john-service-wiki-abc123"
  }
}

Get a specific container

adom-cli carbon containers get <slug>

List containers for the current repo

adom-cli carbon containers list-for-repo

Connecting

Interactive session

ssh [email protected]

For first connection (auto-accept host key):

ssh -o StrictHostKeyChecking=accept-new [email protected]

Run a one-off command

ssh [email protected] "ls -la /home/adom/"

Copy files (scp)

# Local to remote
scp /path/to/file [email protected]:/home/adom/

# Remote to local
scp [email protected]:/home/adom/file /path/to/local/

Port forwarding

Forward a remote port to your local machine:

ssh -L 8080:localhost:8080 [email protected]

Then access http://localhost:8080 locally.

SSH config for convenience

Add to ~/.ssh/config for shorter commands:

Host wiki
    HostName adom.cloud
    User john-service-wiki-abc123
    IdentityFile ~/.ssh/id_ed25519

Then just: ssh wiki

Common Workflows

Check if a service is running on a remote container

ssh [email protected] "curl -sf http://127.0.0.1:8090/health"

Restart a service on a remote container

ssh [email protected] "pkill -f 'node server.js'; cd ~/service && nohup node server.js > /tmp/service.log 2>&1 &"

Pull latest code on a remote container

ssh [email protected] "cd ~/service && git pull origin main && npm install"

Troubleshooting

Symptom	Cause	Fix
"Permission denied (publickey)"	No SSH key registered with Adom, or wrong key	Run the auto-detect script above
"Could not connect to your container"	Container was created without --ssh flag, or is a legacy container without SSH provisioning	Create a new container with --ssh: adom-cli carbon containers create --ssh ... (legacy containers cannot be upgraded -- see note below)
"Connection refused"	Container not running or sshd not started	Check container status: adom-cli carbon containers get <slug>
"Connection timed out"	Gateway unreachable or container provisioning	Wait 30-60s for new containers; check network
Hangs after connecting	Key propagation delay after registration	Wait 30-60 seconds and retry
"Host key verification failed"	Known hosts conflict from previous container	ssh-keygen -R adom.cloud and retry
Works from one container but not another	Different keypair on the other container	Generate and register a key on that container too

Desktop SSH

To SSH from your Windows, Mac, or Linux desktop, see the Desktop SSH Guide (desktop-ssh skill) which covers key generation on your local machine, SSH config setup, and platform-specific instructions (OpenSSH, PuTTY, etc.).