Reference

Command line

NGCP has three programs: ngcp-controller (the panel), ngcp-agent (the node agent) and ngcpctl (administration helpers). The packages install the first two as services; you rarely need the command line, but everything can be done with it.

Every program prints its commands with help and its build with version.

ngcp-controller

ngcp-controller <command> [flags]

Command	Does
`serve`	Runs the controller (the default when no command is given). With `-config` pointing at a `controller.env` without a database URL, it serves the first-run setup.
`setup-url`	Prints the setup page address with its token (only before the setup is finished).
`service install\|uninstall\|start\|stop\|status`	Windows only: manages the NGCP Controller service. Accepts `-config`. On Linux the package installs the systemd unit.
`uninstall-builtin-db`	Windows: removes the built-in PostgreSQL service registration (the MSI runs this on uninstall; the data stays).
`openapi`	Prints the OpenAPI 3.1 document.
`gamedef-schema`	Prints the game definition JSON Schema.
`version`	Prints build information.

serve flags

Each flag has an environment variable, which can also be set in controller.env. The environment wins over the file; flags win over both.

Flag	Environment	Default	Meaning
`-config`	`NGCP_CONFIG`	Windows `C:\ProgramData\NGCP\Controller\controller.env`, Linux `/etc/ngcp/controller.env`	Configuration file
`-listen`	`NGCP_LISTEN`	`127.0.0.1:8080`	HTTP listen address
`-public-url`	`NGCP_PUBLIC_URL`	`http://<listen>`	URL browsers and agents use
`-grpc-listen`	`NGCP_GRPC_LISTEN`	`127.0.0.1:8443`	AgentLink listen address
`-grpc-advertise`	`NGCP_GRPC_ADVERTISE`	from `-grpc-listen` (the host name for `0.0.0.0`)	`host:port` agents dial
`-grpc-hostnames`	`NGCP_GRPC_HOSTNAMES`		Extra names / IPs for the AgentLink certificate
`-database-url`	`NGCP_DATABASE_URL`		PostgreSQL URL
`-auto-migrate`	`NGCP_AUTO_MIGRATE=true`	off (setup turns it on)	Apply migrations at start
`-cookie-secure`	`NGCP_COOKIE_SECURE`	`auto`	`auto`, `always`, `never`
`-trusted-proxies`	`NGCP_TRUSTED_PROXIES`		CIDRs whose `X-Forwarded-For` is trusted
`-ws-origins`	`NGCP_WS_ORIGINS`		Extra origins allowed on `/ws`
`-agent-releases-dir`	`NGCP_AGENT_RELEASES_DIR`	the package’s `share/agent-releases`	Agent builds: `<version>/<os>_<arch>/ngcp-agent[.exe]`
`-log-level`	`NGCP_LOG_LEVEL`	`info`	`debug`, `info`, `warn`, `error`

Environment only:

Variable	Meaning
`NGCP_MASTER_KEY` / `NGCP_MASTER_KEY_FILE`	The master key, or the file holding it (required)
`NGCP_TLS_CERT_FILE`, `NGCP_TLS_KEY_FILE`	Serve HTTPS with these PEM files
`NGCP_LOG_FILE`	Also log to this file
`NGCP_PACKAGES_DIR`	Agent packages for the one-line installers
`NGCP_PGSQL_DIR`	Windows: the bundled PostgreSQL folder (default: `pgsql` next to the program)

Example:

ngcp-controller serve -listen 0.0.0.0:8080 -public-url https://panel.example.com \
  -grpc-listen 0.0.0.0:8443 -grpc-advertise panel.example.com:8443

ngcp-agent

ngcp-agent <command> [flags]

Every command accepts --data-dir (default C:\ProgramData\NGCP or /var/lib/ngcp).

Command	Does
`enroll`	Enrolls this machine as a node.
`run`	Runs the agent in the foreground (the service runs this). Waits until the node is enrolled.
`service install\|uninstall\|start\|stop\|status`	Manages the NGCP Agent Windows service or the `ngcp-agent` systemd unit. Needs Administrator / root. `install` also starts it.
`paths`	Prints the default services and data directories for this OS.
`testgame`	Runs the built-in test game server (used by the NGCP test game definition).
`version`	Prints build information.

enroll flags

Flag	Required	Meaning
`--controller`	yes	The panel’s URL, e.g. `https://panel.example.com`
`--token`	yes	The one-time token (`ngcpe_...`)
`--ca-hash`	yes	`sha256:...` shown with the token
`--services-dir`	no	Where game servers are installed (default `C:\ngcp\services` / `/opt/ngcp/services`)
`--force`	no	Replace an existing enrollment
`--data-dir`	no	Where `agent.yaml`, the certificate and the key are stored

sudo ngcp-agent enroll --controller https://panel.example.com --token ngcpe_... --ca-hash sha256:...

run flags

Flag	Meaning
`--data-dir`	Data directory
`--unisolated`	Development only. Runs game servers as the agent’s own user without per-service accounts, limits or firewall rules. Never use it on a real node.
`--dev-fake-steamcmd`	Development only, with `--unisolated`: a SteamCMD stand-in that downloads nothing.

Agent settings beyond the command line live in agent.yaml; see Adding a node.

Exit code 3

After a self-update the agent exits with code 3 so its service manager starts the new binary. That is expected.

ngcpctl

ngcpctl works directly on the database. Database commands read NGCP_DATABASE_URL unless -database-url is given.

Command	Does
`migrate`	Applies database migrations. `-status` only reports the schema version.
`create-admin`	Creates a SuperAdmin account.
`gen-master-key`	Prints a new random master key (for `NGCP_MASTER_KEY`).
`create-enroll-token`	Issues a one-time node enrollment token. Needs the master key too.
`version`	Prints build information.

export-gamedefs, import-gamedefs and rotate-ca are listed but not implemented yet; they answer “not yet”. Use the panel or the API to manage game definitions.

create-admin

Flag	Default	Meaning
`-email`	(required)	E-mail address
`-username`	`admin`	User name
`-name`		Display name
`-password-stdin`	off	Read the password from the first line of standard input (for scripts); otherwise it asks twice on the terminal
`-database-url`	`NGCP_DATABASE_URL`	Database

printf '%s\n' "$ADMIN_PASSWORD" | ngcpctl create-admin -email [email protected] -username admin -password-stdin

create-enroll-token

Flag	Default	Meaning
`-datacenter`	(required)	Datacenter name; must exist unless `-create-datacenter`
`-create-datacenter`	off	Create the datacenter if missing
`-node`	(required)	The name the node will get
`-ttl`	`1h`	Validity, at most `168h`
`-controller-url`	`NGCP_PUBLIC_URL`	URL put into the printed commands
`-json`	off	Print JSON (token, CA hash, commands) for scripts
`-database-url`	`NGCP_DATABASE_URL`	Database

export NGCP_DATABASE_URL=postgres://ngcp:[email protected]:5432/ngcp
export NGCP_MASTER_KEY_FILE=/etc/ngcp/master.key
ngcpctl create-enroll-token -datacenter Default -node game-02 -ttl 2h -controller-url https://panel.example.com

On a packaged Linux controller with the built-in database, run it as the ngcp user so peer authentication works, with the URL from /etc/ngcp/controller.env.