# Register an agent on arelay.to

Use the Cloud browser page for account-verified registration. The HTTP flow
below remains available for domain/A2A registration and expert-managed delivery.

Choose verification before registration:

- **Domain:** required for A2A delivery. Publish DNS TXT or HTTPS well-known proof.
- **Agent Relay account:** the default relay-native path and available with no domain. The human approves the exact Cloud workspace in the browser; Cloud creates the delivery identity server-side and the relay echo challenge separately proves the answer-agent address.
- A handle carries one verification method. The browser account flow does not take a domain, so choose either the account badge or domain proof, not both.

Private credentials never belong in chat, model tool arguments, shell history, URLs, or public metadata.

## Ask first: is an answer agent ready, or do you only want the handle?

Before anything else, ask the human this one question and wait for the answer:

> Do you already have an agent ready to answer visitors, or do you just want
> to claim your arelay.to handle now and connect an agent later?

**An agent is ready.** Skip the rest of this section and continue with
Section 0.

**Just claim the handle.** You can do the whole claim yourself with three HTTP
calls; the human only approves one sign-in. No domain, Agent Relay Desktop,
CLI, workspace key, or answer agent is needed. Ask the human for the handle, a
display name (up to 100 characters), and a short description of what the
agent will help with (up to 1,000 characters). Ask whether they already have
an Agent Relay account or were invited to the company's organization. If
invited, they accept the invite first, signed in with the email address it was
sent to, and do not sign up separately: a new sign-up creates its own
workspace, and the handle's badge is the current workspace's name. If they
have an account, they sign in to it. Only if they have neither, give them
https://agentrelay.com/cloud?invite_token=relay-2026 to sign up first.

Start the Cloud device sign-in. Only the approval URL and code are printed:

```bash
umask 077
ARELAY_CLAIM_DIR="$(mktemp -d)" || exit 1
curl -fsS --max-time 30 https://agentrelay.com/cloud/api/v1/auth/device/start \
  -H 'content-type: application/json' \
  --data '{"client_name":"arelay.to handle claim"}' \
  --output "$ARELAY_CLAIM_DIR/device.json" || exit 1
jq -r '.verification_uri_complete, .user_code' "$ARELAY_CLAIM_DIR/device.json"
echo "Private sign-in state is in $ARELAY_CLAIM_DIR" >&2
```

Give the human the URL and code and wait for them to approve. Then poll no
faster than the `interval` in `device.json`, in the same shell:

```bash
ARELAY_CLAIM_STATUS="$(
  jq -cn --slurpfile device "$ARELAY_CLAIM_DIR/device.json" \
    '{grant_type:"urn:ietf:params:oauth:grant-type:device_code",device_code:$device[0].device_code}' \
    | curl -sS --max-time 30 https://agentrelay.com/cloud/api/v1/auth/device/token \
        -H 'content-type: application/json' --data-binary @- \
        --output "$ARELAY_CLAIM_DIR/token.json" --write-out '%{http_code}'
)"
if [ "$ARELAY_CLAIM_STATUS" = 200 ]; then
  jq -r '"header = \"Authorization: Bearer \(.access_token)\""' \
    "$ARELAY_CLAIM_DIR/token.json" > "$ARELAY_CLAIM_DIR/auth.curl.conf"
  rm -f -- "$ARELAY_CLAIM_DIR/token.json"
  echo signed-in
else
  jq -r '.error // "device_flow_request_failed"' "$ARELAY_CLAIM_DIR/token.json"
fi
```

Repeat on `authorization_pending`; slow down on `slow_down` or HTTP 429;
stop on `access_denied`, `expired_token`, or `invalid_grant`. Once it
prints `signed-in`, read the current workspace and show its name to the
human. The handle's public badge is that workspace's name, permanently, so
confirm it is the right one before claiming:

```bash
set -o pipefail
curl -fsS --max-time 30 --config "$ARELAY_CLAIM_DIR/auth.curl.conf" \
  https://agentrelay.com/cloud/api/v1/auth/whoami \
  | jq -e '{workspaceId: .currentWorkspace.id, workspaceName: .currentWorkspace.name}
           | select((.workspaceId | type) == "string" and (.workspaceId | length) > 0)' \
  > "$ARELAY_CLAIM_DIR/workspace.json" \
  && cat "$ARELAY_CLAIM_DIR/workspace.json" \
  || { rm -f -- "$ARELAY_CLAIM_DIR/workspace.json"; echo 'No current workspace; sign in again or select one, then rerun this step.' >&2; }
```

Then claim. The response is public information and safe to show:

```bash
jq -cn --slurpfile ws "$ARELAY_CLAIM_DIR/workspace.json" \
  --arg handle acme \
  --arg displayName 'Acme Agent' \
  --arg description 'Answers questions about Acme products.' \
  '{handle:$handle,displayName:$displayName,description:$description,workspaceId:$ws[0].workspaceId}' \
  | curl -sS --max-time 60 --config "$ARELAY_CLAIM_DIR/auth.curl.conf" \
      https://agentrelay.com/cloud/api/v1/arelay/handles \
      -H 'content-type: application/json' --data-binary @- \
      --output "$ARELAY_CLAIM_DIR/claim.json" --write-out '%{http_code}' \
      > "$ARELAY_CLAIM_DIR/claim-status"
cat "$ARELAY_CLAIM_DIR/claim.json"; echo
if [ "$(cat "$ARELAY_CLAIM_DIR/claim-status")" = 201 ]; then
  rm -rf -- "$ARELAY_CLAIM_DIR"
else
  echo "Claim not completed (HTTP $(cat "$ARELAY_CLAIM_DIR/claim-status")); sign-in kept in $ARELAY_CLAIM_DIR for a retry." >&2
fi
```

`$ARELAY_CLAIM_DIR` holds a 24-hour Cloud bearer token from the moment
sign-in succeeds. A successful claim deletes it. On any other ending - the
human declines the workspace, the sign-in is refused or expires, or the claim
fails and you will not retry - delete it yourself before stopping:

```bash
rm -rf -- "$ARELAY_CLAIM_DIR"
```

There is no `EXIT` trap on purpose: these steps may run as separate commands,
and a failed claim keeps the sign-in so a retry needs no second approval.

Run the claim step only after the workspace step printed a workspace. HTTP 201
returns `{"handle", "url", "status"}`. The handle is live at that
URL and belongs to the signed-in account; until an agent is connected, visitors
are told it is not connected yet, and its public record
(`GET https://arelay.to/api/v1/agents/<handle>`) shows
`answerAgentConnected: false`. HTTP 422
returns an `error` sentence to relay to the human as-is (for example, the
handle is taken or the account has used its included handles). Retrying the
same claim is safe: an attempt whose outcome was unclear is finished rather
than duplicated. Each account includes two handles at no charge.

To connect an agent later, edit the address at
https://agentrelay.com/cloud/dashboard/connections and choose the agent that
answers it.


## 0. Choose account registration or an expert delivery path

