Everything you need to run the whole app — server + Max auth token + web SPA — in one place. Two modes: a production-like single process (server serves the built SPA) and a hot-reload dev mode (Vite dev server + watched backend).
- Node 22+, and the
claudeCLI on yourPATH(claude --version) for the sweeper and triggers. Chats do not need it — they run herdctl's SDK runtime, which resolves the Claude Agent SDK's own bundled binary and never consultsPATH(onlydriveMode: batchchats use the CLI). - A Claude Max OAuth token in
~/herds/.envasCLAUDE_CODE_OAUTH_TOKEN. The server passes it through the process environment to the agents; it is never written to any file. (Deployed: the LXC has the same token in env.) - Dependencies installed:
npm install(from the repo root).
Never print the token. Always load it into the environment with
set -a; source ~/herds/.env; set +a— neverecho $CLAUDE_CODE_OAUTH_TOKEN.
This is exactly how the deployed service runs: the server serves
packages/web/dist as the SPA and exposes /api + /ws on the same origin.
cd ~/Code/paddock
# 1. Load the Max token into the environment (no value is printed).
set -a; source ~/herds/.env; set +a
# 2. Build both packages (web dist + server dist).
npm run build
# 3. (optional) Use a throwaway data dir so you don't touch real projects.
export PADDOCK_DATA_DIR="$(mktemp -d /tmp/paddock-dev.XXXXXX)"
export PORT=7233 # default; change if 7233 is taken
# 4. Start the single server process.
npm run start # == node packages/server/dist/index.jsOpen http://localhost:7233/ — the SPA, API, and WebSocket chat all live here.
Quick checks (another terminal):
curl -s http://localhost:7233/api/health # {"ok":true}
curl -s http://localhost:7233/api/projects # {"projects":[...]}Use this while iterating on the frontend. Vite serves the SPA on :5173 and
proxies /api + /ws to the backend on :7233 (see vite.config.ts), so
the WebSocket chat works end-to-end with live reload.
cd ~/Code/paddock
set -a; source ~/herds/.env; set +a # token in env for BOTH terminals
# Terminal 1 — backend (watched, tsx)
npm run dev # paddock-server on :7233
# Terminal 2 — frontend (Vite, HMR)
npm run dev:web # http://localhost:5173 (proxies /api + /ws -> :7233)Open http://localhost:5173/.
To run on different ports (e.g. when :7233 is already taken by another
instance) point the dev server at a backend on another port:
# Terminal 1 — backend on :4200
PORT=4200 npm run dev
# Terminal 2 — Vite on :4100, proxying to the :4200 backend
PADDOCK_DEV_PORT=4100 PADDOCK_PROXY_TARGET=http://localhost:4200 npm run dev:web# Mode A:
pkill -f "packages/server/dist/index.js"
# Mode B: Ctrl-C each terminal.
# If you used a temp data dir:
rm -rf /tmp/paddock-dev.*| Var | Default | Purpose |
|---|---|---|
CLAUDE_CODE_OAUTH_TOKEN |
— | Required. Max auth, passed to the agents. |
PORT |
7233 |
HTTP/WS listen port. |
HOST |
127.0.0.1 |
Bind host — loopback by default. Binding a routable interface while PADDOCK_AUTH_MODE=none refuses to start unless PADDOCK_DANGEROUSLY_ALLOW_OPEN is set. |
PADDOCK_DATA_DIR |
./data |
Root for projects, herdctl config + state. |
PADDOCK_WEB_DIST |
packages/web/dist |
Built SPA served in production. |
VITE_API_BASE (web build) |
same-origin | Point the SPA at a non-default API origin. |
VITE_WS_BASE (web build) |
same-origin | Point the SPA at a non-default WS origin. |
PADDOCK_DEV_PORT (Mode B) |
5173 |
Vite dev-server port. |
PADDOCK_PROXY_TARGET (Mode B) |
http://localhost:7233 |
Backend origin the Vite dev server proxies /api + /ws to (WS target derived by swapping http→ws). |
PADDOCK_WHISPER_MODE |
off (or remote if an endpoint is set) |
Voice dictation backend: off | remote | local. |
PADDOCK_WHISPER_ENDPOINT |
— | remote: OpenAI-compatible base URL, e.g. http://whisper.local:8385/v1. /audio/transcriptions is appended. |
PADDOCK_WHISPER_MODEL |
base |
Whisper model (tiny/base/small/…; .en variants for English-only). |
PADDOCK_WHISPER_API_KEY |
— | remote: optional bearer token for the endpoint. |
PADDOCK_WHISPER_LANGUAGE |
— | Optional spoken-language hint (e.g. en); unset ⇒ auto-detect. |
PADDOCK_WHISPER_MAX_UPLOAD_BYTES |
26214400 (25 MB) |
Max accepted dictation upload size. |
Voice dictation (see Voice dictation) is off unless a whisper backend is configured.
localmode needs the optionalnodejs-whisperdependency plus a systemffmpeg.
The composer shows a microphone button next to Send when the instance has a
whisper backend configured. Recording happens in the browser; the clip is POSTed
to /api/transcribe, transcribed server-side, and the text is inserted into the
draft.
-
remote (recommended): point
PADDOCK_WHISPER_ENDPOINTat any OpenAI-compatible whisper server (whisper-server, faster-whisper-server, speaches, …). This is the same contract HushPod uses, so both can share one server:export PADDOCK_WHISPER_ENDPOINT=http://whisper.local:8385/v1 export PADDOCK_WHISPER_MODEL=base
-
local: run whisper.cpp on the box. Needs
ffmpegonPATHand the optional dependency (npm i -w @paddock/server nodejs-whisper); the first transcription compiles whisper.cpp and downloads the model.export PADDOCK_WHISPER_MODE=local export PADDOCK_WHISPER_MODEL=base # or base.en / small for more accuracy
GET /api/transcription reports { available, mode, model } — the composer uses
it to decide whether to show the button.
Secure context required. Browser mic capture (
getUserMedia) only works over HTTPS orlocalhost. On a plain-HTTP LAN URL the button appears disabled with a tooltip; use the production HTTPS origin (orlocalhost) to record.
- App shell loads at
/, projects grid renders (empty state if no projects). - + New Project → modal → create → you land in the project view.
- New Chat in the project → type a message → assistant text streams in as markdown with a live caret; tool calls appear as collapsible blocks; the chat becomes a resumable session in the left list once it completes.
- Reload the page, reopen the chat → its transcript hydrates from history.
- New chat from the root Home page → same chat pane against the root workspace's keeper.