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:

• Container status in Docker 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 Docker mode this:

1. Pulls new images from the registry
2. Recreates containers with new images
3. Preserves configuration and data

In native mode, edge update restarts the native services. Release-target convergence for native components is driven by the control plane, not by pulling Docker images.

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, so it works for native deployments and Docker deployments where you have made that API reachable from the host.

# 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 Docker deployments:

cd /opt/frameworks-edge

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

# Restart specific container
docker compose -f docker-compose.edge.yml restart helmsman

Stopping the Node

For Docker deployments, stop the containers:

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 Docker deployments, check what your node is using:

docker stats mistserver helmsman edge-proxy

MistServer metrics are available on the MistServer control interface. In the default Docker template that port is not published on the host; expose it intentionally or query it from a shell that has access to the container network:

curl 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 Docker 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:

• .edge.env - Your configuration
• MistServer recordings (if enabled)
• Any custom Caddyfile modifications

Recovery:

1. Install Docker on the new host when recovering a Docker deployment
2. Run frameworks edge preflight
3. Run frameworks edge init --dir . to generate compose/Caddyfile
4. Copy your saved .edge.env into the directory
5. Start with frameworks edge enroll --dir .

Common Tasks

Change node capacity

Edit .edge.env:

HELMSMAN_MAX_TRANSCODES=10

Then restart Helmsman:

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

Disable ingest temporarily

# Edit .edge.env
HELMSMAN_CAP_INGEST=false

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

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 recordings storage

# Check usage
du -sh /var/lib/mistserver/recordings

# Remove old recordings (careful!)
find /var/lib/mistserver/recordings -mtime +30 -delete

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