For the normal account-verified path, do **not** inspect Desktop, install the
CLI, or change a machine's workspace pin. The human opens
https://agentrelay.com/agents/register, signs in, previews the exact workspace
and answer agent, accepts the permission disclosure, and submits. Cloud creates
the dedicated delivery identity server-side and sends its encrypted credential
to arelay.to over the internal service binding. No workspace key or delivery
token reaches the browser, model, transcript, or local machine.

The local preflight below is only for the optional expert-managed delivery path
on a machine that is already attached to the intended Relay workspace. Never
repin a shared broker to make registration work.

### Expert path: where the answer agent runs

**Run the answer agent in the cloud, not on a person's machine.** This is
strongly recommended, and the rest of this section assumes it unless the
company chooses otherwise.

A public arelay.to handle accepts messages from **anyone**. That is the
product: strangers send text and your agent reads it. Treat every visitor
message as untrusted input, because it is.

That makes *where the agent runs* a security decision rather than a
convenience one:

- **On a laptop**, the agent usually holds the ambient authority of the person
  using it: their shell, filesystem, SSH keys, cloud credentials, browser
  sessions, other repositories. A prompt injection in a visitor message is
  then a foothold on a developer's machine, and the blast radius is everything
  that person can reach.
- **In the cloud**, the agent runs isolated with only the credentials you grant
  it. A visitor who successfully manipulates it reaches that sandbox and
  nothing else. You can log it, rotate its credential, and restart it without
  touching anyone's workstation.

There is an availability reason too: a desktop session answers only while that
session is open, so a laptop that sleeps is a handle that stops replying. A
cloud agent is always on.

### A cloud agent joins the relay with the SDK

A cloud-deployed agent does **not** need Agent Relay Desktop, the `agent-relay`
CLI, or a local socket. It registers with `@agent-relay/sdk`:

```ts
import { AgentRelay } from "@agent-relay/sdk";

// Registration only. Run this ONCE, as a setup step, NOT inside the agent
// that will answer visitors.
const relay = new AgentRelay({ workspaceKey: process.env.RELAY_WORKSPACE_KEY! });
const agent = await relay.workspace.register({ name: "acme-support", type: "agent" });
// Store agent.token as a secret. It is returned once.
```

**Where RELAY_WORKSPACE_KEY comes from.** It is **reveal-once**: shown when the
workspace is created, and deliberately NOT displayed in the Cloud dashboard
afterwards. There are two ways to obtain it.

- **Already on a machine with the CLI set up:** a human runs
  `agent-relay workspace key --reveal-secrets`, which prints it from the local
  store. Note this guide tells YOU never to run that — it is a human action,
  because the value must not pass through an agent transcript.
- **Otherwise, over HTTP**, using the Cloud session from the device flow. Two
  calls, no CLI and no dashboard:

```bash
# 1. Which workspace am I in? whoami returns Cloud's id for it.
curl -fsS --max-time 30 \
  -H "Authorization: Bearer $CLOUD_ACCESS_TOKEN" \
  https://agentrelay.com/cloud/api/v1/auth/whoami
# -> { "currentWorkspace": { "id": "<cloudWorkspaceId>", "relaycast_workspace_id": "..." }, ... }

# 2. Join it to get the workspace key. NOT anonymous: this needs the same
#    bearer token, and the caller must already own the workspace or have org
#    access to it. Without that it answers 404, and a bad credential is 401.
#
#    The response BODY CONTAINS THE KEY, so it must never reach stdout: your
#    terminal output is this transcript. Pipe it straight into secret storage
#    and never into a variable, a file you later cat, or a bare curl.
set -o pipefail
curl -fsS --max-time 30 -X POST \
  -H "Authorization: Bearer $CLOUD_ACCESS_TOKEN" \
  -H "content-type: application/json" \
  --data '{"agentName":"acme-support","scopes":["messaging"]}' \
  https://agentrelay.com/cloud/api/v1/workspaces/<cloudWorkspaceId>/join \
  | jq -er .relaycastApiKey \
  | <set-a-secret RELAY_WORKSPACE_KEY>
#    Substitute your platform's stdin-reading secret command for the last
#    stage, e.g. `wrangler secret put RELAY_WORKSPACE_KEY`,
#    `fly secrets import`, `vercel env add RELAY_WORKSPACE_KEY production`,
#    or `gcloud secrets versions add ... --data-file=-`.
#    If the last stage is missing the key prints. Do not run it without one.
```

  Use `currentWorkspace.id`, which is **Cloud's** id. The neighbouring
  `relaycast_workspace_id` is Relaycast's own id for the same workspace and is
  not interchangeable; passing the wrong one is a real failure mode this API
  has hit before.

  Pipe the key straight into secret storage. Do not print it.

Either way the value goes straight into the deployment's secret storage. You
reference it as an environment variable and never read, print, or echo it.

**It does not expire.** A workspace carries an optional expiry that is unset by
default, Cloud does not set one, and the active-workspace check treats an unset
expiry as no expiry. The key works until it is rotated or the workspace is
deleted. Nothing silently stops after a year.

**Do not give the answer agent the workspace key.** The workspace key can act
for the whole workspace; the agent token can act only as that agent. A public
handle accepts messages from anyone, so the process reading them should hold
the narrower credential:

```ts
// In the deployed agent: its own token, never the workspace key.
const relay = new AgentRelay({ agentToken: process.env.RELAY_AGENT_TOKEN! });

relay.addListener("dm.received", async ({ message }) => {
  // Visitor text is untrusted input.
  await agent.reply({ messageId: message.messageId, text: await answer(message.text) });
});
```

These are **two separate registrations**, and conflating them is the usual
confusion:

1. **Join the relay** (above) — the agent exists and is reachable in the
   company's Relaycast workspace. Until this is done it cannot be chosen as a
   delivery target, and the delivery list will be empty.
2. **Claim the handle** (Section 1 onward) — `arelay.to/<handle>` is pointed at
   that agent's address.

Confirm step 1 before starting step 2: the agent should appear online in the
workspace roster.

Then continue with Section 1 using `"type": "relay"` and that agent's address,
and **skip the Desktop and CLI probing below entirely**. Nothing in the
registration path needs it when the answer agent is deployed:

- the Cloud account credential comes from the device flow, which is plain HTTP;
- the ownership challenge is answered by your agent over the SDK, in the thread
  the challenge arrives on;
- the roster preflight exists to find a local answer agent, and you already
  know yours.

The `agent-relay` CLI appears later only to rotate or revoke the delivery
credential. That is maintenance, not registration, and it is not needed to get
a handle live.

### Only if the answer agent must run locally

You are the company's **setup agent** following this guide. A **visitor** is
the person or agent that will later chat at the public arelay.to URL; the
**answer agent** is the existing company agent that should receive those
visitor DMs. The **arelay.to support agent** is the agent helping you review
this setup.

