Command line

Mistgate has two binaries: mistgate is the panel, mistgate-node is the node agent. Both take a command and then flags. Flags can be written with one dash or two (-data-dir or --data-dir); this page uses two. <command> -h prints the flags of a command.

Many flags fall back to an environment variable. A flag given on the command line wins over the variable. Every flag and variable of serve and setup is also described, with the layout of the data directory, in Configuration.

mistgate#

mistgate exits with 0 on success, 1 on an error (printed as mistgate: <error>) and 2 for an unknown command or a missing one.

mistgate serve#

Runs the panel in the foreground. Run it under systemd or another supervisor. Outside development mode it needs an installation made by mistgate setup.

mistgate serve --listen :443 --acme-domain panel.example.com

Development mode. --dev uses ./.data, serves plain HTTP with the decoy on 127.0.0.1:8080 and the admin on 127.0.0.1:8081, puts the agent endpoint on 127.0.0.1:8082, uses localhost as the WebAuthn relying party, needs no setup, and prints a one-time setup link (http://localhost:8081/setup#…, valid 30 minutes) while no admin exists. Never use it on a server.

mistgate setup#

Prepares a new installation: creates the data directory (mode 0700), the master key and the database, stores where the admin is reached, and prints how to get there. It is safe to run again: an existing configuration is kept, and a new setup link is issued only while no admin exists (earlier unused links stop working).

mistgate setup --public-url https://panel.example.com

Data dir:   /var/lib/mistgate
Admin URL:  https://panel.example.com/<secret prefix>/
Setup link: https://panel.example.com/<secret prefix>/setup#<token>
The link works once and expires in 30 minutes. Open it in a browser and create your admin (a passkey, or a password with an authenticator code).

One of --public-url, --admin-host or --admin-listen is required. Where the admin ends up:

Setup also generates the secret TLS name of the agent endpoint and the secret prefix of the subscription links. These settings cannot be changed by running setup again.

mistgate auth#

Commands for the operator on the panel server. Both work with the panel stopped or running: it reads these settings on every request.

mistgate auth turnstile off [--data-dir DIR]
mistgate auth reset-login [<login>] [--admin ID] [--qr-invert] [--data-dir DIR]

auth turnstile off switches the Cloudflare check off on the sign-in and setup pages; the keys stay stored. It is the way back in when Cloudflare is unreachable or the keys are wrong. Switch it on again in Settings → Security.

auth reset-login is the way back in after a lost phone:

• mistgate auth reset-login lists the admins of the panel with their id, name, role, login and number of passkeys.
• mistgate auth reset-login <login> gives that login a new password and a new authenticator app, lifts its lockouts and ends every session of that admin. Passkeys stay.
• mistgate auth reset-login <new login> --admin <id> gives an admin who has passkeys only a password login (--admin picks which admin when there are several).

It prints the login, the new password, and the authenticator key as a QR code drawn in the terminal, as text in groups of four, and as an otpauth:// link. The password is shown only once. It needs the master key, so run it as the user that can read the data directory. Both commands are written to the audit log as "command line".

mistgate auth reset-login alice

mistgate mcp#

A local MCP server on stdin and stdout for agent clients that can only start a command. It forwards every message to the panel's MCP endpoint (the admin URL plus mcp) and decides nothing itself: the panel answers, with the token's profile.

mistgate mcp --url https://panel.example.com/<prefix>/ --token-file ~/.config/mistgate/token

The proxy stops when the panel refuses the token (expired, revoked or the wrong profile). stdout carries only protocol messages; everything else goes to stderr. See MCP.

mistgate release keygen#

mistgate release keygen --out ~/mistgate-release.key

Prints the public key and its fingerprint. Put the public key into the build: RELEASE_KEY=<public key> make build. Keep the key file offline and back it up. See Updates.

mistgate release sign#

mistgate release sign --key FILE --version V --built UNIX [--expires 30d] BINARY... --out DIR

The binaries are named <name>-<os>-<arch>, for example mistgate-node-linux-amd64. Flags may come after the binaries. The command verifies what it wrote and prints every file with its size and the key fingerprint. Copy the directory to <data-dir>/dist on the panel.

mistgate release sign --key ~/mistgate-release.key \
  --version "$(git describe --tags --always)" \
  --built "$(git log -1 --format=%ct)" --expires 30d \
  bin/mistgate-node-linux-amd64 bin/mistgate-node-linux-arm64 --out dist/

mistgate version#

Prints mistgate <version>, then built <time> when the binary was built with a build time, then release key <fingerprint>, or release key: none (unsigned build, nodes are updated by hand).

mistgate-node#

enroll and run take --state-dir; give them the same directory. Exit codes: 0 success, 1 an error, 2 bad usage, 78 from run when the node is not enrolled (systemd does not restart the agent then).

The panel shows the whole install command when you add a node:

chmod +x /root/mistgate-node && /root/mistgate-node enroll --panel panel.example.com:443 --sni <secret name> \
  --ca-sha256 <fingerprint> --token <one-time token> && /root/mistgate-node install

mistgate-node enroll#

The first four are required. A token works once, within the time the panel showed (an hour by default). On success it prints the node id and the next step:

enrolled as nod_… with panel.example.com:443; state in /var/lib/mistgate-node
next: mistgate-node install   (or, in the foreground: mistgate-node run)

mistgate-node install#

Linux only, as root, after enroll.

It writes /etc/systemd/system/mistgate-node.service, then runs systemctl daemon-reload, enable and restart. The unit:

• runs the agent as root with only two capabilities (network administration and binding low ports) and a read-only system, except the state directory, the binary's directory (for self-update), /etc/sysctl.d and /etc/systemd/journald.conf.d;
• sizes its memory limits from the server's RAM;
• restarts the agent 5 seconds after a failure, but not after exit code 78;
• before every start, puts the previous binary back after a crash loop of a fresh update; after every stop, runs cleanup-net.

Running install again with a new binary is how a node is updated by hand (see Updates). Paths may contain only letters, digits and _ . / -.

mistgate-node run#

Runs the agent in the foreground: what the unit does, and a way to try the agent without systemd.

It exits with 78 when the state directory holds no identity, and with 0 when the panel retired the node.

mistgate-node cleanup-net#

Takes no arguments. Removes the tunnel interfaces of the agent, its tunnel nftables table and, when present, the WARP device, routes, rules and table. It needs no state and no panel. The unit runs it after every stop; the agent creates everything again when it starts.

mistgate-node awg prepare-kernel#

Puts the AmneziaWG kernel module on the node. Linux only, as root. The default userspace backend needs no module.

mistgate-node awg prepare-kernel          # prints the plan, runs nothing
mistgate-node awg prepare-kernel --yes    # runs it

It installs packages with apt (non-interactive, waiting for another package manager's lock). Supported: Debian and Ubuntu, not a container, without Secure Boot, with systemd. See AmneziaWG.

mistgate-node version#

Prints mistgate-node <version>, built <unix time>, and release key <fingerprint> or release key none (unsigned build: update by hand).