@rndrntwrk/plugin-555stream

elizaOS plugin for AI agent control of 555stream live streaming studio via the Agent Control API.

Features

• 26 Actions for complete stream control
• Real-time State Sync via WebSocket
• Approval Flow for dangerous operations
• HTTP + WebSocket Client for Agent Control API
• Session Management with auto-reconnect

Installation

bun add @rndrntwrk/plugin-555stream

Or with npm:

npm install @rndrntwrk/plugin-555stream

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | STREAM555_BASE_URL | Yes | 555stream control-plane URL (e.g., https://stream.rndrntwrk.com) | | STREAM555_AGENT_TOKEN | Yes | Agent JWT token from 555stream dashboard or API | | STREAM555_DEFAULT_SESSION_ID | No | Auto-bind to this session on startup | | STREAM555_REQUIRE_APPROVALS | No | Require approval for dangerous actions (default: true) |

Example .env

STREAM555_BASE_URL=https://stream.rndrntwrk.com
STREAM555_AGENT_TOKEN=eyJhbGciOiJIUzI1NiIs...
STREAM555_DEFAULT_SESSION_ID=abc123
STREAM555_REQUIRE_APPROVALS=true

Quick Start

1. Add the plugin to your character file

{
  "name": "555stream Operator",
  "bio": [
    "Operates 555stream live sessions safely and reliably.",
    "Uses explicit approval gates for high-impact actions."
  ],
  "system": "You control a production live streaming studio. Be safe, deliberate, and reversible. Never start/stop streams without explicit operator approval.",
  "plugins": [
    "@elizaos/plugin-sql",
    "@elizaos/plugin-bootstrap",
    "@rndrntwrk/plugin-555stream"
  ]
}

2. Get an Agent Token

Option A: Via Admin API (Recommended)

If you have admin access to the 555stream control-plane, generate a token using the API:

curl -X POST https://stream.rndrntwrk.com/api/agent/v1/auth/token \
  -H "X-Admin-Key: YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["*"],
    "sessionIds": ["*"],
    "expiresIn": "7d"
  }'

Response:

{
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "expiresAt": "2025-01-23T00:00:00.000Z",
  "scopes": ["*"],
  "sessionIds": ["*"]
}

Token Scopes

You can limit agent permissions with specific scopes:

| Scope | Permissions | |-------|-------------| | * | Full access (all operations) | | sessions:read | Read session state | | sessions:create | Create/bind sessions | | stream:start | Start streams | | stream:stop | Stop streams | | studio:write | Modify graphics, layouts | | sources:write | Manage sources | | media:write | Upload media | | platforms:write | Configure platforms | | radio:write | Control radio |

Option B: Via 555stream Dashboard

1. Log in to your 555stream dashboard
2. Navigate to Settings > Agent Access
3. Click Generate Token
4. Select permissions and expiry
5. Copy the generated token

3. Set environment variables

export STREAM555_BASE_URL=https://stream.rndrntwrk.com
export STREAM555_AGENT_TOKEN=your_token_here

4. Start your elizaOS agent

The plugin will automatically connect to the 555stream control-plane and bind to the default session if configured.

Actions Reference

Session Management

| Action | Description | Approval | |--------|-------------|----------| | STREAM555_HEALTHCHECK | Check API connectivity | No | | STREAM555_BOOTSTRAP | Bind to a session | No |

Stream Control

| Action | Description | Approval | |--------|-------------|----------| | STREAM555_STREAM_START | Start streaming to platforms | Yes | | STREAM555_STREAM_STOP | Stop all active streams | Yes | | STREAM555_STREAM_FALLBACK | Switch to fallback mode | Yes | | STREAM555_STREAM_STATUS | Get current stream status | No |

State Management

| Action | Description | Approval | |--------|-------------|----------| | STREAM555_STATE_PATCH | Update production state | Configurable | | STREAM555_LAYOUT_SET | Set scene layout | No | | STREAM555_SCENE_SET_ACTIVE | Switch active scene | No |

Graphics

| Action | Description | Approval | |--------|-------------|----------| | STREAM555_GRAPHICS_CREATE | Create a graphic overlay | No | | STREAM555_GRAPHICS_UPDATE | Update graphic properties | No | | STREAM555_GRAPHICS_DELETE | Delete a graphic | Yes | | STREAM555_GRAPHICS_TOGGLE | Toggle graphic visibility | No |

Sources