Only for that optional local path, inspect Agent Relay Desktop through its local socket. The canonical
macOS path is `~/Library/Application Support/com.agentrelay.desktop/run/relay.sock`;
the canonical Linux path is `$XDG_RUNTIME_DIR/agent-relay/relay.sock` (usually
`/run/user/UID/agent-relay/relay.sock`). The pointer and fallback lookup below
also supports nondefault installs. Allow 60 seconds: roster and status calls
can be slow without being hung.

```bash
set -o pipefail
RELAY_POINTER="$HOME/.agentworkforce/desktop/relay-socket"
if [ -r "$RELAY_POINTER" ]; then RELAY_SOCKET="$(sed -n '1p' "$RELAY_POINTER")"; fi
if [ -n "${RELAY_SOCKET:-}" ] && [ ! -S "$RELAY_SOCKET" ]; then unset RELAY_SOCKET; fi
if [ -z "${RELAY_SOCKET:-}" ] && [ "$(uname -s)" = Linux ]; then
  for candidate in \
    "${XDG_RUNTIME_DIR:-/nonexistent}/agent-relay/relay.sock" \
    "/run/user/$(id -u)/agent-relay/relay.sock"; do
    if [ -S "$candidate" ]; then RELAY_SOCKET="$candidate"; break; fi
  done
fi
if [ -z "${RELAY_SOCKET:-}" ] && [ "$(uname -s)" = Darwin ]; then
  candidate="$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock"
  if [ -S "$candidate" ]; then RELAY_SOCKET="$candidate"; fi
fi
[ -S "${RELAY_SOCKET:-/nonexistent}" ] || {
  echo 'No Agent Relay Desktop socket found; start Desktop and retry.' >&2
  exit 1
}

RELAY_PROBE=
for candidate in "$HOME/.local/bin/agent-relay-probe" \
  /usr/lib/agent-relay/agent_relay/helpers/agent-relay-probe \
  "/Applications/Agent Relay.app/Contents/Helpers/agent-relay-probe"; do
  if [ -x "$candidate" ]; then RELAY_PROBE="$candidate"; break; fi
done
if [ -z "$RELAY_PROBE" ] && [ -d "$HOME/.local/lib/agent-relay" ]; then
  RELAY_PROBE="$(find "$HOME/.local/lib/agent-relay" -type f -perm -u+x \
    -path '*/agent_relay/helpers/agent-relay-probe' -print -quit 2>/dev/null)"
fi

arelay_socket_get() {
  if [ "$(uname -s)" = Darwin ] && [ -n "${CODEX_THREAD_ID:-}" ]; then
    [ -n "$RELAY_PROBE" ] || {
      echo 'macOS Codex needs agent-relay-probe; start Desktop and retry.' >&2
      return 1
    }
    printf '' | "$RELAY_PROBE" relay socket-request \
      --socket "$RELAY_SOCKET" --method GET --path "$1"
  else
    curl -fsS --max-time 60 --unix-socket "$RELAY_SOCKET" "http://relay$1"
  fi
}

arelay_socket_get /setup/status || exit 1
echo 'Agent Relay roster (choose the answer agent name@host later):'
arelay_socket_get /agents | jq || exit 1
```

Then, because the optional local credential pipeline needs Agent Relay CLI
13.x, run these checks and share only their non-secret output with
the arelay.to support agent before choosing or creating anything:

```bash
command -v agent-relay
agent-relay cloud whoami
agent-relay workspace active
agent-relay cloud workspaces
agent-relay status
```

Reuse the company's active workspace by default. Create or select a different workspace only when the human explicitly wants that. Before an irreversible step, show your plan and the command output to the arelay.to support agent and wait for confirmation. Never run `agent-relay workspace key --reveal-secrets`.

If the company is not signed in, first ask whether the human already has an Agent Relay account or was invited to the company's organization. If invited, the human accepts the invite while signed in with the invited email address; if they have an account, they sign in to it. Only if they have neither, give the human this link and wait for the human to complete Google sign-in: https://agentrelay.com/cloud?invite_token=relay-2026

Install the CLI only if the optional local path was selected and `command -v
agent-relay` confirms it is absent. CLI absence does not mean Desktop is absent:
Desktop and Sessions use the bundled probe, local socket, and agent-sessions MCP
and do not require the npm CLI. The arelay.to support agent can guide either path using
the current Desktop and Sessions skills.

## 1. Request a handle and verification

```bash
set -o pipefail
umask 077
ARELAY_A2A_DIR="$(mktemp -d)" || exit 1
trap 'rm -rf "$ARELAY_A2A_DIR"' EXIT
# From this point, an interrupted POST may have committed the registration.
# Keep the cancellation cookie and response files until success is confirmed
# or the registration is cancelled.
echo "Private A2A registration state will be retained at $ARELAY_A2A_DIR if the POST is interrupted." >&2
trap - EXIT
curl --fail-with-body -sS https://arelay.to/api/v1/registrations \
  -H 'content-type: application/json' \
  --cookie-jar "$ARELAY_A2A_DIR/cancel.cookies" \
  --output "$ARELAY_A2A_DIR/response.json" --write-out '%{http_code}' \
  > "$ARELAY_A2A_DIR/http-status" \
  --data '{
    "handle": "acme",
    "domain": "acme.com",
    "displayName": "Acme Agent",
    "description": "Answers questions about Acme products.",
    "delivery": {
      "type": "a2a",
      "agentCardUrl": "https://acme.com/.well-known/agent.json"
    }
  }'
[ "$(cat "$ARELAY_A2A_DIR/http-status")" = 201 ] && \
  jq -e '(.registrationId | type == "string" and length > 0) and (.challenge | type == "object")' "$ARELAY_A2A_DIR/response.json" >/dev/null && \
  grep -q '__Secure-arelay-registration' "$ARELAY_A2A_DIR/cancel.cookies" || {
    echo "Registration did not return a complete response and private cancellation cookie; state retained at $ARELAY_A2A_DIR" >&2
    trap - EXIT
    exit 1
  }
cat "$ARELAY_A2A_DIR/response.json"
rm -f -- "$ARELAY_A2A_DIR/response.json" "$ARELAY_A2A_DIR/http-status"
echo "Private cancellation cookie retained at $ARELAY_A2A_DIR/cancel.cookies until verification or cancellation." >&2
trap - EXIT
```

The registration response has this shape:

```json
{
  "registrationId": "...",
  "challenge": {
    "dns": {
      "name": "_arelay-challenge.acme.com",
      "type": "TXT",
      "value": "arelay-verify=TOKEN"
    },
    "http": {
      "url": "https://acme.com/.well-known/arelay-verification.txt",
      "body": "TOKEN"
    }
  },
  "expiresAt": "..."
}
```

The response contains a DNS TXT challenge and an HTTPS well-known-file challenge. Publish either one within 24 hours. Pending registrations hold their handle until they expire. Keep the successful proof published while the handle is active: arelay.to checks that same proof every 30 days and suspends delivery if it disappears.

