skill

Repo Management

Unreviewed

by Kyle Bergstedt

Create, list, and delete repos and workspaces on the Adom platform via the Carbon API.

Overview Files Versions Dependencies Discussions Activity
skill / adom-repo-management
!

Not installable via adompkg

This skill has no published release. adompkg install kyle/adom-repo-management will not work until a maintainer publishes a tarball with install.sh and uninstall.sh.

See the publishing docs for the package.json schema and tarball layout required to ship this skill.

name: adom-repo-management
description: Use when the user wants to create, list, or delete Adom repos and workspaces, provision containers, or manage projects on hydrogen.adom.inc. Triggers on "create repo", "new adom repo", "create workspace", "provision container", "delete repo", "list repos", "list workspaces".

Adom Repo & Workspace Management

Create, list, and delete repos and workspaces on the Adom platform via the Carbon API.

Authentication

All Carbon and Hydrogen API calls require a session_token cookie. Every Adom container has an API key that works as a session token — always check for it first before asking the user for credentials.

Step 1: Use the container API key (preferred)

Every Adom container has a pre-provisioned API key at /var/run/adom/api-key. This key works as a session_token cookie for both Carbon and Hydrogen APIs.

API_KEY=$(cat /var/run/adom/api-key)

# Use as session_token cookie for any API call:
curl -s -X POST 'https://carbon.adom.inc/user/repos' \
  -b "session_token=$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-repo","description":"...","private":false}'

Important: Never echo or display the API key. Store it in a shell variable only.

Step 2: Check for cached session (fallback)

If /var/run/adom/api-key doesn't exist (rare — only outside Adom containers):

cat /home/adom/.config/adom-session.json 2>/dev/null

If the file exists and created_at is within 30 days, use the stored session_token.

Step 3: Login (last resort)

Only if neither the API key file nor a cached session exists, ask the user for credentials:

curl -s -X POST 'https://carbon.adom.inc/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{"email":"USERNAME","password":"PASSWORD"}' \
  -c /tmp/adom-login-cookies \
  -D /tmp/adom-login-headers

Extract the session_token from the Set-Cookie header and save it:

{
  "session_token": "TOKEN_VALUE",
  "carbon_api": "https://carbon.adom.inc",
  "hydrogen_api": "https://hydrogen.adom.inc",
  "username": "USERNAME",
  "created_at": "YYYY-MM-DD",
  "expires_in_days": 30
}

Write to /home/adom/.config/adom-session.json.

Create a Repo

SESSION=$(cat /home/adom/.config/adom-session.json | python3 -c "import sys,json;print(json.load(sys.stdin)['session_token'])")

# User-owned repo (RECOMMENDED — container shows up on repo homepage)
curl -s -X POST 'https://carbon.adom.inc/user/repos' \
  -b "session_token=$SESSION" \
  -H 'Content-Type: application/json' \
  -d '{"name":"REPO_NAME","description":"DESCRIPTION","private":false}'

# Org-owned repo (container won't show on repo homepage — see note below)
curl -s -X POST 'https://carbon.adom.inc/orgs/adom/repos' \
  -b "session_token=$SESSION" \
  -H 'Content-Type: application/json' \
  -d '{"name":"REPO_NAME","description":"DESCRIPTION","private":false}'

Always prefer user-owned repos (POST /user/repos). The Hydrogen repo page looks for a container matching {owner}-{repo}. Containers are always created under a user (e.g., john), not an org. So org-owned repos (e.g., adom/kicad-cli) can never show their container on the repo homepage because the container is john-kicad-cli-* but the page looks for adom-kicad-cli. User-owned repos (e.g., john/kicad-cli) don't have this mismatch.

Response (200):

{
  "id": "REPO_ID",
  "name": "REPO_NAME",
  "full_name": "adom/REPO_NAME",
  "git_remote": "ssh://[email protected]:/REPO_ID.git",
  "created_at": "..."
}

Errors:

  • 409: REPO_ALREADY_EXISTS
  • 401: Session expired — re-login
  • 422: Missing required fields

Create a Workspace (Hydrogen layout — NOT the Docker container)

Important: A "workspace" in the Carbon API is the Hydrogen panel layout (what tabs/panels are shown). It does NOT provision a Docker container. Container provisioning is separate (see next section).

curl -s -X POST 'https://carbon.adom.inc/workspaces' \
  -b "session_token=$SESSION" \
  -H 'Content-Type: application/json' \
  -d '{
    "repo_id": "REPO_ID",
    "name": "WORKSPACE_NAME",
    "owner": {
      "owner_type": "repository",
      "id": "REPO_ID"
    },
    "workspace_data": {
      "focusedPanelId": "main",
      "meta": { "name": "WORKSPACE_NAME" },
      "root": {
        "type": "leaf",
        "id": "main",
        "panelType": "adom/a1b2c3d4-eeee-4000-a000-00000000000e",
        "activeTabIndex": 0,
        "tabs": [{
          "id": "tab-vscode",
          "panelType": "adom/a1b2c3d4-eeee-4000-a000-00000000000e"
        }]
      }
    }
  }'

