@moxxy/provisioner

Provisioner agent for Moxxy Cloud. Manages moxxy gateway instances on a host machine — creating Linux users, allocating ports, managing systemd services, and reporting back to Convex.

Install it on any machine to add capacity to your Moxxy Cloud deployment.

Quick Start: Add a New Machine

Prerequisites: Ubuntu 22.04+ or Debian 12+, root access, DNS configured.

1. Generate a connection token (on an existing machine)

On any machine that's already connected to your Moxxy Cloud deployment:

moxxy-provisioner connect-token
# Output: mxc_eyJjb252ZXhVcm...  (single string containing Convex URL + auth token)

This token is a secret — it contains your Convex credentials. Share it over a secure channel.

If you don't have an existing machine yet, run moxxy-provisioner init without a token and fill in CONVEX_URL and MACHINE_AUTH_TOKEN manually (see Configuration).

2. Set up and connect the new machine

# Install the provisioner
npm i -g @moxxy/provisioner

# Prepare the machine (installs Caddy, Node.js, firewall, provisioner user)
sudo moxxy-provisioner setup

# Initialize .env with the connection token (pre-fills Convex URL + auth)
moxxy-provisioner init <connection-token>

# Set the machine's public IP (the only manual edit needed)
nano /opt/moxxy-provisioner/.env
# -> Set MACHINE_PUBLIC_IP=<this machine's IP>

# Generate SSH keypair (for web terminal feature)
sudo moxxy-provisioner generate-ssh-keys

# Configure Caddy reverse proxy
sudo moxxy-provisioner setup-caddy cloud.moxxy.ai

# Install and start the provisioner service
sudo moxxy-provisioner install

# Verify
moxxy-provisioner status

The machine registers itself with Convex on startup and begins accepting provisioning tasks automatically.

How It Works

                    Convex (cloud database)
                           |
            +------- poll tasks -------+
            |                          |
   Machine A                    Machine B
   (web/api + provisioner)      (provisioner only)
   cloud.moxxy.ai -> web       npm i -g @moxxy/provisioner
   api.cloud.moxxy.ai -> API   Caddy proxies *.cloud.moxxy.ai
   instances :3001-3999         instances :3001-3999

Each provisioner agent:

• Registers the machine with Convex on startup
• Sends heartbeats every 30s
• Polls for pending tasks every 5s (provision, deprovision, configure, upgrade, restart)
• Claims tasks atomically (no double-processing across machines)
• Reports instance health every 60s

Commands

Getting Started

| Command | Description | |---------|-------------| | sudo moxxy-provisioner setup | Install system deps, Caddy, firewall, provisioner user | | moxxy-provisioner connect-token | Generate a connection token (run on existing machine) | | moxxy-provisioner init <token> | Initialize .env from a connection token | | moxxy-provisioner init | Initialize .env with blank template (manual setup) | | sudo moxxy-provisioner install | Install systemd service and start the agent | | sudo moxxy-provisioner setup-caddy <domain> | Configure Caddy reverse proxy |

Service Management

| Command | Description | |---------|-------------| | sudo moxxy-provisioner start | Start the provisioner service | | sudo moxxy-provisioner stop | Stop the provisioner service | | sudo moxxy-provisioner restart | Restart the provisioner service | | moxxy-provisioner status | Show service status and machine info | | moxxy-provisioner logs [-f] [-n 100] | View provisioner logs | | sudo moxxy-provisioner uninstall | Remove the systemd service |

Utilities

| Command | Description | |---------|-------------| | moxxy-provisioner generate-tokens | Generate MACHINE_AUTH_TOKEN and MASTER_ENCRYPTION_KEY | | moxxy-provisioner generate-ssh-keys [dir] | Generate Ed25519 SSH keypair | | moxxy-provisioner agent | Run the agent in the foreground (for development) |

Configuration (.env)

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | CONVEX_URL | Yes | - | Convex deployment URL | | MACHINE_AUTH_TOKEN | Yes | - | Shared secret (must match Convex dashboard) | | MACHINE_HOSTNAME | No | OS hostname | Machine identifier in Convex | | MACHINE_PUBLIC_IP | Yes | - | Public IP for DNS routing | | AGENT_ID | No | hostname | Unique agent ID | | MAX_INSTANCES | No | 100 | Max instances on this machine | | PORT_RANGE_START | No | 3001 | First port for instances | | PORT_RANGE_END | No | 3999 | Last port for instances | | SSH_PUBLIC_KEY_PATH | No | .../keys/cloud_ed25519.pub | SSH public key for terminal proxy | | MOXXY_SHARED_BIN_DIR | No | /opt/moxxy-provisioner/bin | Shared binary directory | | MOXXY_BINARY_RELEASE_TAG | No | latest | Gateway binary version | | MOXXY_BINARY_URL | No | - | Override download URL (air-gapped environments) |

Multi-Machine Architecture

Machine with Web/API + Provisioner (primary)

Your first machine typically runs everything: web app, API server, and provisioner. This is set up by the monorepo's scripts/deploy.sh.

Provisioner-Only Machines (additional capacity)

Additional machines only need the provisioner. Install @moxxy/provisioner globally and follow the quick start above. Key points:

• No web/api — those stay on the primary machine
• Same CONVEX_URL — all machines talk to the same Convex deployment
• Same MACHINE_AUTH_TOKEN — shared secret for authentication (set in Convex dashboard)
• Unique MACHINE_HOSTNAME — each machine needs a distinct name
• DNS — *.cloud.moxxy.ai must resolve to each machine that hosts instances

DNS for Multi-Machine

For multiple machines hosting instances:

1. DNS round-robin: Add multiple A records for *.cloud.moxxy.ai pointing to each machine IP
2. Load balancer: Route by subdomain to the correct machine
3. Separate subdomains: Use *.us1.moxxy.ai, *.eu1.moxxy.ai per machine/region

Caddy on each machine handles TLS for the subdomains it serves.

Upgrading

npm update -g @moxxy/provisioner
sudo moxxy-provisioner restart

Development (monorepo)

When working within the monorepo, the provisioner runs as a workspace package:

# From monorepo root
bun install
bun dev:provisioner   # runs with --watch

The monorepo scripts/deploy.sh handles the full deployment (web + api + provisioner) to the primary machine. For additional machines, use the npm package.

Troubleshooting

Service won't start

• Check .env exists: cat /opt/moxxy-provisioner/.env
• Check logs: moxxy-provisioner logs -f
• Check the agent directly: moxxy-provisioner agent (runs in foreground)

Caddy TLS issues

• Verify DNS: dig cloud.moxxy.ai and dig test.cloud.moxxy.ai
• Validate config: caddy validate --config /etc/caddy/Caddyfile
• Check logs: journalctl -u caddy -e

Provisioner can't connect to Convex

• Verify CONVEX_URL in .env
• Check MACHINE_AUTH_TOKEN matches Convex dashboard
• Check logs: moxxy-provisioner logs

Instance not reachable

• Check Caddy routes: cat /etc/caddy/instance-routes.conf
• Check instance service: systemctl status moxxy-<shortId>
• Check instance health: curl http://127.0.0.1:<port>/v1/health