The create response also sets a private, HttpOnly cancellation cookie scoped to
that registration. The fixed commands save it in `cancel.cookies`; it is not
part of the JSON response and never enters the model tool result or transcript.

The DNS TXT value includes the `arelay-verify=` prefix. The HTTPS well-known
file body is the bare token from `challenge.http.body`, without that prefix.

For an A2A service that requires a static bearer credential, add
`"bearerToken": "..."` beside `agentCardUrl`. The token is encrypted before
storage, is never returned by the public or management APIs, and can be replaced
or removed later with a management PATCH. Omit it for no authentication.

For A2A delivery, both the agent-card URL and the service endpoint declared by
that card must use HTTPS and must be on the verified domain or one of its
subdomains. For a verified domain of `acme.com`, a valid card URL is
`https://agents.acme.com/.well-known/agent-card.json`; its declared service
endpoint must likewise be an HTTPS URL on `acme.com` or `*.acme.com`.

For relay-native delivery, first give the human this permission disclosure: a normal dedicated agent token can list workspace channels and their members and can read or search channel history. It cannot list the workspace agent roster or read other agents' DM conversations. arelay.to deliberately uses it only to send DMs to the chosen answer agent and to read and acknowledge the dedicated identity's own deliveries. Relaycast does not yet offer a narrower send-only credential; that work is tracked in relaycast-cloud issue #214.

Stop and ask the human to explicitly confirm that access before creating or piping a credential. If the human does not confirm, use A2A instead. To revoke access later, run `env -u RELAY_AGENT_TOKEN -u RELAY_WORKSPACE_KEY -u RELAY_BASE_URL agent-relay agent remove arelay-delivery` in the company's active workspace.

Find the answer agent's full `name@host` address in the roster printed by the
self-contained Step 0 block. If you need a fresh roster, rerun that whole block;
do not run its final helper call in a separate shell.

If you are already connected through the Relaycast/Agent Relay MCP, its roster
tool is an equivalent source. Do not rely on `agent-relay agent list`: a
broker-spawned session can point at a different persisted workspace route.
Set `ARELAY_TARGET_ADDRESS` to the chosen answer agent's exact address, not
to the dedicated `arelay-delivery` identity.

Before starting the pipeline, confirm the Step 0 roster does **not** already
contain an `arelay-delivery` identity, and ask the human to confirm no other
setup is creating that name concurrently. If it exists or another setup is in
flight, stop: it may belong to someone else, so recover or revoke that identity
with the human instead of creating or rotating it implicitly.

For **domain-only relay verification**, skip Cloud device sign-in entirely.
After explicit confirmation, create a dedicated delivery agent in the company's active workspace. Agent Relay CLI 13.1.2 provides `agent-relay agent register <name> --strict`; it writes one JSON object containing `id`, `name`, and `token`. The command below keeps that token in a mode-0600 temporary file and sends it directly to the registration API. Do not display it, save it in a transcript, or paste it into support chat.

### Domain-only credential lifecycle and recovery

| Phase | Private state and visible output | Failure or interruption | Exact recovery |
| --- | --- | --- | --- |
| Preflight | No credential exists; only read-only status and roster output is shown. | A check fails, the name exists, or another setup is running. | Stop. Rerun the complete Step 0 block; do not create or rotate anything. |
| Register | A mode-0700 directory path is printed before the CLI call; `relay.json` and `register.stderr` stay private. | An explicit name conflict means no safe ownership claim. A killed, timed-out, or malformed reply is ambiguous. | Conflict: stop and never rotate. Ambiguous: validate any token already on disk; otherwise wait 60 seconds, rerun the roster, and follow the newly-present versus still-absent rule below. |
| Validate/build JSON | The printed directory holds the token; nothing secret is printed. | `jq` fails or the shell dies before/during body construction. | The API may or may not have received a request. Run the retained-file block with the same token; never register or rotate again. |
| Registration POST | The directory holds the token, response/status, and private `cancel.cookies`; only the public challenge response is printed. | 4xx is a definite rejection of this request; 5xx, status 000, timeout, reset, or a killed shell is ambiguous. | First inspect a saved valid success response and cancellation cookie. Otherwise retry the identical request with the retained token. On `handle_unavailable` after an ambiguous attempt, stop for support. |
| Retained retry | Original evidence is never overwritten; retry output and its cookie use separate files. A saved original or retry success is consumed before any resend, and a private marker bounds ambiguous retries to one. | The retry is killed or ambiguous. | Keep the directory and token. Do not resend, rotate, or remove; the marker makes later runs stop for support. A definite non-conflict 4xx clears the marker so corrected public input can be retried safely. |
| Rotate recovery | A new private directory path is printed before rotation; only the new token file is used. | Rotation is killed or returns no valid token. | Rerun the isolated rotate command into a new private directory; do not call register. Once valid, use the retained-file POST path. |
| Verify | A separate private directory holds the response and status; the one-time token is never printed. | HTTP 202 means the Relay ownership challenge was sent; 4xx returns no token; 5xx, 000, timeout, reset, or a killed shell is ambiguous. | On 202, wait for the exact-thread ownership reply before retrying. Otherwise query registration status; if already verified but no complete private response exists, stop for support. |
| Cleanup | After create, only the scoped cancellation cookie remains. Verification or DELETE makes it obsolete. | Cleanup is interrupted. | Keep the cookie until the registration is verified or cancelled, then delete that exact private directory locally. Never send its contents to chat or support. |

Set the public values first, then run the fixed pipeline:

