Connecting to the Network

Connecting your edge node is the final step in the setup process. Enrollment establishes a secure identity for your node, allowing it to receive traffic and report telemetry to the control plane.

Install the CLI

curl -sSfL https://github.com/Livepeer-FrameWorks/monorepo/releases/latest/download/install.sh | sh

Override the version or install directory with environment variables:

curl -sSfL https://github.com/Livepeer-FrameWorks/monorepo/releases/latest/download/install.sh | \
  FRAMEWORKS_VERSION=v1.2.3 FRAMEWORKS_INSTALL_DIR=/usr/local/bin sh

Keep the CLI up to date:

frameworks update

Quick Start: One-Command Deploy

If you’re logged in (frameworks login), deploy an edge node in a single command:

frameworks edge deploy --ssh ubuntu@edge-1 --email [email protected]

This automatically:

1. Creates a private edge cluster with an assigned Foghorn if you don’t have one
2. Generates an enrollment token
3. Pre-registers the edge node through Bridge (assigns domain, ID, Foghorn address, and internal gRPC trust bootstrap)
4. Runs the full provision pipeline (preflight, tuning, templates, start, verify)

To deploy to a specific cluster:

frameworks edge deploy --cluster-id my-edge-prod --ssh ubuntu@edge-1

The target cluster must already have an assigned Foghorn. If you are starting from scratch, omit --cluster-id and let Bridge create the private edge cluster.

Manual Setup

If you prefer step-by-step control, follow the sections below.

Get an Enrollment Token

You need an edge_node bootstrap token for a cluster that has an assigned Foghorn.

Via Dashboard (tenant owner):

1. Go to Infrastructure → Network
2. Click Create Private Cluster
3. Copy the bootstrap token shown in the modal

Use this dashboard token only after the cluster has a Foghorn assignment. The one-command CLI path creates that assignment automatically.

If a dashboard-created token fails with Cluster has no Foghorn assignment yet, use frameworks edge deploy without --cluster-id or ask an admin to create a token for an assigned edge cluster.

Via CLI (admin):

frameworks admin bootstrap-tokens create \
  --kind edge_node \
  --tenant-id <TENANT_UUID> \
  --cluster-id <CLUSTER_ID> \
  --name "edge-node-1" \
  --ttl 24h

By default, bootstrap tokens are single-use. Set --usage-limit if you need a reusable token.

Enroll the Node

First, add the enrollment token to your .edge.env:

# In .edge.env
EDGE_ENROLLMENT_TOKEN=your-enrollment-token

Then start the stack:

frameworks edge enroll --dir /opt/frameworks-edge

This:

1. Starts the MistServer, Helmsman, and Caddy containers
2. Waits for https://<EDGE_DOMAIN>/health to become available
3. Helmsman connects to Foghorn (gRPC) and sends the enrollment token
4. Foghorn asks Quartermaster to register the node and starts including healthy heartbeats in routing decisions

The enrollment token carries tenant_id and cluster_id, so your node is enrolled into the correct cluster automatically. After enrollment, your node appears in the dashboard under Infrastructure → Network.

Bootstrap (Token-Based Provisioning)

If you used --enrollment-token during frameworks edge init, the CLI sent the token to Bridge’s public bootstrapEdge mutation. Bridge validates the token via Quartermaster, finds the cluster’s assigned Foghorn, and proxies a PreRegisterEdge call. The response carries:

• Node ID — a stable, unique identifier for your node
• Edge domain — {node_label}.{cluster_slug}.{base_domain} where node_label is the node ID with a single edge- prefix (Navigator creates the A record)
• Pool domain — the cluster’s shared edge pool domain
• Foghorn gRPC address — for Helmsman’s ongoing control stream
• Internal CA bundle — staged locally so Helmsman can trust internal gRPC before the first control stream connects

The operator only ever needs the token. Bridge is the rendezvous; the cluster’s Foghorn is resolved server-side. After bootstrap, the edge talks directly to its assigned Foghorn — it does not join the internal WireGuard mesh.

Certificate Renewal (ConfigSeed)

After initial provisioning, certificate renewals are pushed to edge nodes via ConfigSeed — Foghorn sends updated TLS bundles to Helmsman over the existing gRPC control stream. Edges do not need direct access to the ACME provider or Navigator.

Verify Connection

Check that your node is talking to the network:

frameworks edge status --dir /opt/frameworks-edge

This shows:

• Service status for MistServer, Helmsman, and Caddy
• HTTPS health check against your configured EDGE_DOMAIN

For enrollment and heartbeat status, check the dashboard—your node should appear under Infrastructure → Network once enrolled.

How Traffic Gets Routed

Once enrolled, Foghorn (the load balancer) knows about your node. When a viewer requests a stream:

1. Foghorn checks which nodes have the stream
2. GeoIP determines the viewer’s location
3. Scoring weighs node load, viewer proximity, and stream availability
4. Redirect sends the viewer to the best node (possibly yours)

Your node will receive traffic when:

• A stream is ingesting to your node
• Viewers are geographically closer to you than other edges
• Other edges are overloaded

Ingesting to Your Node

Streamers can push directly to your node instead of the default ingest. Direct ingest requires MistServer ports to be exposed on the host. The default Docker edge template publishes only 80/443, so expose the non-HTTP ports in your deployment before using direct RTMP/E-RTMP/SRT/RTSP ingest.

Open/forward as needed:

• 1935/tcp (RTMP/E-RTMP ingest)
• 8889/udp (SRT ingest)
• 5554/tcp (RTSP)

Caddy listens on 80/443. After ConfigSeed activation, Helmsman rewrites Caddy so HTTP viewer traffic is proxied to MistServer on 8080.

Direct RTMP/E-RTMP ingest:

rtmp://stream.yourdomain.com:1935/live/{stream-key}

Or use the network’s default ingest and let Foghorn route:

rtmps://edge-ingest.frameworks.network:1935/live/{stream-key}

Both work. Direct ingest means lower latency to your node; network ingest means Foghorn picks the best ingest point.

Capacity and Capabilities

Your node advertises what it can do. Set these in your edge environment file, and pass them through to the helmsman container (add them to helmsman.environment or use env_file in your edge compose file):

# In your edge environment file
HELMSMAN_CAP_INGEST=true    # Can receive RTMP/E-RTMP/SRT streams
HELMSMAN_CAP_EDGE=true      # Can serve viewers
HELMSMAN_CAP_STORAGE=true   # Can store recordings
HELMSMAN_CAP_PROCESSING=true # Can transcode

Disable capabilities you don’t want:

# Viewer-only node (no ingest)
HELMSMAN_CAP_INGEST=false

# Ingest-only node (no viewers)
HELMSMAN_CAP_EDGE=false

Removing a Node from the Network

To stop receiving network traffic:

cd /opt/frameworks-edge
docker compose -f docker-compose.edge.yml down

When Helmsman stops, Foghorn stops receiving heartbeats. Foghorn’s health sync reports only nodes seen alive within the last 90 seconds, so stale nodes are excluded from routing while their registry entry is retained.

Troubleshooting Enrollment

“Invalid token”

The token was already used or expired. Get a fresh one.

“Network unreachable”

Your server can’t reach the control plane. Check firewalls, DNS, and outbound HTTPS.

“Node already enrolled”

This usually means the node already has an identity. You can just start the stack again—no re‑enrollment required. If you need to move the node to a different cluster, revoke the old token, create a new one, and enroll again.

Node shows offline in dashboard

Helmsman isn’t sending heartbeats.

# Check Helmsman logs
frameworks edge logs helmsman --tail 50

Next Steps

Your node is connected. Learn how to manage it day-to-day.