Configuration

norsk-ctl keeps its state in ~/.norsk-ctl/. Two files live there: a daemon config (config.yaml) that the server reads at boot, and a state database (norsk-ctl.db) that holds runtime state (instances, launch configs).

File	Who writes it	Purpose
~/.norsk-ctl/config.yaml	norsk-ctl init, config set	Daemon settings — network mode, TLS, public host
~/.norsk-ctl/norsk-ctl.db	The daemon	SQLite state (instances, launch configs). Do not edit by hand
~/.norsk-ctl/certs/	mkcert / self-signed pipelines	Generated cert + key. User-supplied / certbot certs live elsewhere

Override the store directory with NORSK_CTL_STORE_DIR (see Environment Variables).

Daemon config (config.yaml)

Written by norsk-ctl init and read by the daemon at startup. Example:

~/.norsk-ctl/config.yaml

networkMode: docker
defaultWorkingDirectory: /home/alice/norsk-data
certPath: /etc/norsk-ctl/tls/cert.pem
keyPath: /etc/norsk-ctl/tls/key.pem
certSource: certbot
publicHost: norsk.example.com
proxyPort: 443
externalPort: 443
httpRedirect: true
httpRedirectPort: 80

Fields

Field	Values	Description
networkMode	docker | hybrid	How containers are networked. See Network Modes
defaultWorkingDirectory	path	Default host directory holding plugins/, studio-save-files/, dashboards/
publicHost	host or host:port	Public hostname or IP. Baked into TLS cert SAN; advertised in per-instance URLs. Stored bare (no scheme — the scheme is derived from cert presence at read time)
proxyPort	port number	Host port the proxy binds. Defaults to 443 across all network modes
externalPort	port number	Port clients arrive on, when that isn’t proxyPort — i.e. when another reverse proxy fronts this box, publishing 443 and forwarding to us. Every advertised URL (the oauth2 sign-in redirect, each instance’s base URL) names this port instead of the bound one. Defaults to proxyPort
httpRedirect	boolean	Bind a port for the HTTP→HTTPS redirect + certbot HTTP-01. Defaults to true; --no-http-redirect to disable
httpRedirectPort	port number	Host port for that redirect listener. Defaults to 80; move it rather than dropping the redirect when 80 belongs to something else
upgradeCheckEnabled	boolean	Poll /api/upgrade/check against the S3 channel pointer. Defaults to true
spectrumCacheEnabled	boolean	Keep one Spectrum compile cache on the host, at cache/spectrum under the state dir, mounted into every media engine launched after the change. A video pipeline then compiles once per host instead of once per container start, which takes seconds off the first frames of every later start. ctl creates the directory owner-only, since Spectrum loads compiled code from it and refuses a directory anyone else could write to. Off, nothing is mounted and nothing is kept: each engine compiles from empty. For a host that must be left as found, turn it off and delete the directory. Defaults to true; config set --spectrum-cache on|off
norskdReadyTimeoutSeconds	integer, 1-600	How long a Norsk Domain’s daemon may take to announce READY when a launch brings it up. Defaults to 60; raise it on a heavily loaded host. Read at daemon start
containerUser	uid:gid	User/group containers run as (auto-detected on Linux)
excludedCores	number[]	CPU cores to keep out of the media container’s affinity set
smtPolicy	pairs | primary-only	How a cpuCount launch is given hyperthread siblings on a Linux host: whole physical cores (default) or one thread per core with the sibling left idle. norsk-ctl config set --smt-policy
certPath	path	TLS certificate file. Required
keyPath	path	TLS key file. Required
certSource	mkcert | self-signed | user | certbot	How the cert was provisioned. Influences renewal behavior

There is no license in config.yaml: the license is supplied when a product is registered (norsk-ctl product add --license-file <path> or --marketplace-provider <aws|gcp>) and stored on the product registration. Legacy licenseMode/licenseFile/marketplaceProvider keys in an old config.yaml are ignored.

proxyHeader is retired. It named a header the daemon accepted any non-empty value of, on the assumption that a fronting ingress had already authenticated the caller — which authenticates nobody. A config.yaml that still sets it is refused at boot rather than quietly downgraded to secret-required authentication, which would leave such a host open without anyone noticing. Remove the key. Support for an authenticating ingress returns as verified, signed assertions.

Caution

Don’t hand-edit config.yaml while the daemon is running. Use norsk-ctl config set <field> <value> (which writes through safely) or norsk-ctl init --force to reset. The Settings page in the web UI exposes runtime-editable fields.

CLI / daemon port

The CLI always talks to a daemon on the same machine. Default port is 8333. Override with --port <n> per-invocation, or set NORSK_CTL_PORT in the environment (honoured by both daemon and CLI).

Remote management happens through the web UI (behind the nginx + auth front door), not the CLI.

State database (norsk-ctl.db)

SQLite file. Holds:

• Instance records — every launched instance, its launch config (workflow, sidecars, image tags), and current status
• Other daemon-managed state — added forward-only via the migration framework in backend/src/lib/migrations.ts

Managed entirely by the daemon. Do not edit by hand. Schema changes go through forward-only migrations run at daemon startup; a failed migration aborts startup with a clear error.

To start fresh, stop the daemon and delete ~/.norsk-ctl/norsk-ctl.db (keeps your config) or all of ~/.norsk-ctl/ (resets everything). norsk-ctl init --force does the same plus rewrites the config.

See also

• Environment Variables — runtime overrides
• Ports — proxy port, daemon port, ingest ports
• Backup & Upgrade — what to preserve across binary upgrades