Field reference:

  • repo_id: The repo's id from creation
  • name: Alphanumeric + hyphens only (no underscores, no spaces)
  • owner.owner_type: Always "repository"
  • owner.id: Same as repo_id
  • workspace_data.root: Panel layout tree. The example above creates a single VS Code panel
  • panelType: adom/a1b2c3d4-eeee-4000-a000-00000000000e = VS Code editor

Response (200):

{
  "id": "WORKSPACE_ID",
  "name": "WORKSPACE_NAME",
  "owner": { "type": "repository", "id": "REPO_ID" },
  "workspace_data": { ... },
  "created_at": "..."
}

Create a Dev Container (provisions Docker container)

After creating a repo, you need to provision its Docker container. This requires two steps via the Hydrogen API (not Carbon), and is separate from creating a workspace.

Step 1: Initialize the Curium project

This creates the git project on the Coder side. Must be done before container creation or you get "Failed to perform recursive copy".

curl -s -X POST 'https://hydrogen.adom.inc/api/curium/create-project' \
  -b "session_token=$SESSION" \
  -H 'Content-Type: application/json' \
  -d '{"username":"USERNAME","projectName":"REPO_NAME"}'
  • username: The user who will own the container (must be a valid Coder user, e.g., john)
  • projectName: The repo name (e.g., kicad-cli)

Response (200):

{"success": true, "message": "Project created successfully", "details": {"username": "john", "projectName": "kicad-cli"}}

Step 2: Create the container

curl -s -X POST 'https://hydrogen.adom.inc/api/containers/create' \
  -b "session_token=$SESSION" \
  -H 'Content-Type: application/json' \
  -d '{"owner":"USERNAME","repository":"REPO_NAME","actor":"USERNAME"}'
  • owner: Must match the username from Step 1 — the Coder user who will own the container
  • repository: The repo name (must match projectName from Step 1)
  • actor: Same as owner — the user performing the action

Important: owner and actor should both be the user's username (e.g., john), NOT the org name (e.g., adom), even for org-owned repos. The Coder platform associates containers with users, not orgs. Using the org name as owner causes "Failed to fetch user: 404".

Response (201):

{
  "id": "john-kicad-cli-ba3ddf337bb1d9a6",
  "owner": "john",
  "repository": "kicad-cli",
  "unique_hash": "ba3ddf337bb1d9a6",
  "services": {
    "coder_url": "https://coder.john-kicad-cli-ba3ddf337bb1d9a6.containers.adom.inc/",
    "s3_url": "https://s3.john-kicad-cli-ba3ddf337bb1d9a6.containers.adom.inc/",
    "ssh_credentials": { "hostname": "ssh.containers.adom.localhost", "port": 2222, "username": "john-kicad-cli-ba3ddf337bb1d9a6" }
  }
}

Check container status

# Get a specific container (ID format: {owner}-{repo})
curl -s 'https://hydrogen.adom.inc/api/containers/get/{owner}-{repo}' \
  -b "session_token=$SESSION"

# List all containers
curl -s 'https://hydrogen.adom.inc/api/curium-proxy/containers' \
  -b "session_token=$SESSION"

Container response:

{
  "id": "john-my-repo-d4d7f7f287915e49",
  "owner": "john",
  "repository": "my-repo",
  "unique_hash": "d4d7f7f287915e49",
  "status": "running",
  "services": {
    "coder_url": "https://coder.john-my-repo-d4d7f7f287915e49.containers.adom.inc/",
    "s3_url": "https://s3.john-my-repo-d4d7f7f287915e49.containers.adom.inc/",
    "ssh_credentials": {
      "hostname": "ssh.containers.adom.localhost",
      "port": 2222,
      "username": "john-my-repo-d4d7f7f287915e49"
    }
  }
}

Container URL pattern:
https://coder.{owner}-{repo}-{hash}.containers.adom.inc/

The hash is assigned by the platform. Check the container status via API or the Hydrogen UI at https://hydrogen.adom.inc/{owner}/{repo} to find the full URL.

List Repos

# All org repos
curl -s -b "session_token=$SESSION" 'https://carbon.adom.inc/orgs/adom/repos' | python3 -m json.tool

# User repos (replace USERNAME with the actual username from adom-session.json)
curl -s -b "session_token=$SESSION" 'https://carbon.adom.inc/users/USERNAME/repos' | python3 -m json.tool

# All public repos
curl -s 'https://carbon.adom.inc/repos' | python3 -m json.tool

List Workspaces