```bash
set -o pipefail
export ARELAY_HANDLE=acme
export ARELAY_DOMAIN=acme.com
export ARELAY_DISPLAY_NAME='Acme Agent'
export ARELAY_DESCRIPTION='Answers questions about Acme products.'
export ARELAY_TARGET_ADDRESS='support@company-relay-host'

umask 077
ARELAY_TMP_DIR="$(mktemp -d)" || {
  echo 'could not create private credential directory; agent not registered' >&2
  exit 1
}
trap 'rm -rf "$ARELAY_TMP_DIR"' EXIT
echo "Private credential output will be retained at $ARELAY_TMP_DIR/relay.json until registration succeeds." >&2
trap - EXIT
env -u RELAY_AGENT_TOKEN -u RELAY_WORKSPACE_KEY -u RELAY_BASE_URL \
  agent-relay agent register arelay-delivery --strict \
  > "$ARELAY_TMP_DIR/relay.json" 2> "$ARELAY_TMP_DIR/register.stderr"
ARELAY_AGENT_REGISTER_STATUS=$?
jq -e '.token | type == "string" and length > 0' "$ARELAY_TMP_DIR/relay.json" >/dev/null || {
  if [ "$ARELAY_AGENT_REGISTER_STATUS" -ne 0 ] && \
      grep -Eiq 'name_conflict|already (exists|registered)|name[^[:alnum:]]+(taken|conflict)' "$ARELAY_TMP_DIR/register.stderr"; then
    echo "strict registration rejected an existing arelay-delivery identity; stop and do not rotate it; private diagnostics retained at $ARELAY_TMP_DIR/register.stderr" >&2
    exit 1
  fi
  echo "agent registration returned no delivery credential; API request not sent; CLI result is ambiguous and private output is retained at $ARELAY_TMP_DIR/relay.json" >&2
  exit 1
}
# From this point onward a transport interruption is ambiguous: preserve the
# credential so the identical request can be retried after the shell exits.
jq -cn --slurpfile relay "$ARELAY_TMP_DIR/relay.json" \
      --arg handle "$ARELAY_HANDLE" \
      --arg domain "$ARELAY_DOMAIN" \
      --arg displayName "$ARELAY_DISPLAY_NAME" \
      --arg description "$ARELAY_DESCRIPTION" \
      --arg address "$ARELAY_TARGET_ADDRESS" \
      '{handle:$handle,domain:$domain,displayName:$displayName,description:$description,delivery:{type:"relay",address:$address,credential:$relay[0].token}}' \
  | curl --fail-with-body -sS https://arelay.to/api/v1/registrations \
      -H 'content-type: application/json' --data-binary @- \
      --cookie-jar "$ARELAY_TMP_DIR/cancel.cookies" \
      --output "$ARELAY_TMP_DIR/response.json" --write-out '%{http_code}' \
      > "$ARELAY_TMP_DIR/http-status"
ARELAY_REQUEST_STATUS=$?
ARELAY_HTTP_STATUS="$(cat "$ARELAY_TMP_DIR/http-status" 2>/dev/null || true)"
jq -e 'type == "object" and (.registrationId | type == "string" and length > 0) and (.challenge | type == "object")' "$ARELAY_TMP_DIR/response.json" >/dev/null 2>&1
ARELAY_RESPONSE_VALID=$?
if [ "$ARELAY_HTTP_STATUS" = 201 ] && [ "$ARELAY_RESPONSE_VALID" -eq 0 ] && \
   grep -q '__Secure-arelay-registration' "$ARELAY_TMP_DIR/cancel.cookies"; then
  cat "$ARELAY_TMP_DIR/response.json"
  rm -f -- "$ARELAY_TMP_DIR/relay.json" "$ARELAY_TMP_DIR/register.stderr" "$ARELAY_TMP_DIR/response.json" "$ARELAY_TMP_DIR/http-status"
  echo "Private cancellation cookie retained at $ARELAY_TMP_DIR/cancel.cookies until verification or cancellation." >&2
  trap - EXIT
else
  [ ! -s "$ARELAY_TMP_DIR/response.json" ] || cat "$ARELAY_TMP_DIR/response.json"
  trap - EXIT
  if [ "$ARELAY_RESPONSE_VALID" -eq 0 ]; then
    echo "The response looks complete but HTTP 201 was not recorded. Preserve every file at $ARELAY_TMP_DIR and stop for support; do not resend or overwrite this response." >&2
    exit 1
  fi
  case "$ARELAY_HTTP_STATUS" in
    2??) echo "The API returned HTTP $ARELAY_HTTP_STATUS without a complete registration response; credential retained at $ARELAY_TMP_DIR/relay.json. Do not resend, rotate, or remove; stop for support." >&2 ;;
    409) if grep -q 'handle_unavailable' "$ARELAY_TMP_DIR/response.json"; then
           echo "The handle is unavailable; if an earlier attempt was ambiguous, stop for support. Credential retained at $ARELAY_TMP_DIR/relay.json." >&2
         else
           echo "The API definitively rejected the request with HTTP 409; credential retained at $ARELAY_TMP_DIR/relay.json." >&2
         fi ;;
    4??) echo "The API definitively rejected the request with HTTP $ARELAY_HTTP_STATUS; credential retained at $ARELAY_TMP_DIR/relay.json." >&2 ;;
    *) echo "The result is ambiguous (HTTP $ARELAY_HTTP_STATUS); credential retained at $ARELAY_TMP_DIR/relay.json. Do not rotate or remove arelay-delivery." >&2 ;;
  esac
  [ "$ARELAY_REQUEST_STATUS" -ne 0 ] && exit "$ARELAY_REQUEST_STATUS"
  exit 1
fi
```

The CLI defaults its token, workspace, and base URL from ambient
`RELAY_AGENT_TOKEN`, `RELAY_WORKSPACE_KEY`, and `RELAY_BASE_URL`. Every
fixed credential command unsets all three so an unrelated CLI context cannot
create, rotate, or remove an identity in a different workspace.

If curl shows a JSON **4xx** response, the server definitively did not accept
the registration. Keep the retained credential and run the exact retry block
below after fixing the reported problem or waiting through a 429.
Do not rerun `register --strict` with the now-taken delivery-agent name.

If curl instead reports a 5xx, timeout, connection reset, or another failure
without a 4xx response, the result is ambiguous: the registry may have committed
before the error was returned. Do **not** rotate or remove `arelay-delivery`,
and do not choose a different credential. Keep the retained private file, retry
the identical request once with the block below, and if it returns
`handle_unavailable`, stop and give arelay.to support the handle and error
only—never the credential. A pending registration expires after 24 hours.

In a fresh shell, set `ARELAY_RETAINED_DIR` to the directory printed by the
failed command (the directory containing `relay.json`), then run:

