113 lines
3.6 KiB
Markdown
113 lines
3.6 KiB
Markdown
# 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.
|