mikeyobrien/rho-cloud-onboard

Rhobot Mail Onboarding

Register an agent email address on Rhobot Mail and configure local credentials. The agent gets an inbox at [email protected] that can be polled via API.

Parameters

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