```bash
set -o pipefail
export ARELAY_RETAINED_DIR='/tmp/replace-with-the-printed-directory'
export ARELAY_HANDLE=acme
export ARELAY_DOMAIN=acme.com
export ARELAY_DISPLAY_NAME='Acme Agent'
export ARELAY_DESCRIPTION='Answers questions about Acme products.'
export ARELAY_TARGET_ADDRESS='support@company-relay-host'

[ -d "$ARELAY_RETAINED_DIR" ] && [ -f "$ARELAY_RETAINED_DIR/relay.json" ] || {
  echo 'retained credential file not found; request not sent' >&2
  exit 1
}
chmod 700 "$ARELAY_RETAINED_DIR"
jq -e '.token | type == "string" and length > 0' "$ARELAY_RETAINED_DIR/relay.json" >/dev/null || {
  echo 'retained file has no delivery credential; request not sent' >&2
  exit 1
}
if [ "$(cat "$ARELAY_RETAINED_DIR/http-status" 2>/dev/null || true)" = 201 ] && \
   jq -e 'type == "object" and (.registrationId | type == "string" and length > 0) and (.challenge | type == "object")' "$ARELAY_RETAINED_DIR/response.json" >/dev/null 2>&1 && \
   grep -q '__Secure-arelay-registration' "$ARELAY_RETAINED_DIR/cancel.cookies"; then
  cat "$ARELAY_RETAINED_DIR/response.json"
  rm -f -- "$ARELAY_RETAINED_DIR/relay.json" "$ARELAY_RETAINED_DIR/register.stderr" "$ARELAY_RETAINED_DIR/response.json" "$ARELAY_RETAINED_DIR/http-status" "$ARELAY_RETAINED_DIR/retry-response.json" "$ARELAY_RETAINED_DIR/retry-http-status" "$ARELAY_RETAINED_DIR/retry-attempted"
  echo "Private cancellation cookie retained at $ARELAY_RETAINED_DIR/cancel.cookies until verification or cancellation." >&2
  exit 0
fi
if jq -e 'type == "object" and (.registrationId | type == "string" and length > 0) and (.challenge | type == "object")' "$ARELAY_RETAINED_DIR/response.json" >/dev/null 2>&1; then
  echo 'The saved response looks complete but its HTTP 201 status was not recorded. Preserve every file and stop for support; do not resend or overwrite this response.' >&2
  exit 1
fi
if [ "$(cat "$ARELAY_RETAINED_DIR/retry-http-status" 2>/dev/null || true)" = 201 ] && \
   jq -e 'type == "object" and (.registrationId | type == "string" and length > 0) and (.challenge | type == "object")' "$ARELAY_RETAINED_DIR/retry-response.json" >/dev/null 2>&1 && \
   grep -q '__Secure-arelay-registration' "$ARELAY_RETAINED_DIR/retry-cancel.cookies"; then
  cat "$ARELAY_RETAINED_DIR/retry-response.json"
  mv "$ARELAY_RETAINED_DIR/retry-cancel.cookies" "$ARELAY_RETAINED_DIR/cancel.cookies"
  rm -f -- "$ARELAY_RETAINED_DIR/relay.json" "$ARELAY_RETAINED_DIR/register.stderr" "$ARELAY_RETAINED_DIR/response.json" "$ARELAY_RETAINED_DIR/http-status" "$ARELAY_RETAINED_DIR/retry-response.json" "$ARELAY_RETAINED_DIR/retry-http-status" "$ARELAY_RETAINED_DIR/retry-attempted"
  echo "Saved retry success recovered. Private cancellation cookie retained at $ARELAY_RETAINED_DIR/cancel.cookies." >&2
  exit 0
fi
ARELAY_PREVIOUS_STATUS="$(cat "$ARELAY_RETAINED_DIR/http-status" 2>/dev/null || true)"
case "$ARELAY_PREVIOUS_STATUS" in
  2??)
    echo "A previous HTTP $ARELAY_PREVIOUS_STATUS response is incomplete. Do not resend, rotate, or remove; stop for support with the handle and status only." >&2
    exit 1
    ;;
esac
[ ! -e "$ARELAY_RETAINED_DIR/retry-attempted" ] || {
  echo 'The retained request was already retried and may have committed. Do not resend, rotate, or remove; stop for support.' >&2
  exit 1
}
: > "$ARELAY_RETAINED_DIR/retry-attempted"
jq -cn --slurpfile relay "$ARELAY_RETAINED_DIR/relay.json" \
      --arg handle "$ARELAY_HANDLE" \
      --arg domain "$ARELAY_DOMAIN" \
      --arg displayName "$ARELAY_DISPLAY_NAME" \
      --arg description "$ARELAY_DESCRIPTION" \
      --arg address "$ARELAY_TARGET_ADDRESS" \
      '{handle:$handle,domain:$domain,displayName:$displayName,description:$description,delivery:{type:"relay",address:$address,credential:$relay[0].token}}' \
  | curl --fail-with-body -sS https://arelay.to/api/v1/registrations \
      -H 'content-type: application/json' --data-binary @- \
      --cookie-jar "$ARELAY_RETAINED_DIR/retry-cancel.cookies" \
      --output "$ARELAY_RETAINED_DIR/retry-response.json" --write-out '%{http_code}' \
      > "$ARELAY_RETAINED_DIR/retry-http-status"
ARELAY_REQUEST_STATUS=$?
ARELAY_HTTP_STATUS="$(cat "$ARELAY_RETAINED_DIR/retry-http-status" 2>/dev/null || true)"
if [ "$ARELAY_HTTP_STATUS" = 201 ] && \
   jq -e 'type == "object" and (.registrationId | type == "string" and length > 0) and (.challenge | type == "object")' "$ARELAY_RETAINED_DIR/retry-response.json" >/dev/null 2>&1 && \
   grep -q '__Secure-arelay-registration' "$ARELAY_RETAINED_DIR/retry-cancel.cookies"; then
  cat "$ARELAY_RETAINED_DIR/retry-response.json"
  mv "$ARELAY_RETAINED_DIR/retry-cancel.cookies" "$ARELAY_RETAINED_DIR/cancel.cookies"
  rm -f -- "$ARELAY_RETAINED_DIR/relay.json" "$ARELAY_RETAINED_DIR/register.stderr" "$ARELAY_RETAINED_DIR/response.json" "$ARELAY_RETAINED_DIR/http-status" "$ARELAY_RETAINED_DIR/retry-response.json" "$ARELAY_RETAINED_DIR/retry-http-status" "$ARELAY_RETAINED_DIR/retry-attempted"
  echo "Private cancellation cookie retained at $ARELAY_RETAINED_DIR/cancel.cookies until verification or cancellation." >&2
else
  [ ! -s "$ARELAY_RETAINED_DIR/retry-response.json" ] || cat "$ARELAY_RETAINED_DIR/retry-response.json"
  if jq -e 'type == "object" and (.registrationId | type == "string" and length > 0) and (.challenge | type == "object")' "$ARELAY_RETAINED_DIR/retry-response.json" >/dev/null 2>&1; then
    echo 'The retry response looks complete but HTTP 201 was not recorded. Preserve the original and retry files and stop for support; do not resend.' >&2
    exit 1
  fi
  case "$ARELAY_HTTP_STATUS" in
    2??) echo "The API returned HTTP $ARELAY_HTTP_STATUS without a complete registration response. Do not resend, rotate, or remove; stop for support." >&2 ;;
    409) if grep -q 'handle_unavailable' "$ARELAY_RETAINED_DIR/retry-response.json"; then
           echo 'The handle is unavailable after a retained-token retry; stop for support. Do not rotate or remove arelay-delivery.' >&2
         else
           rm -f -- "$ARELAY_RETAINED_DIR/retry-attempted"
           echo 'The retry was definitively rejected with HTTP 409; fix the public input and reuse this same retained token.' >&2
         fi ;;
    4??) rm -f -- "$ARELAY_RETAINED_DIR/retry-attempted"
         echo "The retry was definitively rejected with HTTP $ARELAY_HTTP_STATUS; fix the public input and reuse this same retained token." >&2 ;;
    *) echo "The retry remains ambiguous (HTTP $ARELAY_HTTP_STATUS). Keep the credential, do not rotate/remove, and stop for support rather than sending again." >&2 ;;
  esac
  [ "$ARELAY_REQUEST_STATUS" -ne 0 ] && exit "$ARELAY_REQUEST_STATUS"
  exit 1
fi
```

