Docs / Reference / Standalone mode

Standalone mode and config reference

A node runs without the panel from one config.yaml file and the ingressd CLI. Every apply is recorded in git, secrets are encrypted with age, and a managed node can leave the panel at any time.

Open source

The node, the edge build and the connector are licensed under Apache-2.0. Standalone mode needs no account.

Managed or standalone#

	Managed	Standalone
Config	Compiled by the panel, signed, pushed to the node	`config.yaml` on the node, edited by you
Several nodes per home	Yes, with failover DNS	One node per config
Access-policy emails	Sent by the panel	Your SES or SMTP account
Certificates	Shared between your nodes	Stored on the node

Both run the same binaries.

Start a standalone node#

On a node built from source (make build in the node repository), install the binaries and units, then create a starter config:

shellon the vps, as root

$ sudo ./deploy/install.sh bin
$ ingressd init
$ ingressd validate
$ ingressd apply

ingressd init creates the config directory, an age key for secrets and a starter config.yaml, and records it in git. Back up the key: it decrypts secrets.age.

Commands#

Command	Does
`ingressd validate [-f file]`	Checks a config without applying it.
`ingressd diff`	Shows what `apply` would change.
`ingressd apply [-m message]`	Applies `config.yaml` and records it in git. `--dry-run` shows the diff only.
`ingressd history` / `ingressd rollback <revision>`	Lists applied changes; restores and applies an earlier one.
`ingressd serve`	Runs the node: applies at start and whenever `config.yaml` changes.
`ingressd secret set <name>`	Stores a secret, referenced in the config as `secret://name`.
`ingressd tunnel config <tunnel>`	Prints the WireGuard config to import on a router.
`ingressd tunnel enroll-token <tunnel> --join`	Creates a one-time join string for `ingressd-connector`.
`ingressd doctor`	Checks the host, config, DNS and tunnels.
`ingressd logs [-f]` / `ingressd stats`	Searches or follows access logs; traffic totals per host.
`ingressd export -o backup.tar.gz` / `ingressd restore`	Exports or restores config, secrets and history.
`ingressd node detach`	Leaves managed mode and keeps the config and secrets.
`ingressd import <config.yaml>`	Validates, writes and applies a config, for example one exported from the panel.

config.yaml#

The top-level sections:

Section	Holds
`edge`	Node name, public addresses, ACME account, GeoIP and CrowdSec settings.
`email`	How sign-in codes are sent: `ses`, `smtp` or `log`.
`access`	Portal host, session length and code limits.
`tunnels`	One per home: `site: router` or `site: connector`, listen port, transit `/30`.
`groups`, `policies`, `service_tokens`	Who may sign in to which app.
`apps`	HTTP apps: hostnames, origin or pool, TLS to the origin, WAF, bot challenge, rate limits, cache, Always Online.
`pools`	Several origins with health checks, steering and failover tiers.
`l4`	Game and TCP/UDP services.
`security`	Global IP, country and ASN deny lists.
`smartdns`, `mesh`	Smart DNS exits and services; the WireGuard mesh between nodes.
`alerts`, `logging`, `backups`	Notification channels, log retention, scheduled backups.

A small example:

config.yamlstandalone node

version: 1
edge:
  name: fra-1
  public_ipv4: 203.0.113.24
  acme: { email: you@example.net }
tunnels:
  home:
    type: wireguard
    site: router
    listen_port: 51820
    transit: 100.64.0.0/30
    public_key: "<router public key>"
apps:
  media:
    hosts: [media.example.net]
    origin: http://192.168.1.20:8096
    tunnel: home
    waf: { mode: block, paranoia: 1 }

The full annotated reference is examples/config.yaml in the node repository; it is validated in the node's tests, so it always matches the schema.

Moving between modes#

Managed to standalone: ingressd node detach on the node. It keeps serving with its current config and secrets.
Standalone to managed: enrol the node with ingressd node enroll --panel https://app.ingressd.com --token <token>. The panel's config replaces the local one.