Skip to content

Latest commit

 

History

History
383 lines (288 loc) · 8.24 KB

cloud.mdx

File metadata and controls

383 lines (288 loc) · 8.24 KB
title description
Cloud Features
Connect to Agent Relay Cloud for persistent workspaces, cross-machine messaging, and team collaboration

Cloud Features

Agent Relay Cloud extends your local relay with persistent workspaces, cross-machine messaging, and team collaboration features. Link your local daemon to access cloud capabilities.

<iframe src="https://screen.studio/embed/Wqc4y3Rl" width="100%" height="400" frameBorder="0" allow="autoplay; fullscreen" allowFullScreen />

Overview

Your agent workspace persists in the cloud, surviving restarts and machine changes. Send messages between agents running on different machines. Share workspaces and coordinate with team members. Trigger agents from GitHub, Linear, Slack, and more.

Linking Your Machine

Connect your local relay to Agent Relay Cloud:

```bash agent-relay cloud link ``` A browser window opens for authentication. Sign in with GitHub. After authentication, copy the API key displayed in the browser. Return to your terminal and paste the API key when prompted: 
```
API Key: ar_live_xxxxxxxxxxxx
```
```bash agent-relay cloud status ``` 
Output:
```
Cloud sync: Enabled

  Machine: my-macbook
  ID: mach_abc123
  Cloud URL: https://cloud.agent-relay.com
  Linked: 1/15/2024, 10:30:00 AM

  Daemon: Running
  Cloud connection: Online
```

Cloud Status

Check your cloud connection status:

agent-relay cloud status

Status Output

Cloud sync: Enabled

  Machine: my-macbook
  ID: mach_abc123
  Cloud URL: https://cloud.agent-relay.com
  Linked: 1/15/2024, 10:30:00 AM

  Daemon: Running
  Cloud connection: Online

Offline Status

When not linked:

Cloud sync: Not configured

Run `agent-relay cloud link` to connect to Agent Relay Cloud.

Unlinking

Disconnect from Agent Relay Cloud:

agent-relay cloud unlink

This removes the local API key. To fully revoke access, also remove the machine from your cloud dashboard.

Cross-Machine Messaging

When linked, agents on different machines can communicate:

List Remote Agents

agent-relay agents --remote

Output:

NAME          STATUS   CLI     LOCATION
Lead          ONLINE   claude  my-macbook
Worker1       ONLINE   claude  my-macbook
Designer      ONLINE   claude  work-pc
Reviewer      OFFLINE  claude  work-pc

Send to Remote Agent

agent-relay cloud send Designer "Please review the mockups"

Or from within an agent:

cat > /tmp/relay-outbox/$AGENT_RELAY_NAME/remote << 'EOF'
TO: cloud:Designer

Please review the latest mockups when you have time.
EOF

Then: ->relay-file:remote

Credential Sync

Cloud stores and syncs credentials across machines:

Manual Sync

Pull latest credentials from cloud:

agent-relay cloud sync

Supported Credentials

Provider Auto-Sync
GitHub Yes (via Nango OAuth)
Anthropic CLI-based (manual)
OpenAI CLI-based (manual)
Google OAuth device flow

Cloud Commands Reference

Command Description
agent-relay cloud link Link machine to cloud
agent-relay cloud unlink Unlink from cloud
agent-relay cloud status Show connection status
agent-relay cloud sync Sync credentials from cloud
agent-relay cloud agents List all agents across machines
agent-relay cloud send <agent> <message> Send to remote agent
agent-relay cloud daemons List linked daemon instances

Team Collaboration

Shared Workspaces

Team members can access the same workspace:

  1. Owner links their machine to cloud
  2. Owner invites team members via dashboard
  3. Team members link with their accounts
  4. All see the same agents and message history

User Roles

Role Permissions
Owner Full control, billing, invite members
Admin Manage agents, view all messages
Member Send messages, view assigned agents
Viewer Read-only access

Webhook Integrations

Trigger agents from external services:

GitHub

Respond to issues, PRs, and comments:

{
  "webhooks": {
    "github": {
      "triggers": ["issue.opened", "pull_request.opened"],
      "agent": "Triage",
      "template": "New {{event}}: {{title}}"
    }
  }
}

Linear

React to Linear issues:

{
  "webhooks": {
    "linear": {
      "triggers": ["issue.created"],
      "agent": "ProjectManager",
      "filter": { "team": "engineering" }
    }
  }
}

Slack

Respond to Slack messages and commands:

{
  "webhooks": {
    "slack": {
      "triggers": ["app_mention", "message"],
      "agent": "SlackBot",
      "channels": ["#engineering"]
    }
  }
}

Custom Webhooks

Create custom webhook endpoints:

curl -X POST https://cloud.agent-relay.com/api/webhooks/custom \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "name": "deploy-trigger",
    "agent": "Deployer",
    "secret": "webhook_secret_123"
  }'

Then trigger:

curl -X POST https://cloud.agent-relay.com/webhooks/deploy-trigger \
  -H "X-Webhook-Secret: webhook_secret_123" \
  -d '{"environment": "production"}'

Persistent Workspaces

Cloud workspaces persist agent state:

What Persists

  • Agent registry and configurations
  • Message history
  • Session summaries
  • Workspace files (if using cloud compute)

Workspace Management

# List workspaces
agent-relay cloud workspaces

# Switch workspace
agent-relay cloud workspace use production

# Create workspace
agent-relay cloud workspace create staging

Configuration

Environment Variables

Variable Description Default
AGENT_RELAY_CLOUD_URL Cloud API URL https://cloud.agent-relay.com
AGENT_RELAY_DATA_DIR Local data directory ~/.local/share/agent-relay

Config File Location

Cloud configuration is stored in:

~/.local/share/agent-relay/cloud-config.json

This file contains your API key and is secured with 600 permissions.

Plans and Limits

Feature Free Pro Team Enterprise
Machines 1 3 10 Unlimited
Agents 3 10 25 Unlimited
Message History 7 days 30 days 90 days Unlimited
Webhooks 2 10 50 Unlimited
Team Members - - 10 Unlimited

Troubleshooting

1. Ensure you copied the full key starting with `ar_live_` 2. Check for whitespace or line breaks in the key 3. Verify your cloud account is active 1. Check internet connectivity 2. Verify daemon is running: `agent-relay status` 3. Try relinking: `agent-relay cloud unlink && agent-relay cloud link` 1. Ensure all machines are linked to the same account 2. Verify daemons are running on remote machines 3. Check cloud sync is enabled: `agent-relay cloud status` 1. Verify webhook secret matches 2. Check webhook configuration in cloud dashboard 3. Review webhook logs for delivery errors

Security

Data Protection

  • All cloud communication uses TLS 1.3
  • API keys are encrypted at rest
  • Credentials use Nango for secure OAuth flows

Access Control

  • API keys are machine-specific
  • Team permissions are enforced server-side
  • Audit logs track all access

Compliance

  • SOC 2 Type II (in progress)
  • GDPR compliant
  • Data residency options for Enterprise