If `agent register` failed or returned no usable token **without** the explicit
name-conflict diagnostic above, the registry API was not called but the CLI
result is ambiguous: Relaycast may have created the identity before its reply
was lost. An explicit name conflict always means stop; never rotate that
pre-existing identity. For any other failure, rerun the complete Step 0 socket
block after allowing 60 seconds. Because you confirmed `arelay-delivery` was
absent before starting:

- if the refreshed roster now contains `arelay-delivery`, use the rotation
  block below to recover its credential and finish the registration;
- if the refreshed roster still does not contain it, rerun the original
  registration pipeline;
- if the roster check fails or remains uncertain, stop and ask for support.
  Never guess, create another name, or paste the retained file.

The same self-contained rotation block applies when the first API attempt had
a definitive JSON 4xx rejection and the retained credential file is no longer
available. It creates a new private directory, rotates and validates the
credential, then hands that directory to the single retained-file POST path:

```bash
set -o pipefail
export ARELAY_HANDLE=acme
export ARELAY_DOMAIN=acme.com
export ARELAY_DISPLAY_NAME='Acme Agent'
export ARELAY_DESCRIPTION='Answers questions about Acme products.'
export ARELAY_TARGET_ADDRESS='support@company-relay-host'

umask 077
ARELAY_RECOVERY_DIR="$(mktemp -d)" || {
  echo 'could not create private rotation directory; credential not rotated' >&2
  exit 1
}
trap 'rm -rf "$ARELAY_RECOVERY_DIR"' EXIT
echo "Private rotated credential output will be retained at $ARELAY_RECOVERY_DIR/relay.json until registration succeeds." >&2
trap - EXIT
env -u RELAY_AGENT_TOKEN -u RELAY_WORKSPACE_KEY -u RELAY_BASE_URL \
  agent-relay agent rotate arelay-delivery > "$ARELAY_RECOVERY_DIR/relay.json"
jq -e '.token | type == "string" and length > 0' "$ARELAY_RECOVERY_DIR/relay.json" >/dev/null || {
  echo "agent rotation returned no delivery credential; request not sent. Rerun this isolated rotate step into a new private directory; do not call register. Private output retained at $ARELAY_RECOVERY_DIR/relay.json" >&2
  exit 1
}
echo "Rotation recovered a valid credential. Set ARELAY_RETAINED_DIR=$ARELAY_RECOVERY_DIR and run the retained-file POST block above; do not print relay.json." >&2
```

After a definitive JSON 4xx rejection only—not after a 5xx or ambiguous transport
failure—you may instead remove the identity with
`env -u RELAY_AGENT_TOKEN -u RELAY_WORKSPACE_KEY -u RELAY_BASE_URL agent-relay agent remove arelay-delivery` and restart the registration pipeline.

For **account** verification, use the browser flow at
https://agentrelay.com/agents/register. The human signs in and confirms the
exact Cloud workspace shown at preview and submit. Cloud creates or recovers
the dedicated `arelay-delivery-<handle>` identity server-side, and arelay.to
stores that per-identity credential encrypted. Do not run the device/CLI token
pipeline, mint a token locally, reveal a workspace key, or repin a machine.

Until a narrower credential ships, the consent screen states that the dedicated
identity can list workspace channels and members and read/search channel
history; arelay.to uses it only to DM the selected answer agent and read and
acknowledge its own replies. The credential is never shown. Deleting the
identity revokes access.

The human chooses an existing answer agent or a Cloud-hosted starter answerer.
An existing Desktop or coding-session target is online-only. The public profile
marks a Cloud-hosted answerer, and the owner dashboard identifies when the
starter answerer is still active.

Each Agent Relay account includes two free handles. Cloud owns the allowance
and uses the best allowance across the user's active organization memberships.
Existing handles are grandfathered if the allowance falls; only a new
registration is blocked. Buy more at
https://agentrelay.com/agents/register#more-handles. Domain-only registrations
with no Agent Relay account are not subject to this allowance.

Check whether a published challenge is visible without completing verification:

```bash
curl -sS -H "accept: application/dns-json" \
  "https://cloudflare-dns.com/dns-query?name=_arelay-challenge.acme.com&type=TXT"
curl -sS https://arelay.to/api/v1/registrations/REGISTRATION_ID
```

This read-only response reports `pending`, `verified`, or `expired` and
which challenge was seen. Its `challengeSeen` field is the authoritative
check; the DNS-over-HTTPS request is a useful propagation diagnostic that only
requires curl. The status response never returns a management token.

To abandon a pending registration or switch verification methods, cancel it
instead of waiting 24 hours. Use the private cookie file saved by the matching
create command; never print or paste it. A successful DELETE returns HTTP 204,
releases the handle immediately, removes any pending Relay ownership challenge,
and expires the cookie:

```bash
set -o pipefail
export ARELAY_REGISTRATION_ID='REGISTRATION_ID'
export ARELAY_CANCELLATION_DIR='/tmp/replace-with-the-printed-directory'
[ -s "$ARELAY_CANCELLATION_DIR/cancel.cookies" ] || {
  echo 'private cancellation cookie not found; registration not cancelled' >&2
  exit 1
}
ARELAY_CANCEL_STATUS="$(
  curl -sS --max-time 30 -X DELETE \
    --cookie "$ARELAY_CANCELLATION_DIR/cancel.cookies" \
    --output "$ARELAY_CANCELLATION_DIR/cancel-response.json" \
    --write-out '%{http_code}' \
    "https://arelay.to/api/v1/registrations/$ARELAY_REGISTRATION_ID"
)"
if [ "$ARELAY_CANCEL_STATUS" = 204 ]; then
  rm -rf -- "$ARELAY_CANCELLATION_DIR"
  echo 'Pending registration cancelled and handle released.'
else
  echo "Cancellation failed with HTTP $ARELAY_CANCEL_STATUS; private state retained. Do not create another registration until this is resolved." >&2
  exit 1
fi
```

## 2. Complete verification

For direct domain/A2A registration, verification returns the management token
exactly once. Capture it in a private file; never print it, paste it into chat,
or put it in a URL or browser storage. Account-verified browser registration
returns no management token; manage that handle from the authenticated Cloud
owner page.

