Install

dox runs as a single Node process. There is no build step for the server and no database — state lives in plain files in a dox-data/ folder next to the code directory.

Requirements

From source

git clone https://github.com/dox012/dox.git
cd dox

npm install                      # workspace dependencies
npm run build --workspaces --if-present   # builds each app into app/*/dist

node dox.mjs

node dox.mjs starts the server and opens http://localhost:3000/.

Two things worth knowing:

• The entry point is /. There is no second path.
• dist/ is not committed. If the canvas loads but every app refuses to open, the build step above was skipped; the server only registers apps that have a dist/index.html.

First run

1. Open Config (right-click the canvas, choose config) and fill in the model endpoint, key and model name.
2. Send a message in the Agent window. The first turn creates a session file under dox-data/agent/sessions/.
3. Right-click the canvas for the app menu; drag a window by its 4px edge to move it.

Where state lives

State lives beside the code, never inside it:

dox/                        the checkout — safe to delete and replace
dox-data/                   created on first run
  agent/config.json         default model, default cwd
  agent/models/*.env        one file per model
  agent/sessions/*.sss      conversations, one file each

That is the whole upgrade story on a server: stop the process, replace the dox/ directory, start it again. dox-data/ is untouched.

Point DOX_DATA_DIR somewhere else to override the location:

DOX_DATA_DIR=/var/lib/dox node dox.mjs

Run a single app in development

Each app is self-contained, with its own package.json and dev server:

cd app/editor
npm run dev        # vite on 5173 + the app's own server on its declared port

The app then works standalone, outside the canvas. This is the fastest loop when you are changing one app.

The TUI

The agent also runs in a terminal, without dox, the browser, or node_modules:

node app/agent/tui/main.ts

It reads the same dox-data/ directory, so sessions opened in the GUI appear in the TUI and vice versa. It needs Node 22.6+ for the same type-stripping reason, and nothing else.

Troubleshooting