# For a specific repo
curl -s -b "session_token=$SESSION" 'https://carbon.adom.inc/repos/{owner}/{name}/workspaces'

# Workspace detail
curl -s -b "session_token=$SESSION" 'https://carbon.adom.inc/workspaces/{WORKSPACE_ID}'

Delete Repo

curl -s -X DELETE "https://carbon.adom.inc/repos/{owner}/{name}" \
  -b "session_token=$SESSION"

Returns 202 Accepted. This is destructive and irreversible — always confirm with the user first.

Delete Workspace

curl -s -X DELETE "https://carbon.adom.inc/workspaces/{WORKSPACE_ID}" \
  -b "session_token=$SESSION"

Returns 204 No Content.

Push Code to a Repo

SSH key setup (one-time)

Check for existing key:

ls /home/adom/.ssh/id_ed25519 2>/dev/null

If missing, generate one:

ssh-keygen -t ed25519 -N "" -f /home/adom/.ssh/id_ed25519
ssh-keyscan git.adom.inc >> /home/adom/.ssh/known_hosts 2>/dev/null

The public key (/home/adom/.ssh/id_ed25519.pub) must be registered with the Adom platform. There is no API endpoint for this yet — tell the user to add it via the Hydrogen UI at Settings > SSH Keys, or ask them to paste the public key for manual setup.

Push

cd /path/to/service
git init
git remote add origin ssh://[email protected]:/REPO_ID.git
git add .
git commit -m "Initial commit"
git push -u origin main

Full Workflow Example

To create a new project with a Docker container:

  1. Create repo: POST /user/repos with name and description (user-owned so container shows on repo page)
  2. Init Curium project: POST /api/curium/create-project with {username: "YOUR_USERNAME", projectName: "REPO_NAME"} — initializes git on Coder
  3. Create container: POST /api/containers/create with {owner: "YOUR_USERNAME", repository: "REPO_NAME", actor: "YOUR_USERNAME"} — provisions Docker container. Response includes coder_url
  4. (Optional) Create workspace: POST /workspaces with repo_id and layout — defines Hydrogen panel layout
  5. Open in Hydrogen: Navigate to https://hydrogen.adom.inc/{username}/{repo-name} or directly to the coder_url from step 3
  6. Bootstrap: In the new container's terminal (or via a Claude Code prompt), install dependencies and start services
  7. (Optional) Set up SSH & push code: If you need to push code from another container, generate SSH key, register via Hydrogen UI, then git push

Troubleshooting

Symptom Cause Fix
401 Unauthorized on any API call Session token expired (30-day TTL) Delete /home/adom/.config/adom-session.json and re-login
409 on repo creation Repo name already exists in the org Choose a different name or delete the existing repo first
WORKSPACE_NAME_INVALID on workspace creation Name contains underscores, spaces, or special characters Use only alphanumeric characters and hyphens
git push rejected with "Permission denied (publickey)" SSH key not registered with the platform Add the public key via Hydrogen UI at Settings > SSH Keys
"No Container" shown on repo page Container not provisioned yet Run the 2-step container creation: first POST /api/curium/create-project, then POST /api/containers/create
Failed to fetch user: 404 on container create owner is an org name instead of a username Use the user's username as owner (e.g., john), not the org name (e.g., adom). Coder users are per-user, not per-org
Failed to perform recursive copy on container create Curium project not initialized Run POST /api/curium/create-project with {username, projectName} before creating the container
missing field errors on workspace creation workspace_data schema is strict Ensure all required fields are present: focusedPanelId, meta.name, root.type, root.id, root.panelType, root.activeTabIndex, root.tabs

API Reference

Carbon API (carbon.adom.inc)

Endpoint Method Auth Purpose
/auth/login POST None Login → session cookie
/user/repos POST Cookie Create user-owned repo (recommended)
/orgs/{org}/repos POST Cookie Create org-owned repo (container won't show on repo page)
/orgs/{org}/repos GET Public Org repos
/repos/{owner}/{name} GET Public Repo details
/repos/{owner}/{name} DELETE Cookie Delete repo
/repos/{owner}/{name}/workspaces GET Public List workspaces
/repos GET Public List all repos
/users/{name}/repos GET Public User repos
/workspaces POST Cookie Create workspace (Hydrogen layout)
/workspaces/{id} GET Cookie Workspace detail
/workspaces/{id} DELETE Cookie Delete workspace
/user GET Cookie Current user profile

Hydrogen API (hydrogen.adom.inc)

Endpoint Method Auth Purpose
/api/curium/create-project POST Cookie Initialize Curium project (body: {username, projectName}) — must call before container create
/api/containers/create POST Cookie Create dev container (body: {owner, repository, actor}) — owner/actor = username, not org
/api/containers/get/{owner}-{repo} GET Cookie Get container status/URL
/api/curium-proxy/containers GET Cookie List all containers