---
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.

```bash
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):

```bash
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:

```bash
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:

```json
{
  "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

```bash
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):**
```json
{
  "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).

```bash
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):**
```json
{
  "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".

```bash
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):**
```json
{"success": true, "message": "Project created successfully", "details": {"username": "john", "projectName": "kicad-cli"}}
```

### Step 2: Create the container

```bash
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):**
```json
{
  "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

```bash
# 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:**
```json
{
  "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

```bash
# 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

```bash
# 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

```bash
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

```bash
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:
```bash
ls /home/adom/.ssh/id_ed25519 2>/dev/null
```

If missing, generate one:
```bash
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

```bash
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 |