Self-hosting

Configuration

Every flag flockdeck-relay serve takes, with the environment variable that does the same thing where one exists. A flag wins over its environment variable if both are set.

Network and TLS

Flag	Env	Default	What it does
`-addr`		`:8080` (`:443` with `-acme-domain`)	Address to listen on.
`-public-url`	`FLOCKDECK_RELAY_PUBLIC_URL`		The address people open, at the root of its host. Required, except with `-acme-domain`, where it defaults to `https://` plus that domain. Must be `https://` when the relay serves TLS itself.
`-trust-proxy`		off	Take the client address from `X-Forwarded-For` instead of the TCP connection. Only turn this on when every request comes through a proxy that sets it: any client can write the header, and a relay serving TLS itself (`-acme-domain` or `-tls-cert`) logs a warning if it is set.
`-acme-domain`			Domain to get a certificate for automatically, and any other names the relay answers to, comma-separated after it. Requires the relay to be reachable on port 80 and 443 directly. One name has to be the host of `-public-url`. Not with `-tls-cert`, and not with `-desk-domain`.
`-acme-email`			Contact address for the ACME account. Does nothing without `-acme-domain`, and is refused if set without it.
`-http-addr`		`:80`	With `-acme-domain`, the address answering ACME challenges and redirecting to https. Does nothing without `-acme-domain`, and is refused if set without it.
`-tls-cert` / `-tls-key`			Your own certificate and key, which go together. Reloaded automatically when the files change.
`-client-dir`			Serve the remote client from this directory instead of the one built into the relay.
`-desk-domain`	`FLOCKDECK_RELAY_DESK_DOMAIN`		Base domain for giving each paired desktop its own origin, `https://<hostId>.<domain>/`. Needs a wildcard DNS record and certificate, which `-acme-domain` cannot get: give the relay one with `-tls-cert`/`-tls-key`, or terminate TLS in front of it. Without it, each desktop is reached at `/h/<hostId>/` on `-public-url` itself, which puts every desktop of an account on one origin.
`-admin-addr`		`127.0.0.1:8081`	Loopback address for the admin endpoints `flockdeck-relay invite`, `stats`, `plan`, `user revoke` and `audit export` use. See Admin and invites. Empty turns them off.

Storage

Flag	Env	Default	What it does
`-data`		`data`	Directory for the embedded database and the admin token file.
`-database`	`FLOCKDECK_RELAY_DATABASE_URL`		MySQL DSN, in place of the embedded database. See Storage and data.
`-database-ca`	`FLOCKDECK_RELAY_DATABASE_CA`		A file path for the flag, or the PEM text itself in the environment variable. Refused without `-database`.

Registration and limits

Flag	Default	What it does
`-registration`	`open`	Who may create a new account: `open`, `invite` (needs an invite code from an admin, see Admin and invites), or `closed`. A desktop joining an existing account with a join code from `flockdeck remote pair -desktop` is always allowed.
`-max-hosts`	10	Maximum number of desktops per account (0: no limit).
`-max-devices`	20	Maximum number of paired phones/browsers per account (0: no limit).
`-max-pairings`	5	Unused pairing codes an account can hold at once; a new one replaces the oldest (0: no limit).
`-pairing-ttl`	10m	How long a pairing or join code, in a link or QR code, stays valid. More than 0.
`-session-ttl`	720h (30 days)	How long a device stays paired without being used, before it has to pair again. More than 0.
`-max-streams`	256	Connections open to one desktop at once. More than 0.
`-account-retention`	2160h (90 days)	How long an account may go unused before it is deleted with its desktops and devices, unless it has a subscription. On every relay. At least 24h: a value above 0 and under 24h is refused at start. 0 keeps accounts for good. See Storage and data.
`-register-per-hour`	5	Accounts made, and join codes that don't work, per client address per hour (0: no limit).
`-pair-per-minute`	10	Pairing attempts per client address per minute (0: no limit).
`-connects-per-minute`	60	Desktop tunnels opened with a token that doesn't work, per client address per minute (0: no limit).
`-tunnels-per-address`	20	Maximum desktops connected from one address at once (0: no limit).
`-max-tunnels`	1000	Maximum desktops connected to the relay at once (0: no limit).
`-log-level`	`info`	`debug`, `info`, `warn` or `error`.
`-memory-limit`	none	A soft limit on the memory the relay uses, taken from the `GOMEMLIMIT` environment variable when the flag is not given, and written as it is, for example `220MiB`: nearing it, the garbage collector works harder.

Verified registration

