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
httpRedirect: true

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	Proxy host port. Defaults to 443 across all network modes
httpRedirect	boolean	Bind port 80 for HTTP→HTTPS redirect + certbot HTTP-01. Defaults to true; --no-http-redirect to disable
upgradeCheckEnabled	boolean	Poll /api/upgrade/check against the S3 channel pointer. Defaults to true
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
proxyHeader	header name	Custom header injected into proxy requests
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.

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