Skip to content

Latest commit

 

History

History
158 lines (120 loc) · 6.8 KB

DEV.md

File metadata and controls

158 lines (120 loc) · 6.8 KB

Running Paddock locally (full stack)

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).

Prerequisites

  • Node 22+, and the claude CLI on your PATH (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 consults PATH (only driveMode: batch chats use the CLI).
  • A Claude Max OAuth token in ~/herds/.env as CLAUDE_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 — never echo $CLAUDE_CODE_OAUTH_TOKEN.

Mode A — production-like (one process serves API + WS + SPA)

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 MANAGERS_DATA_DIR="$(mktemp -d /tmp/paddock-dev.XXXXXX)"
export PORT=7234            # default; change if 7234 is taken

# 4. Start the single server process.
npm run start              # == node packages/server/dist/index.js

Open http://localhost:7234/ — the SPA, API, and WebSocket chat all live here.

Quick checks (another terminal):

curl -s http://localhost:7234/api/health     # {"ok":true}
curl -s http://localhost:7234/api/projects    # {"projects":[...]}

Mode B — hot-reload dev (two processes)

Use this while iterating on the frontend. Vite serves the SPA on :5173 and proxies /api + /ws to the backend on :7234 (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 :7234

# Terminal 2 — frontend (Vite, HMR)
npm run dev:web      # http://localhost:5173  (proxies /api + /ws -> :7234)

Open http://localhost:5173/.

To run on different ports (e.g. when :7234 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
MANAGERS_DEV_PORT=4100 MANAGERS_PROXY_TARGET=http://localhost:4200 npm run dev:web

Stopping

# 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.*

Environment variables (server)

Var Default Purpose
CLAUDE_CODE_OAUTH_TOKEN — Required. Max auth, passed to the agents.
PORT 7234 HTTP/WS listen port.
HOST 127.0.0.1 Bind host — loopback by default. Binding a routable interface while MANAGERS_AUTH_MODE=none refuses to start unless MANAGERS_DANGEROUSLY_ALLOW_OPEN is set.
MANAGERS_DATA_DIR ./data Root for projects, herdctl config + state.
MANAGERS_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.
MANAGERS_DEV_PORT (Mode B) 5173 Vite dev-server port.
MANAGERS_PROXY_TARGET (Mode B) http://localhost:7234 Backend origin the Vite dev server proxies /api + /ws to (WS target derived by swapping http→ws).
MANAGERS_WHISPER_MODE off (or remote if an endpoint is set) Voice dictation backend: off | remote | local.
MANAGERS_WHISPER_ENDPOINT — remote: OpenAI-compatible base URL, e.g. http://whisper.local:8385/v1. /audio/transcriptions is appended.
MANAGERS_WHISPER_MODEL base Whisper model (tiny/base/small/…; .en variants for English-only).
MANAGERS_WHISPER_API_KEY — remote: optional bearer token for the endpoint.
MANAGERS_WHISPER_LANGUAGE — Optional spoken-language hint (e.g. en); unset ⇒ auto-detect.
MANAGERS_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. local mode needs the optional nodejs-whisper dependency plus a system ffmpeg.

Voice dictation

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 MANAGERS_WHISPER_ENDPOINT at 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 MANAGERS_WHISPER_ENDPOINT=http://whisper.local:8385/v1
    export MANAGERS_WHISPER_MODEL=base
  • local: run whisper.cpp on the box. Needs ffmpeg on PATH and the optional dependency (npm i -w @managers/server nodejs-whisper); the first transcription compiles whisper.cpp and downloads the model.

    export MANAGERS_WHISPER_MODE=local
    export MANAGERS_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 or localhost. On a plain-HTTP LAN URL the button appears disabled with a tooltip; use the production HTTPS origin (or localhost) to record.

What "good" looks like end-to-end

  1. App shell loads at /, projects grid renders (empty state if no projects).
  2. + New Project → modal → create → you land in the project view.
  3. 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.
  4. Reload the page, reopen the chat → its transcript hydrates from history.
  5. New chat from the root Home page → same chat pane against the root workspace's keeper.