Registering an Agent

Before an AI agent can receive messages from apps, it must be registered with Relay. Registration creates an agent token that authenticates the agent's WebSocket connection.

Registration Process

1. Log in to Relay Dashboard

Navigate to https://relay.ckgworks.com and log in with your email and OTP.

2. Create a New Agent

In the dashboard, go to Agents and click Register Agent.

Fill in:

Field	Example	Notes
Agent ID	athena	Lowercase slug, unique within your organization. Used in app events.
Name	Athena	Display name shown in app discovery.
Description	Personal EA, general tasks	Brief description of what the agent does.

3. Save and Copy Token

After registration, Relay displays your agent token once:

rla_athena_k9x2p7m2jq8r5v3n1b9...

Important: Copy this token immediately and store it securely. Once you leave this page, the token is not shown again.

Token Storage

Store the token in your agent server's configuration:

Environment variable:

export RELAY_AGENT_TOKEN="rla_athena_k9x2p7m2jq8r5v3n1b9..."

Config file (plugin):

{
  "agents": [
    {
      "agent_id": "athena",
      "token": "rla_athena_k9x2p7m2jq8r5v3n1b9..."
    }
  ]
}

Never commit tokens to version control. Use environment variables or secure vaults.

Agent Token Format

Agent tokens have a specific format:

• Prefix: rla_ (always)
• Agent ID: athena (from registration)
• Random suffix: k9x2p7m2jq8r5v3n1b9... (40+ characters)
• Example: rla_athena_k9x2p7m2jq8r5v3n1b9x4m8n2p7k3q5r8s1t4v7w2y5z8

Relay validates the token format and signature on every WebSocket connection.

Token Rotation

For security, you can rotate your agent's token from the dashboard.

Rotating a Token

1. Go to Agents → select your agent → Settings
2. Click Rotate Token
3. Relay displays a new token
4. You get a 1-hour grace period to update your agent server config
5. After 1 hour, the old token stops working

Grace Period

During the grace period, both old and new tokens are valid. This allows you to:

1. Update your agent server config with the new token
2. Restart or redeploy the agent server
3. Be confident the old token won't break active connections

Time 0:00    - Rotate token in dashboard
             - Old token: VALID
             - New token: VALID

Time 0:30    - Update agent config with new token
             - Restart agent server
             - Old token: VALID
             - New token: VALID

Time 1:00    - Grace period expires
             - Old token: INVALID
             - New token: VALID

Multi-Agent Setup

If you run multiple AI agents from one process (e.g., using the OpenClaw plugin), register each agent separately:

1. Register Agent 1: athena → get token rla_athena_...
2. Register Agent 2: klyve → get token rla_klyve_...
3. Register Agent 3: future_agent → get token rla_future_...

Then configure your plugin with all tokens:

{
  "relay": {
    "url": "wss://api.relay.ckgworks.com/v1/ws/agent"
  },
  "agents": [
    {
      "agent_id": "athena",
      "token": "rla_athena_k9x2p...",
      "ttl_days": 14
    },
    {
      "agent_id": "klyve",
      "token": "rla_klyve_k9x2p...",
      "ttl_days": 30
    }
  ]
}

Agent Status in Dashboard

After registration, you can monitor your agent in the dashboard:

• Connection Status: Online/Offline (updated in real-time)
• Last Heartbeat: When the agent last sent a ping
• Events Processed: Count of events received
• Uptime: Duration of current connection

Deactivating an Agent

To temporarily disable an agent without deleting it:

1. Go to Agents → select your agent → Settings
2. Click Deactivate
3. Apps will receive error: AGENT_NOT_ALLOWED or AGENT_OFFLINE

To reactivate, click Activate.

Managing Allowlists

By default, all registered apps in your organization can send events to your agent. To restrict access:

1. Go to Agents → select your agent → Allowlist
2. Click Add App
3. Select app(s) to allowlist
4. Save

Once an allowlist exists, only allowlisted apps can send events to your agent.

No allowlist = open to all apps in organization Allowlist exists = only specified apps can send events

Example Allowlist Setup

Agent: Athena
Current allowlist:
  ✓ Portal
  ✓ Studio
  ✓ Academy
  ✗ Flow (not allowed)
  ✗ Future App (not allowed)

If Flow tries to send an event to Athena, it receives: AGENT_NOT_ALLOWED

To allow Flow, click Add App and select it.

Best Practices

Do

• Store tokens securely (env vars, vaults)
• Rotate tokens periodically (every 90 days)
• Use descriptive agent IDs
• Monitor connection status
• Document your allowlist policy

Don't

• Commit tokens to git
• Share tokens via email
• Use generic agent IDs like "agent1"
• Hardcode tokens in code
• Ignore rotation grace periods

Troubleshooting

Token won't work after copying?

• Ensure you copied the entire token (it's long)
• Check there are no extra spaces or newlines
• Verify environment variable is set correctly

"Invalid agent token" on connection?

• Confirm token prefix is rla_
• Check if you've rotated the token (old one expired)
• Request a new token from dashboard

Agent appears offline in dashboard?

• Check agent server logs for connection errors
• Verify network connectivity to api.relay.ckgworks.com
• Ensure agent server is actually running
• Check firewall/proxy isn't blocking WebSocket

"Agent not allowed" when sending events?

• Check the allowlist in agent settings
• Verify the app is in the allowlist
• If no allowlist exists, agent should be open (check dashboard)