fake-ship-manager

A bash CLI for creating and managing fake Urbit ships on a single machine. Handles port assignment, tmux sessions, and Tailscale HTTPS proxying automatically.

Features

• Create, start, stop, and delete fake ships with one command
• Auto-assigns Ames + HTTP ports (no manual tracking)
• Each ship gets a dedicated tmux session
• Automatically wires up Tailscale Serve HTTPS for remote access
• Tracks all ships in a local JSON database (~/.fakeships.json)

Port Convention

Ship	Ames/HTTP	Tailscale HTTPS
~zod	8080	8443
~bus	8081	8444
~nec	8082	8445
next	8083	8446

Formula: tailscale_port = ames_port + 363 (mirrors the standard 80 → 443 offset)

Requirements

• Urbit binary (~/urbit/urbit or update URBIT_BIN in the script)
• tmux
• jq
• Tailscale (optional — skip if you don't need remote HTTPS access)

Install

cp ship ~/bin/ship
chmod +x ~/bin/ship

Make sure ~/bin is on your $PATH.

Usage

ship new zod          # Create and boot a new fake ~zod
ship start zod        # Start an existing ship
ship stop zod         # Gracefully stop a running ship
ship list             # List all ships with status + Tailscale URLs
ship attach zod       # Attach to the ship's tmux dojo session
ship rm zod           # Delete ship pier (with confirmation)
ship ports            # Show all port assignments
ship help             # Show help

Note: Skip the ~ prefix — zsh expands bare ~name before the script sees it. Use ship new zod or quoted ship new '~zod', not ship new ~zod.

Configuration

Edit the variables at the top of the script:

URBIT_BIN="$HOME/urbit/urbit"   # path to Urbit binary
SHIPS_DIR="$HOME"                # where piers are created
SHIPS_DB="$HOME/.fakeships.json" # ship registry
BASE_PORT=8082                   # first port for new ships
TAILSCALE_OFFSET=363             # tailscale_port = ames_port + offset
TAILSCALE_HOST="your-machine.tailnet.ts.net"

How It Works

Each fake ship gets:

• Ames UDP port for inter-ship networking
• HTTP TCP port (same number — no conflict since different protocols)
• tmux session named after the ship (e.g., zod, bus)
• Tailscale Serve entry for HTTPS access over your tailnet

Ships are booted with explicit --http-port to ensure deterministic port assignment. The registry (~/.fakeships.json) is the source of truth for all port and session metadata.