Configuration

DK Studio is configured in three layers: environment variables, configuration files in the working directory, and built-in defaults. This page introduces every variable and every file the platform reads, and how a change to each one takes effect.

The layers

Layer	Holds	Read
Process environment	`PORT`, `HOSTNAME`, `NODE_ENV`, `DATA_DIR`, `DASHBOARD_WS_TOKEN`, `ADMIN_CREATED` for the studio; `AGENT_PORT`, `AGENT_HOST`, `AGENT_DATA_DIR`, `NEXT_PUBLIC_DEFAULT_STUDIO_URL` for the agent.	At process start.
Configuration file	`.db-config.json`, `.studio-license.json`, `.setup-progress.json`, `.setup-complete` in the studio's working directory; `agent.json` in the agent's `AGENT_DATA_DIR`.	When the platform needs the value.
Built-in default	The default listed in the tables below.	When no variable and no file sets the value.

Where a value exists at more than one layer, the process environment wins over the configuration file, and the configuration file wins over the built-in default.

The studio serves the web UI, the REST API and the realtime socket from one process, so one set of variables and one working directory configure all three.

Studio environment

Variable	Default	Meaning
`PORT`	`3000`	The port the studio listens on.
`HOSTNAME`	`localhost`	The host name the studio reports for itself in the startup banner.
`NODE_ENV`	—	`production` marks the session cookie `secure`.
`DATA_DIR`	`./data`	Where the SQLite database file is created.
`DASHBOARD_WS_TOKEN`	—	The token the dashboard client presents on the socket connection.
`ADMIN_CREATED`	—	`"true"` skips the redirect to the setup wizard.

The studio's listener accepts every interface, so a browser on the network and an agent on a bench both reach it without a port forward. HOSTNAME names the host for the startup banner only; it is unrelated to the hostname reported by the get_system_info command. To keep the studio off the network, put an authenticating proxy in front of it and let only the proxy reach the port.

Agent environment

Variable	Default	Meaning
`AGENT_PORT`	`3001`	The port the agent's local page listens on.
`AGENT_HOST`	`127.0.0.1`	The interface to bind. The default keeps the page on the bench.
`AGENT_DATA_DIR`	`./data`	Where the agent keeps its registration record. Give each agent instance its own directory: the record is the agent's identity, and two instances sharing one overwrite each other.
`NEXT_PUBLIC_DEFAULT_STUDIO_URL`	`http://localhost:3000`	The studio address the agent's registration form starts with.
`NODE_ENV`	—	Set to `production` for a production run.

The agent's studio address and its display name are set during registration and stored in data/agent.json; NEXT_PUBLIC_DEFAULT_STUDIO_URL only fills the form in before registration.

Studio files

All four files live in the studio's working directory, the directory the server is started from.

`.db-config.json`

Written by the setup wizard's database step. It selects the driver and holds the connection details.

{
  "dbType": "sqlite",
  "database": "dkstudio",
  "initializedAt": "2026-10-21T07:33:50.876Z"
}

Field	Applies to	Meaning
`dbType`	all	`sqlite`, `postgresql` or `mysql`.
`host`	PostgreSQL, MySQL	The server address.
`port`	PostgreSQL, MySQL	The server port.
`username`	PostgreSQL, MySQL	The database user.
`password`	PostgreSQL, MySQL	The database password.
`database`	all	The database name, or the file name for SQLite.
`initializedAt`	all	When the wizard wrote the file.

The SQLite file is created at ${DATA_DIR}/<database>.db, where <database> is the database field of this file and the default file name is dkstudio.db.

The password is stored in plain text

The wizard writes the database password into this file without encrypting it. Keep the file readable only by the service account, and prefer a database user with the narrowest privileges that still works.

`.studio-license.json`

Written by the setup wizard's licence step. It is the platform's entitlement record.

{
  "edition": "enterprise",
  "licenseKey": "ENT0-DKST-UDIO-2026",
  "issuedAt": "2026-10-21T07:33:50.876Z",
  "expiresAt": null,
  "maxAgents": 999,
  "features": ["core", "agents", "analytics", "api", "advanced", "enterprise"]
}

Field	Meaning
`edition`	The edition the key selects.
`licenseKey`	The key itself.
`issuedAt`	When the licence was issued.
`expiresAt`	When the licence expires, or `null` for a licence without an end date.
`maxAgents`	The largest number of agents the licence entitles you to register.
`features`	The capabilities the licence grants.

`.setup-progress.json`

Records the step the wizard reached, so an interrupted setup can resume. It is cleared when the admin account is created.

{
  "currentStep": "database",
  "startedAt": "2026-10-21T07:30:00.000Z"
}

`.setup-complete`

A marker file. Its presence is what tells the studio that setup is done and it should serve the application rather than the wizard. It contains a completion timestamp.

The licence

A licence key has the form xxxx-xxxx-xxxx-xxxx. The first group is the edition prefix.

Edition	Prefix	`maxAgents`	`features`
starter	`STR0-`	3	`core`, `agents`
professional	`PRF0-`	10	`core`, `agents`, `analytics`, `api`
pro	`PR00-`	25	`core`, `agents`, `analytics`, `api`, `advanced`
enterprise	`ENT0-`	999	`core`, `agents`, `analytics`, `api`, `advanced`, `enterprise`

The platform enforces the licence. maxAgents is the number of agents the licence entitles you to register: a registration beyond that limit is refused. features gates the capabilities the licence grants.

ENT0-DKST-UDIO-2026 is the demo key. It selects the enterprise edition, carries maxAgents 999 and validates on every installation.

A licence is issued from the studio — a personal one from the Personal Center, a lab one from Admin → Licences — or with POST /api/licenses. The licence code is shown once, at issue. See API Reference.

`data/agent.json`

Written on the machine under test when the agent registers. This is the agent's entire identity. The file sits in AGENT_DATA_DIR, which defaults to data.

{
  "agentId": "0f2c…",
  "apiKey": "…32 alphanumeric characters…",
  "agentSecret": "…64 hex characters…",
  "name": "Bench 01",
  "studioUrl": "http://localhost:3000",
  "registeredAt": "2026-10-21T07:35:12.004Z"
}

Field	Meaning
`agentId`	The identifier the agent sends on every command and heartbeat.
`apiKey`	The secret presented to `POST /api/agent/auth`.
`agentSecret`	The credential presented over the socket.
`name`	The name shown in the studio.
`studioUrl`	The studio the agent connects to.
`registeredAt`	When the agent registered.

This file is a credential

It contains the API key and the agent secret in plain text. Restrict its permissions on the bench. Deleting it un-registers the agent locally; the studio keeps the agent row until you delete it.

Applying a change

Change	How it takes effect
An environment variable	Restart the process. The studio reads its environment once, at start-up.
`.db-config.json`	Restart the studio, or re-run the setup wizard's database step.
`.studio-license.json`	Restart the studio. The platform reads `maxAgents` and `features` from it.
`.setup-progress.json`, `.setup-complete`	Read by the setup middleware on the next request.
`data/agent.json`	Read by the agent at start-up. Restart the agent.

The agent dials the studio; the studio never dials the agent. A change to studioUrl is therefore applied on the agent, and a change to the studio's address is applied wherever the agents point at it.

Configuration

The layers

Studio environment

Agent environment

Studio files

.db-config.json

.studio-license.json

.setup-progress.json

.setup-complete