/rho-cloud-onboard

name: rho-cloud-onboard
description: Register an agent email address on Rhobot Mail (name@rhobot.dev). Use when the user wants to set up agent email, register a Rhobot Mail account, claim an email handle, or onboard to rhobot.dev.
kind: sop

Rhobot Mail Onboarding

Register an agent email address on Rhobot Mail and configure local credentials. The agent gets an inbox at `name@rhobot.dev` that can be polled via API.

Parameters

• **handle** (required): The desired email local part (e.g. `tau` for `tau@rhobot.dev`)
• **display_name** (optional): Human-readable name for the agent

URLs

• **Landing page**: `https://rhobot.dev/email`
• **Skill reference**: `https://rhobot.dev/skill.md`
• **API endpoint**: `https://api.rhobot.dev` (all API calls go here)

Prerequisites

• `curl` and `jq` installed
• Internet access to `api.rhobot.dev`

Steps

1. Collect Handle

Ask the user what email handle they want. If not provided, suggest one based on the agent's name or personality.

**Constraints:**

• Handle MUST be 1-64 characters, lowercase alphanumeric and hyphens only
• Handle MUST NOT start or end with a hyphen
• Handle MUST NOT be a reserved name: `admin`, `postmaster`, `abuse`, `noreply`, `no-reply`, `support`, `help`, `info`, `security`, `webmaster`, `hostmaster`, `mailer-daemon`, `root`, `dmarc`
• You MUST validate the handle format locally before making the API call
• You MUST confirm the handle with the user before registering: "Register as `{handle}@rhobot.dev`?"

2. Check Existing Credentials

Before registering, check if credentials already exist.

cat ~/.config/rho-cloud/credentials.json 2>/dev/null

**Constraints:**

• If credentials exist and contain a valid `api_key`, MUST warn the user: "Existing credentials found for `{email}`. Registering again will create a new account. Continue?"
• If the user does not confirm, MUST stop
• You MUST NOT overwrite credentials without explicit confirmation

3. Register with API

Call the registration endpoint.

curl -s -X POST https://api.rhobot.dev/v1/register \
  -H "Content-Type: application/json" \
  -d '{"name": "{handle}", "display_name": "{display_name}"}' | jq .

**Constraints:**

• You MUST check the response `ok` field before proceeding
• You MUST handle these error cases:

| HTTP Status | Error | Action | |-------------|-------|--------| | 400 | Invalid name format | Show the validation rules. Ask user to pick a different handle. Return to Step 1. | | 409 | Handle already taken | Tell user `{handle}@rhobot.dev` is taken. Suggest alternatives: `{handle}-agent`, `{handle}-bot`, `{handle}-ai`, or ask user for another name. Return to Step 1. | | 500 | Server error | Report the error. Suggest retrying in a few minutes. | | Network error | Connection failed | Check internet. Suggest `curl -s https://api.rhobot.dev/v1/health | jq .` to verify the API is up. |

• You MUST NOT proceed if registration fails
• On 409 (taken), you MUST suggest at least 3 alternative handles

4. Save Credentials

On successful registration, save the credentials locally.

mkdir -p ~/.config/rho-cloud
cat > ~/.config/rho-cloud/credentials.json << 'EOF'
{
  "api_key": "{api_key from response}",
  "agent_id": "{agent_id from response}",
  "email": "{email from response}"
}
EOF
chmod 600 ~/.config/rho-cloud/credentials.json

**Constraints:**

• You MUST set file permissions to 600 (owner read/write only)
• You MUST verify the file was written by reading it back
• You MUST NOT log or display the full API key after saving. Show only the first 8 characters.

5. Verify Registration

Confirm the credentials work by hitting the health and status endpoints.

# Health check
curl -s https://api.rhobot.dev/v1/health | jq .

# Auth check
curl -s -H "Authorization: Bearer {api_key}" \
  https://api.rhobot.dev/v1/agents/status | jq .

**Constraints:**

• Health check MUST return `{"ok": true}`
• Status check MUST return the agent list with the registered email
• If status check returns 401, credentials are invalid. Report error and suggest re-registering.

6. Claim Your Agent

The registration response includes a `claim_url` for identity verification.

**Constraints:**

• You MUST show the claim URL to the user
• You SHOULD offer to open the claim URL on the device using the open-url skill or `termux-open-url`
• Claiming verifies ownership. Unclaimed agents cannot receive email and may be removed.
• You MUST strongly encourage the user to complete the claim flow immediately.

7. Report

Summarize what was set up.

**Report template:**

Registered: {handle}@rhobot.dev
Agent ID:   {agent_id}
Credentials: ~/.config/rho-cloud/credentials.json
Claim URL:  {claim_url}
Status:     {claimed or pending}

Send a test email to {handle}@rhobot.dev to verify delivery.
Use the rho-cloud-email skill to check your inbox.

Troubleshooting

| Problem | Solution | |---------|----------| | "already taken" on a handle you own | You may have registered previously. Check `~/.config/rho-cloud/credentials.json` for existing credentials. | | Health check fails | API may be down. Try again in a few minutes. Check `dig api.rhobot.dev` for DNS resolution. | | Auth check returns 401 | API key may be invalid or corrupted. Re-register with a new handle. | | Claim URL returns 404 | Claim token may have expired. Re-register to get a fresh claim URL. |