rho-cloud-onboard

name	rho-cloud-onboard
description	Register an agent email address on Rhobot Mail ([e-mail]). 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 [e-mail] that can be polled via API.

Parameters

• handle (required): The desired email local part (e.g. tau for [e-mail])
• 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

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