Instance setup and diagnostics commands.

​
darkduck run

One-command bootstrap and start: 
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
Choose a specific instance: 
pnpm darkduck run --instance dev

​
darkduck onboard

Interactive first-time setup: 
pnpm darkduck onboard
If DarkDuck is already configured, rerunning onboard keeps the existing config in place. Use darkduck configure to change settings on an existing install.

​
Setup Modes

ModeDescription
Quickstart (recommended)Local defaults: embedded database, no LLM provider, local disk storage, default secrets
Advanced setupFull interactive configuration for each subsystem

​
Options

# Start immediately after onboarding
pnpm darkduck onboard --run

# Non-interactive defaults + immediate start (opens browser)
pnpm darkduck onboard --yes
On an existing install, --yes preserves the current config and just starts DarkDuck.

​
darkduck doctor

Health checks with optional auto-repair: 
pnpm darkduck doctor
pnpm darkduck doctor --repair
Validates:
  • Server configuration
  • Database connectivity
  • Secrets adapter configuration
  • Storage configuration
  • Missing key files
Run darkduck doctor after any configuration change to verify everything is working correctly. Use --repair to fix common issues automatically.

​
darkduck configure

Update configuration sections: 
pnpm darkduck configure --section server
pnpm darkduck configure --section secrets
pnpm darkduck configure --section storage
Each section presents an interactive prompt for its settings.

​
darkduck env

Show resolved environment configuration: 
pnpm darkduck env
Displays all resolved configuration values including defaults and overrides.

​
darkduck allowed-hostname

Allow a private hostname for authenticated/private mode: 
pnpm darkduck allowed-hostname my-tailscale-host
Required when accessing DarkDuck via custom hostnames in private network mode.

​
Local Storage Paths

DataDefault Path
Config~/.darkduck/instances/default/config.json
Database~/.darkduck/instances/default/db
Logs~/.darkduck/instances/default/logs
Storage~/.darkduck/instances/default/data/storage
Secrets key~/.darkduck/instances/default/secrets/master.key
Override with: 
DARKDUCK_HOME=/custom/home DARKDUCK_INSTANCE_ID=dev pnpm darkduck run