# 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

```bash
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.

1. Place your tunnel token in `data/cloudflared-token.txt` (single line, no quotes), **or**
2. 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.

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

Skip browser auto-open (headless / SSH):

```bash
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:

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

```ini
[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
```

4. Enable: `sudo systemctl enable --now wg-quick@forge-mesh`
5. 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):

```bash
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.