Run DarkDuck locally with zero external dependencies.

​
Prerequisites

  • Node.js 20+
  • pnpm 9+

​
Start Dev Server

pnpm install
pnpm dev
This starts:
  • API server at http://localhost:3100
  • UI served by the API server in dev middleware mode (same origin)
No Docker or external database required. DarkDuck uses embedded PostgreSQL automatically.

​
One-Command Bootstrap

For a first-time install: 
pnpm darkduck run
This does:
  1. Auto-onboards if config is missing
  2. Runs darkduck doctor with repair enabled
  3. Starts the server when checks pass

​
Tailscale/Private Auth Dev Mode

To run in authenticated/private mode for network access: 
pnpm dev --tailscale-auth
This binds the server to 0.0.0.0 for private-network access. Allow additional private hostnames: 
pnpm darkduck allowed-hostname dotta-macbook-pro
For full setup and troubleshooting, see Tailscale Private Access.

​
Health Checks

Verify the server is running: 
curl http://localhost:3100/api/health
# -> {"status":"ok"}

curl http://localhost:3100/api/companies
# -> []

​
Reset Dev Data

To wipe local data and start fresh: 
rm -rf ~/.darkduck/instances/default/db
pnpm dev
This deletes all companies, agents, tasks, and run history. There is no undo. Back up your data directory first if you need to preserve anything.

​
Data Locations

DataPath
Config~/.darkduck/instances/default/config.json
Database~/.darkduck/instances/default/db
Storage~/.darkduck/instances/default/data/storage
Secrets key~/.darkduck/instances/default/secrets/master.key
Logs~/.darkduck/instances/default/logs
Override with environment variables: 
DARKDUCK_HOME=/custom/path DARKDUCK_INSTANCE_ID=dev pnpm darkduck run
Use separate instance IDs to run multiple DarkDuck instances on the same machine without data conflicts. Each instance gets its own config, database, and storage.

​
Multiple Instances

Run isolated instances by specifying different instance IDs: 
# Production-like instance
DARKDUCK_INSTANCE_ID=prod pnpm darkduck run

# Experimental instance
DARKDUCK_INSTANCE_ID=experiment pnpm darkduck run --port 3200
Each instance stores data under ~/.darkduck/instances/<id>/.