| Action | Description | Approval | |--------|-------------|----------| | STREAM555_SOURCE_CREATE | Add a video/audio source | No | | STREAM555_SOURCE_UPDATE | Update source properties | No | | STREAM555_SOURCE_DELETE | Remove a source | Yes |

Guests

| Action | Description | Approval | |--------|-------------|----------| | STREAM555_GUEST_INVITE | Create guest invite link | Yes | | STREAM555_GUEST_REMOVE | Remove a guest | Yes |

Media

| Action | Description | Approval | |--------|-------------|----------| | STREAM555_UPLOAD_IMAGE | Upload image from URL | No | | STREAM555_UPLOAD_VIDEO | Upload video from URL | No | | STREAM555_VIDEO_ADD_URL | Add video by URL | No | | STREAM555_VIDEO_DELETE | Delete a video asset | Yes |

Platforms

| Action | Description | Approval | |--------|-------------|----------| | STREAM555_PLATFORM_CONFIG | Configure platform (RTMP, key) | Yes | | STREAM555_PLATFORM_TOGGLE | Enable/disable platform | No |

Radio (Lofi)

| Action | Description | Approval | |--------|-------------|----------| | STREAM555_RADIO_CONFIG | Configure radio settings | No | | STREAM555_RADIO_CONTROL | Control radio playback | No |

Providers

The plugin exposes two providers for the model context:

STREAM555_STATE

Real-time session state including:

• Current scene and layout
• Active sources and graphics
• Stream status
• Connected guests

STREAM555_CAPABILITIES

Available actions based on current state and permissions.

Approval Flow

Actions marked with Approval Required use an async approval pattern to prevent accidental or unauthorized operations.

How It Works

1. Agent calls a dangerous action (e.g., STREAM555_STREAM_START)
2. Plugin creates a pending approval request (expires in 5 minutes)
3. Agent responds: "Approval required - ID: approval-1234567890-abc123def"
4. Operator approves via API (see below)
5. Agent re-calls action with _approvalId parameter
6. Action executes

Operator Approval API

The approval endpoints are served by elizaOS (not 555stream). Replace localhost:3000 with your elizaOS deployment URL.

All approval endpoints require authentication with the agent token.

List Pending Approvals

# Replace localhost:3000 with your elizaOS URL
curl http://localhost:3000/555stream/approvals \
  -H "Authorization: Bearer YOUR_AGENT_TOKEN"

Response:

{
  "approvals": [
    {
      "id": "approval-1705432100000-abc123def",
      "actionName": "STREAM555_STREAM_START",
      "actionParams": { "input": { "type": "lofi" } },
      "status": "pending",
      "createdAt": 1705432100000,
      "expiresAt": 1705432400000
    }
  ],
  "count": 1
}

Get Approval Details

curl http://localhost:3000/555stream/approvals/approval-1705432100000-abc123def \
  -H "Authorization: Bearer YOUR_AGENT_TOKEN"

Approve an Action

curl -X POST http://localhost:3000/555stream/approvals/approval-1705432100000-abc123def/approve \
  -H "Authorization: Bearer YOUR_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"approvedBy": "[email protected]"}'

Response:

{
  "success": true,
  "approval": {
    "id": "approval-1705432100000-abc123def",
    "status": "approved",
    "resolvedAt": 1705432150000,
    "resolvedBy": "[email protected]"
  }
}

Reject an Action

curl -X POST http://localhost:3000/555stream/approvals/approval-1705432100000-abc123def/reject \
  -H "Authorization: Bearer YOUR_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rejectedBy": "[email protected]"}'

View Approval History

curl http://localhost:3000/555stream/approvals/history \
  -H "Authorization: Bearer YOUR_AGENT_TOKEN"

After Approval

Once approved, the agent should re-invoke the action. The approval ID is passed automatically by the agent runtime or can be included manually:

// Agent internally passes: { ...params, _approvalId: "approval-xxx" }

Approval Expiry

• Approvals expire 5 minutes after creation
• Expired approvals cannot be approved and must be re-requested
• Approval history is kept for 1 hour for audit purposes

Disable Approvals (Development Only)

STREAM555_REQUIRE_APPROVALS=false

Warning: Only disable approvals in development environments. In production, this exposes dangerous operations without human oversight.

Development

# Install dependencies
bun install

# Build
bun run build

# Type check
bun run typecheck

# Watch mode
bun run dev

Requirements

• elizaOS ^1.7.0
• Node.js 18+ or Bun
• 555stream account with Agent API access

License

MIT