skill
SSH Connection
UnreviewedSSH into Adom containers from other containers or from your desktop.
{
"schema_version": 1,
"type": "skill",
"slug": "ssh-connection",
"title": "SSH Connection",
"brief": "SSH into Adom containers from other containers or from your desktop.",
"version": "1.0.0",
"tags": [],
"license": "MIT",
"source_path": "SKILL.md",
"readme": "# SSH Connection Guide\n\nEnd-to-end guide for SSH access to Adom containers.\n\n## Architecture\n\nAll Adom containers are accessible via SSH through a centralized gateway:\n\n```\nYour Machine --SSH--> adom.cloud:22 --routes--> Target Container (sshd)\n (gateway)\n```\n\nThe gateway routes connections based on the SSH username, which encodes the container identity:\n\n```\nssh <owner>-<repo>-<slug>@adom.cloud\n```\n\nExample: `ssh [email protected]`\n\n## Prerequisites: SSH Keys\n\nSSH requires two things:\n1. A **private key** at `~/.ssh/id_ed25519` on the machine you're connecting FROM\n2. The matching **public key** registered with your Adom account\n\n**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.\n\n**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`.\n\n**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`.\n\n### Auto-detect and fix missing keys\n\nRun this to check and fix your SSH key setup:\n\n```bash\n# Check for local private key\nif [ ! -f ~/.ssh/id_ed25519 ]; then\n echo \"No SSH key found. Generating...\"\n ssh-keygen -t ed25519 -C \"adom\" -f ~/.ssh/id_ed25519 -N \"\"\n echo \"Key generated.\"\nelse\n echo \"SSH key exists at ~/.ssh/id_ed25519\"\nfi\n\n# Check if any keys are registered with Adom\nKEYS=$(adom-cli carbon user ssh-keys 2>/dev/null)\nif [ \"$KEYS\" = \"[]\" ]; then\n echo \"No keys registered with Adom. Registering...\"\n adom-cli carbon user ssh-key-add --display-name \"auto-generated\" \"$(cat ~/.ssh/id_ed25519.pub)\"\n echo \"Key registered.\"\nelse\n echo \"Keys registered with Adom:\"\n echo \"$KEYS\" | python3 -c \"import sys,json; [print(f' - {k[\\\"display_name\\\"]} ({k[\\\"fingerprint\\\"]})') for k in json.load(sys.stdin)]\"\nfi\n```\n\n### Verify local key matches a registered key\n\n```bash\n# Local key fingerprint\nssh-keygen -lf ~/.ssh/id_ed25519.pub\n\n# Registered key fingerprints\nadom-cli carbon user ssh-keys\n```\n\nIf the fingerprints don't match, register the local key:\n\n```bash\nadom-cli carbon user ssh-key-add --display-name \"My Container\" \"$(cat ~/.ssh/id_ed25519.pub)\"\n```\n\n## Finding Container SSH Credentials\n\n### List all your containers\n\n```bash\nadom-cli carbon containers list\n```\n\nEach container has an `ssh_credentials` field:\n\n```json\n{\n \"ssh_credentials\": {\n \"command\": \"ssh [email protected]\",\n \"hostname\": \"adom.cloud\",\n \"port\": 22,\n \"username\": \"john-service-wiki-abc123\"\n }\n}\n```\n\n### Get a specific container\n\n```bash\nadom-cli carbon containers get <slug>\n```\n\n### List containers for the current repo\n\n```bash\nadom-cli carbon containers list-for-repo\n```\n\n## Connecting\n\n### Interactive session\n\n```bash\nssh [email protected]\n```\n\nFor first connection (auto-accept host key):\n\n```bash\nssh -o StrictHostKeyChecking=accept-new [email protected]\n```\n\n### Run a one-off command\n\n```bash\nssh [email protected] \"ls -la /home/adom/\"\n```\n\n### Copy files (scp)\n\n```bash\n# Local to remote\nscp /path/to/file [email protected]:/home/adom/\n\n# Remote to local\nscp [email protected]:/home/adom/file /path/to/local/\n```\n\n### Port forwarding\n\nForward a remote port to your local machine:\n\n```bash\nssh -L 8080:localhost:8080 [email protected]\n```\n\nThen access `http://localhost:8080` locally.\n\n### SSH config for convenience\n\nAdd to `~/.ssh/config` for shorter commands:\n\n```\nHost wiki\n HostName adom.cloud\n User john-service-wiki-abc123\n IdentityFile ~/.ssh/id_ed25519\n```\n\nThen just: `ssh wiki`\n\n## Common Workflows\n\n### Check if a service is running on a remote container\n\n```bash\nssh [email protected] \"curl -sf http://127.0.0.1:8090/health\"\n```\n\n### Restart a service on a remote container\n\n```bash\nssh [email protected] \"pkill -f 'node server.js'; cd ~/service && nohup node server.js > /tmp/service.log 2>&1 &\"\n```\n\n### Pull latest code on a remote container\n\n```bash\nssh [email protected] \"cd ~/service && git pull origin main && npm install\"\n```\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| \"Permission denied (publickey)\" | No SSH key registered with Adom, or wrong key | Run the auto-detect script above |\n| \"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) |\n| \"Connection refused\" | Container not running or sshd not started | Check container status: `adom-cli carbon containers get <slug>` |\n| \"Connection timed out\" | Gateway unreachable or container provisioning | Wait 30-60s for new containers; check network |\n| Hangs after connecting | Key propagation delay after registration | Wait 30-60 seconds and retry |\n| \"Host key verification failed\" | Known hosts conflict from previous container | `ssh-keygen -R adom.cloud` and retry |\n| Works from one container but not another | Different keypair on the other container | Generate and register a key on that container too |\n\n## Desktop SSH\n\nTo 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.).",
"author": {
"id": "695820315b5f1e4db2fcf602",
"name": "Kyle Bergstedt",
"email": "[email protected]"
},
"visibility": {
"public": true
},
"hero": null,
"sample_prompts": [],
"discovery_triggers": [],
"discovery_pitch": null,
"metadata": {},
"created_at": "2026-05-28T05:29:53.302Z",
"updated_at": "2026-05-28T05:29:53.302Z",
"sub_skills": [],
"parent_app": null
}