Node CLI

The FrameWorks CLI provides commands for monitoring status, viewing logs, and managing the lifecycle of your edge services.

Status

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

Shows:

Health of the single frameworks-edge container in container mode, or systemd/launchd status in native mode
HTTPS health check against your configured domain

Logs

# All services, follow mode
frameworks edge logs --follow --dir /opt/frameworks-edge

# Specific container (positional argument)
frameworks edge logs helmsman --tail 100 --dir /opt/frameworks-edge

# Multiple options
frameworks edge logs --follow --tail 50 --dir /opt/frameworks-edge

Service names: mistserver, helmsman, caddy (the proxy service)

Updates

Updating the CLI

# Check for updates
frameworks update --check

# Update to the latest version
frameworks update

Updating Edge Services

Update/restart the deployed edge services:

frameworks edge update --dir /opt/frameworks-edge

In container mode this:

Pulls a new edge image from the registry
Recreates the frameworks-edge container
Preserves configuration, binaries, and data (named volumes; on Ansible-provisioned nodes hot storage is the storage/ directory next to the compose file)

In native mode, edge update restarts the native services. In both modes, day-to-day component convergence (Helmsman/MistServer/Caddy versions) is driven by the control plane’s release reconciler — edge update is the coarse image/service refresh, not the update mechanism.

Check current version:

frameworks version

Certificates

Check TLS status:

frameworks edge cert --dir /opt/frameworks-edge

Shows certificate expiration and issuer. In token-provisioned edge deployments, Foghorn can push renewed TLS material through ConfigSeed and Helmsman reloads Caddy. If Caddy needs to reload local certificate state:

# Reload Caddy to pick up new certificates
frameworks edge cert --reload --dir /opt/frameworks-edge

Operational Mode

Use node mode when you want Foghorn to stop sending new traffic without fully stopping the services. This command talks to Helmsman’s local HTTP API: directly on native nodes, and by exec’ing into the frameworks-edge container on container nodes — no ports need to be exposed for it.

# Show current mode
frameworks edge mode

# Stop new sessions and let existing work drain
frameworks edge mode draining --reason maintenance

# Return to normal routing
frameworks edge mode normal

Mode changes are requested through Helmsman and validated by Foghorn, which pushes the authoritative mode back through ConfigSeed.

Restarting Services

For container deployments:

cd /opt/frameworks-edge

# Restart the edge container (caddy/mistserver/helmsman run inside it)
docker compose -f docker-compose.edge.yml restart edge

Stopping the Node

For container deployments, stop the stack:

docker compose -f docker-compose.edge.yml stop

Bring down the stack:

docker compose -f docker-compose.edge.yml down

Start again:

docker compose -f docker-compose.edge.yml up -d

Diagnostics

Full health check:

frameworks edge doctor --dir /opt/frameworks-edge

Runs:

Host checks (ports, DNS, sysctls)
Service status
HTTPS reachability
Remediation hints

Network diagnostics:

# Check connectivity to control plane
frameworks context check

# Inspect Helmsman's gRPC connection to Foghorn (any dial errors land here)
frameworks edge logs helmsman --tail 100

Resource Usage

For container deployments (the single edge image), check what your node is using:

docker stats frameworks-edge

MistServer’s control interface binds loopback inside the container. On Linux (host networking) it is reachable from the host’s loopback; on macOS exec into the container:

# Linux
curl http://localhost:4242/api/stats
# macOS
docker exec frameworks-edge curl -s http://localhost:4242/api/stats

Helmsman exposes Prometheus metrics when its local HTTP API is reachable:

curl http://localhost:18007/metrics

Configuration Changes

Most config lives in .edge.env. After editing a container deployment:

cd /opt/frameworks-edge

# Apply changes by restarting
docker compose -f docker-compose.edge.yml restart

Changes that require restart:

Capability toggles
Foghorn endpoints / enrollment token
Storage configuration

Changes that take effect immediately:

Most MistServer settings via its API

Backup and Recovery

What to backup (container mode): the whole project directory — it carries the node’s identity and secrets:

.edge.env - Configuration (node identity, domain, control-plane address)
.edge-enroll.env - Write-once enrollment token file
.edge-secrets.env - MistServer API password (0600)
pki/ - Internal CA bundle for the Foghorn gRPC connection
telemetry/ - Telemetry token (when telemetry is enabled)
docker-compose.edge.yml (or docker-compose.yml on Ansible-provisioned nodes)

The named volumes (frameworks_opt, frameworks_etc, caddy_etc, caddy_data) hold binaries, certs, and the activated Caddyfile. You do not need to back them up for identity: binaries reseed from the image and converge via the release reconciler, and certs and stream config re-arrive over ConfigSeed after the node reconnects.

Hot storage (DVR/clip artifacts) differs by setup: local edge init renders use the edge_storage named volume, while Ansible-provisioned nodes bind the storage/ directory next to the compose file (kept from the earlier layout so migrated nodes retain their artifacts). Back it up — the volume or the directory respectively — only if you must preserve local DVR/clip artifacts across the move.

Recovery:

Install Docker on the new host (container mode)
Run frameworks edge preflight
Restore the saved project directory (env files, pki/, telemetry/, compose file) — do not re-run edge init, which would mint a new node identity and secrets
Start with frameworks edge enroll --dir .
Certificates, stream config, and component versions converge from the control plane after enrollment

Common Tasks

Change node capacity

Edit .edge.env:

HELMSMAN_MAX_TRANSCODES=10

Then restart the edge container:

docker compose -f docker-compose.edge.yml restart edge

Disable ingest temporarily

# Edit .edge.env
HELMSMAN_CAP_INGEST=false

# Restart
docker compose -f docker-compose.edge.yml restart edge

Foghorn will stop routing new ingest to this node.

Check active streams

curl http://localhost:4242/api/streams

Or via the dashboard under Nodes → [your node].

Clear hot storage

Helmsman’s cleanup monitor and the control plane’s DVR reclaim already evict by watermark; manual clearing is for emergencies. In container mode, hot storage is mounted at /data/storage (the edge_storage named volume on local edge init renders, the storage/ host directory on Ansible-provisioned nodes):

# Check usage
docker exec frameworks-edge du -sh /data/storage

# Remove old artifacts (careful — bypasses Foghorn's segment accounting!)
docker exec frameworks-edge find /data/storage -mtime +30 -delete

Native mode keeps hot storage at /var/lib/frameworks/edge-storage on the host.

Automation

For multiple nodes, consider:

Ansible playbooks using the CLI commands
Docker Swarm or Kubernetes (bring your own manifests)
Custom scripts wrapping frameworks edge commands

Example health check script:

#!/bin/bash
cd /opt/frameworks-edge
if ! docker compose -f docker-compose.edge.yml ps | grep -q "Up"; then
  echo "Containers not running, attempting restart"
  docker compose -f docker-compose.edge.yml up -d
fi