Installation

DK Studio ships as one repository with five applications. Two of them make up a working system: the studio, which serves the web platform, and the agent, which runs once on each machine under test. This page takes you from an empty machine to a running studio with a first admin account.

Prerequisites

Requirement	Version
Node.js	24 or newer (`engines.node` in the root `package.json`)
pnpm	11.x
A database	SQLite by default; PostgreSQL or MySQL are supported
Bash	`/bin/bash` on the machine that runs an agent

A bench that talks to a serial device also needs the native serial bindings — they are installed with the agent's dependencies (serialport, @serialport/bindings-cpp).

Install the workspace

Clone the repository and install every workspace package from the root:

Terminal

git clone <your-repository-url> core-platform
cd core-platform
pnpm install

pnpm install builds the native modules for the agent's serial ports. If it fails on a machine without a toolchain, install the build dependencies for node-gyp first, then re-run the install.

The applications

Application	Package	Port	What it is
Studio	`apps/studio`	3000	The web platform: UI, REST API and the realtime socket, all from one server.
Agent	`apps/agent`	3001	The workstation companion that runs on each bench.
API	`apps/api`	3003	A separate REST service for integrations.
Docs	`apps/docs`	3004	This documentation site.
Site	`apps/site`	3005	The public marketing site.

Start the studio

pnpm --filter @dkstudio/studio dev

The studio starts on http://localhost:3000. One server serves the web UI, the REST API and the Socket.IO endpoint, so the browser and the agents talk to a single address and a single port.

Verify the installation

Ask the studio what it sees:

curl http://localhost:3000/api/system/status

A freshly installed studio answers with its state before setup has run:

{
  "status": "uninitialized",
  "needsSetup": true,
  "databaseConfigured": false,
  "adminCreated": false,
  "version": "1.0.0"
}

status moves from uninitialized to needs_admin once the database is configured, and to ready when the admin account exists.

Run the setup wizard

The first visit to the studio redirects you into the setup wizard, which takes the licence key, configures the database, creates the schema and creates the first admin account. When it finishes, the studio serves the application and you sign in at http://localhost:3000/login with the admin account you created.

The session cookie session is written on login and expires after 7 days.

Run an agent

An agent runs on the machine that owns the hardware, which is usually a different computer from the studio. On that machine:

git clone <your-repository-url> core-platform
cd core-platform
pnpm install
pnpm --filter @dkstudio/agent dev

The agent starts on http://localhost:3001 and opens with a registration form. Point it at your studio and give it the credentials from Connect Your First Agent.

One address is enough

The agent only ever needs the studio URL — for example http://localhost:3000 on the same machine, or http://studio.lab.internal:3000 across a network. The agent dials out to the studio; the studio never dials back.

Configuration

Both applications read their configuration from the environment. Copy the example file and edit it:

# in apps/agent
cp .env.example .env.local

Variable	Default	Read by	Meaning
`PORT`	`3000`	studio	The port the studio listens on.
`DATA_DIR`	`./data`	studio	Where the studio's SQLite file and local state are created.
`ADMIN_CREATED`	—	studio	Set to `"true"` to skip the setup redirect for an already-configured deployment.
`DASHBOARD_WS_TOKEN`	—	studio	The shared secret the realtime dashboard socket authenticates with.
`AGENT_PORT`	`3001`	agent	The port the agent's local UI listens on.
`AGENT_HOST`	`localhost`	agent	The interface the agent binds to.

The agent's name and studio URL come from its registration form, not from the environment, and are stored on the agent machine in data/agent.json.

The configuration files

The studio keeps its state in the working directory, and the setup wizard writes these files:

File	Written by	Holds
`.db-config.json`	Setup wizard	`dbType`, `host`, `port`, `database`, `username`, `password`, `initializedAt`.
`.studio-license.json`	Setup wizard	`edition`, `licenseKey`, `issuedAt`, `expiresAt`, `maxAgents`, `features`.
`.setup-progress.json`	Setup wizard	`currentStep`, `startedAt`, `completedAt` — so setup can resume.
`.setup-complete`	Setup wizard	The marker that makes the studio serve the app instead of the wizard.
`data/agent.json`	Agent	`agentId`, `apiKey`, `agentSecret`, `name`, `studioUrl`, `registeredAt`.

Database engines

The studio supports three engines, and the same platform features run on all of them:

Engine	Driver	Where the data lives
SQLite	`better-sqlite3`	A file at `${DATA_DIR}/<database>.db`, `dkstudio.db` by default.
PostgreSQL	`pg`	The database you point it at.
MySQL	`mysql2`	The database you point it at.

Production build

pnpm build          # builds every workspace package
pnpm --filter @dkstudio/studio start

The production command serves the UI, the REST API and the Socket.IO endpoint from the same server and the same port, exactly as the development command does.

Deploy the platform on a trusted network

The studio serves plain HTTP and does not terminate TLS itself. Its session cookie is marked secure only when NODE_ENV=production, so a production deployment sits behind a reverse proxy that terminates TLS and forwards to the studio port over the private network. Agents reach the studio over that same address; only http and https URLs are supported. See Self-hosted Deployment.

Next steps

Setup Wizard — configure the database and create the first admin.
Connect Your First Agent — claim a licence and register a bench.