Forge Mesh — Portable Deck (USB Edition)

Self-contained command deck you can run from a USB stick or extracted tarball without a system install.

Quick start

tar -xzf forge-mesh-portable-*.tar.gz
cd forge-mesh-portable-*
# Edit credentials and wallet before production use:
${EDITOR:-nano} data/config.json
./LAUNCH.sh

LAUNCH.sh starts the control plane on http://localhost:8989, opens your default browser, and uses ./data for SQLite, artifacts, and secrets.

Default login (change in data/config.json):

Username: admin
Password: changeme

Cloudflare Tunnel (optional sidecar)

Linux uses an external cloudflared process (AF_TUNNEL_EXTERNAL=1), not in-process tunneling.

Place your tunnel token in data/cloudflared-token.txt (single line, no quotes), or
Export AF_TUNNEL_TOKEN before launch.

LAUNCH.sh looks for cloudflared on PATH or in bin/cloudflared. When a token is present it starts the sidecar and sets AF_TUNNEL_EXTERNAL=1 for agents that honor that flag.

# Example
echo 'YOUR_CF_TUNNEL_TOKEN' > data/cloudflared-token.txt
./LAUNCH.sh

Skip browser auto-open (headless / SSH):

AF_NO_BROWSER=1 ./LAUNCH.sh

WireGuard mesh (optional, operator-managed)

When you control the network, WireGuard is preferred over Cloudflare: agents dial the deck on a private mesh without a public tunnel.

Forge Mesh does not auto-install WireGuard. Configure it on the deck host and enrolled agents yourself:

Install WireGuard (wireguard, wireguard-tools) on deck and agents.
Generate keys: wg genkey | tee privatekey | wg pubkey > publickey
Create /etc/wireguard/forge-mesh.conf (paths may vary):

[Interface]
PrivateKey = <deck-private-key>
Address = 10.66.0.1/24
ListenPort = 51820

[Peer]
# Example agent
PublicKey = <agent-public-key>
AllowedIPs = 10.66.0.2/32

Enable: sudo systemctl enable --now wg-quick@forge-mesh
Point agents at the deck WireGuard IP (e.g. http://10.66.0.1:8989) in summon URL or agent env — not localhost.

Triple-onion tier T9 (mTLS mesh join via WireGuard) assumes this overlay exists. See docs/PROBLEMS.md for limits.

Summon agents from this deck

With the deck listening (and reachable on your LAN or tunnel):

curl -fsSL http://localhost:8989/install.sh | sudo bash

Replace localhost with your tunnel hostname or WireGuard address when summoning remote hosts.

Layout

.
├── LAUNCH.sh              # Entry point (symlink to scripts/LAUNCH.sh)
├── scripts/LAUNCH.sh
├── bin/
│   ├── forge-mesh-server  # Included if built before pack-usb.sh
│   └── cloudflared      # Optional
├── data/
│   ├── config.json
│   ├── cloudflared-token.txt   # Optional (gitignore in real deployments)
│   └── forge-mesh.db           # Created on first run
└── README.md

Environment variables

Variable	Purpose
`AF_TUNNEL_TOKEN`	Cloudflare tunnel token (overrides file)
`AF_TUNNEL_EXTERNAL`	Set to `1` automatically when sidecar runs
`AF_NO_BROWSER`	Skip opening a browser
`AF_CONFIG`	Override config path (default `./data/config.json`)
`AF_DATA_DIR`	Data directory (default `./data`)
`AF_SERVER_BIN`	Path to `forge-mesh-server` binary
`AF_DECK_URL`	Browser URL (default `http://localhost:8989`)

Security notes

Change auth.basic_password and auth.fleet_secret before exposing the deck.
Do not commit data/cloudflared-token.txt or data/signing.key to version control.
USB copies carry your fleet secret — treat the stick like a key.

3.6 KiB Raw Blame History