Flag	Env	Default	What it does
`-require-verified-registration`	`FLOCKDECK_RELAY_REQUIRE_VERIFIED_REGISTRATION`	off	Require a verified email, confirmed with a magic link, before `flockdeck remote enable` may create an account and start a trial. Needs a Postmark token and `-mail-from`.
`-mail-from`			The relay's own address verification emails are sent from, e.g. `verify@flockdeck.ai`. Needed with `-require-verified-registration`, and refused without it.
`-verify-email-per-hour`		5	Verification emails started or resent per client address per hour (0: no limit).
`-verification-ttl`		30m	How long someone has to click a verification email's link before it expires.

The Postmark server token itself is read only from FLOCKDECK_RELAY_POSTMARK_TOKEN. There is no flag for it, so it never appears in a process listing. -require-verified-registration refuses to start without both it and -mail-from set.

With it on, one email address has one account. A desktop that enrols with an address that already has an account joins that account, with its plan and its other desktops, instead of making a second account. The desktop prints an 8-character match code when it starts, and the page the emailed link opens asks for it, so only the person at that terminal can finish. Five wrong codes cancel the registration. A desktop from before match codes is refused at registration and has to be updated, or enrol with a join code instead. A closed relay joins nothing by email. The account's paired devices get a push notice when a desktop joins, and the address is emailed one.

The desktop app's command-palette dialog can't yet wait on a verification link, so it fails immediately on a relay set up this way; flockdeck remote enable and flockdeck remote move from a terminal open the link and wait for it instead. See Flockdeck Remote.

Push notifications

Flag	Env	What it does
`-vapid-private-key`	`FLOCKDECK_RELAY_VAPID_PRIVATE_KEY`	Private key for signing web push messages.
`-vapid-public-key`	`FLOCKDECK_RELAY_VAPID_PUBLIC_KEY`	The matching public key, which paired devices are given. Worked out from the private key when left out.

Generate a pair with:

flockdeck-relay vapid-keys

It prints FLOCKDECK_RELAY_VAPID_PUBLIC_KEY=… and FLOCKDECK_RELAY_VAPID_PRIVATE_KEY=… lines, and sends nothing anywhere. Keep the pair: a browser subscribed under one pair is sent nothing signed with another. The private key can also be given as -vapid-private-key (base64url or PEM), but the environment variable keeps it out of a process listing; the public key is worked out from the private one when left out.

Without these set, the relay still runs; paired devices just don't get push notifications.

Single sign-on

Flag	Env	What it does
`-oidc-issuer`	`FLOCKDECK_RELAY_OIDC_ISSUER`	Have everyone pairing a device sign in with this OpenID Connect issuer first, e.g. `https://example.okta.com`.
`-oidc-client-id`	`FLOCKDECK_RELAY_OIDC_CLIENT_ID`	The relay's client id at the identity provider.
`-oidc-client-secret-file`	`FLOCKDECK_RELAY_OIDC_CLIENT_SECRET`	File holding the relay's client secret at the identity provider, or, in the environment variable, the secret itself. There's no `-oidc-client-secret` flag, so it never has to appear in a process listing.
`-oidc-name`	`FLOCKDECK_RELAY_OIDC_NAME`	What the sign-in button calls the identity provider. The provider's own host by default.
`-oidc-email-domains`	`FLOCKDECK_RELAY_OIDC_EMAIL_DOMAINS`	Comma-separated email domains whose people may sign in. Anyone the provider signs in, by default.

-oidc-issuer needs a client id and a secret to go with it; either given without the other, or without -oidc-issuer, is a startup error. This is part of the relay itself, which is what Flockdeck Enterprise is: the licensed, supported, self-hosted relay, single sign-on included. See Overview.

Audit log

Flag	Default	What it does
`-audit`	off	Keep the audit log: who reached which desktop, from which device, and when. Never what was typed or shown.
`-audit-ip`	off	With `-audit`, also record the address each event came from. Refused without `-audit`.
`-audit-retention`	0 (for good)	With `-audit`, how long events are kept. Refused without `-audit`.

See Security and privacy for what the audit log does and doesn't capture.

An example

Behind a reverse proxy, with MySQL, registration by invite only, and push notifications on. The database address and the VAPID private key are set in the environment, so neither appears in a process listing; the public key is worked out from the private one.

export FLOCKDECK_RELAY_DATABASE_URL="flockdeck:$MYSQL_PASSWORD@tcp(db.internal:3306)/flockdeck_relay?tls=true"
export FLOCKDECK_RELAY_VAPID_PRIVATE_KEY="$VAPID_PRIVATE_KEY"
flockdeck-relay serve \
  -public-url https://relay.example.com \
  -addr 127.0.0.1:8080 \
  -trust-proxy \
  -registration invite