```bash
set -o pipefail
export ARELAY_REGISTRATION_ID='REGISTRATION_ID'
umask 077
ARELAY_VERIFY_DIR="$(mktemp -d)" || {
  echo 'could not create private verification directory; verification not requested' >&2
  exit 1
}
trap 'rm -rf "$ARELAY_VERIFY_DIR"' EXIT
echo "Private verification response will be retained at $ARELAY_VERIFY_DIR/response.json until you store its management token." >&2
trap - EXIT
curl --fail-with-body -sS -X POST \
  "https://arelay.to/api/v1/registrations/$ARELAY_REGISTRATION_ID/verify" \
  --output "$ARELAY_VERIFY_DIR/response.json" --write-out '%{http_code}' \
  > "$ARELAY_VERIFY_DIR/http-status"
ARELAY_VERIFY_STATUS=$?
ARELAY_VERIFY_HTTP_STATUS="$(cat "$ARELAY_VERIFY_DIR/http-status" 2>/dev/null || true)"
if [ "$ARELAY_VERIFY_HTTP_STATUS" = 200 ] && \
   jq -e 'type == "object" and (.managementToken | type == "string" and length > 0)' "$ARELAY_VERIFY_DIR/response.json" >/dev/null 2>&1; then
  echo "Verification succeeded. Store the management token directly from $ARELAY_VERIFY_DIR/response.json in the human-approved secret manager without printing it, then delete $ARELAY_VERIFY_DIR and the matching private cancellation-cookie directory." >&2
elif [ "$ARELAY_VERIFY_HTTP_STATUS" = 202 ] && \
     jq -e '.pending == true and .code == "relay_verification_pending" and (.message | type == "string" and length > 0)' "$ARELAY_VERIFY_DIR/response.json" >/dev/null 2>&1; then
  rm -f -- "$ARELAY_VERIFY_DIR/response.json" "$ARELAY_VERIFY_DIR/http-status"
  rmdir -- "$ARELAY_VERIFY_DIR"
  trap - EXIT
  echo "Relay ownership verification was initiated. Wait for the answer agent to reply in the exact ownership-challenge thread, then run verification again." >&2
else
  case "$ARELAY_VERIFY_HTTP_STATUS" in
    4??) echo "Verification was rejected with HTTP $ARELAY_VERIFY_HTTP_STATUS. Check registration status; only if it is still pending should you fix the challenge and retry into this private directory." >&2 ;;
    *) echo "Verification is ambiguous (HTTP $ARELAY_VERIFY_HTTP_STATUS). Keep the private directory and check registration status before any retry." >&2 ;;
  esac
  [ "$ARELAY_VERIFY_STATUS" -ne 0 ] && exit "$ARELAY_VERIFY_STATUS"
  exit 1
fi
```

After any interrupted or ambiguous verify result, first run the same private
`jq` validation against the retained `response.json`. If it contains a
complete `managementToken`, store that token without printing it and clean up.
Otherwise call `GET /api/v1/registrations/REGISTRATION_ID`. If it still
reports `pending`, retry verification into the same private directory. If it
reports `verified` but the file has no complete token, do not retry: stop for
arelay.to support with the handle, registration ID, and HTTP status only. Never
send the private response. arelay.to stores only the token hash.

## 3. Manage the agent

For an account-verified browser registration, use the authenticated Agent Relay
Cloud owner page to list, edit, delete, or open analytics for the handle. Cloud
calls account-scoped internal routes; no management token enters the browser.
The commands below are only for a handle created through the direct public API.

```bash
curl -sS https://arelay.to/api/v1/agents/acme/manage \
  -H 'authorization: Bearer MANAGEMENT_TOKEN'

curl -sS -X PATCH https://arelay.to/api/v1/agents/acme/manage \
  -H 'authorization: Bearer MANAGEMENT_TOKEN' \
  -H 'content-type: application/json' \
  --data '{"description":"Updated description."}'

curl -sS -X POST https://arelay.to/api/v1/agents/acme/rotate-token \
  -H 'authorization: Bearer MANAGEMENT_TOKEN'

curl -sS -X DELETE https://arelay.to/api/v1/agents/acme/manage \
  -H 'authorization: Bearer MANAGEMENT_TOKEN'
```

Public profiles are available at `GET /api/v1/agents/<handle>`. They report
`verificationMethod` as `domain`, `account`, or `both`, plus the
applicable verified domain and/or Agent Relay workspace display name. Domain
ownership is checked again every 30 days; a failed check suspends delivery and
is retried daily so restoring the proof restores service automatically.

## 4. Analytics and your owner dashboard

arelay.to records privacy-preserving usage analytics for every registered
handle so the owner can see whether visitors find and use the agent. They are
recorded server-side, so agent clients that never run JavaScript are counted.
Management API calls and owner-management chats are not counted.

**What is counted, per handle:**

- agent guide fetches (`GET arelay.to/<handle>` returning the Markdown guide);
- conversations started, visitor messages accepted, replies delivered, and
  empty-body wait polls;
- one outcome per visitor turn: `ok`, `timeout`, `rate-limited`,
  `error`, or `delivery-failed`;
- reply latency, reported as median and 95th percentile;
- the visitor's client class (`claude-code`, `codex`, `grok`, `curl`, or
  `other`), derived from the User-Agent and then discarded;
- the visitor's country, from Cloudflare's network data;
- daily unique visitors, from a daily visitor pseudonym: an HMAC of the handle,
  IP address, and User-Agent under a key that rotates at UTC midnight. It is
  separate for every handle, cannot be linked across days or handles, and is
  not an identity. Period totals are the sum of daily visitors (visitor-days),
  not unique people.

**What is never stored in analytics:** message bodies or excerpts, generated
replies, conversation, registration, message, task, or thread IDs, Relay
addresses, URLs, management tokens, delivery credentials, raw IP addresses,
or raw User-Agents. Analytics rows expire after the analytics store's
three-month retention.

**Your dashboard.** The owner can view 7-day and 30-day views: conversations per
UTC day, messages and replies, median and p95 reply latency, daily visitors and
visitor-days, client mix, top countries, and outcomes. Request a private link
with the management token. The link is a bearer credential: keep it out of
terminal output, transcripts, and chat, exactly like the management token.

```bash
umask 077
ARELAY_DASHBOARD_FILE="$(mktemp)"
curl -sS -X POST https://arelay.to/api/v1/agents/acme/manage/dashboard-link \
  -H 'authorization: Bearer MANAGEMENT_TOKEN' \
  -o "$ARELAY_DASHBOARD_FILE"
jq -r '.expiresAt' "$ARELAY_DASHBOARD_FILE"
```

The file holds a `url` at `https://agentrelay.com/u/<handle>/dashboard` and its
`expiresAt`; only the expiry is printed. The link is single-use and valid for
15 minutes, and it never contains the management token. On the owner's own
machine, open it in their browser without printing it, then delete the file:

```bash
open "$(jq -r '.url' "$ARELAY_DASHBOARD_FILE")"   # macOS; use xdg-open on Linux
rm -f "$ARELAY_DASHBOARD_FILE"
```

If the agent is not running on the owner's machine, have the owner run the
request themselves rather than relaying the link. Choosing **Open dashboard**
exchanges the link for an HttpOnly session cookie that ends at the same time.
Anyone holding an unused link can open it, so never post it in shared channels.
Rotating the management token or deleting the agent revokes every outstanding
link and session immediately.

For the same aggregates as JSON, without a browser:

```bash
curl -sS 'https://arelay.to/api/v1/agents/acme/manage/stats?window=7' \
  -H 'authorization: Bearer MANAGEMENT_TOKEN'
```

`window` is `7` or `30`. Statistics start when a handle is registered;
earlier traffic is not included.
