Worklab

Worklab is a local, single-user workspace for coordinating AI agents across projects, tasks, goals, teams, knowledge, providers, and runtime controls. It runs on your machine, keeps its working data under your local data directory, and gives you a browser UI for managing agent work without turning every run into a terminal session.

Start Worklab

Requirements: Node.js 20 or newer.

Install the CLI from npm:

npm install -g @worklab-ai/worklab
worklab onboard

Open http://127.0.0.1:7878.

For development from this checkout:

npm install
npm run install:worklab
worklab onboard

worklab onboard is the first-run setup wizard. It checks Codex and Claude Code availability, installs the Worklab host skill into available tools, guides hosted auth setup, configures a local provider such as Ollama or LM Studio, optionally installs the default embedding model, and finishes with service and doctor checks.

worklab start builds the UI, installs or refreshes the per-user service, and starts Worklab in the background. worklab onboard runs it for you unless you pass --no-start. After the first install, your normal startup command is just:

worklab start

Useful service commands:

worklab status
worklab restart
worklab stop

Auth And Embeddings

Worklab can run with only local providers, but hosted models need credentials. worklab onboard reports what is missing and prints the exact follow-up commands.

Pi OpenAI Codex auth:

worklab auth pi openai-codex

This starts the Pi OAuth flow and stores credentials in ~/.worklab/pi-auth.json. If you use a custom data directory, pass the same --data-dir flag you use for the service. OPENAI_CODEX_API_KEY or CODEX_API_KEY still take precedence when set.

OpenAI API key auth:

1. Create an API key in the OpenAI dashboard: https://platform.openai.com/api-keys

2. Add it to the active Worklab data directory:

   echo 'OPENAI_API_KEY=sk-...' >> ~/.worklab/.env
   worklab restart

OPENAI_API_KEY enables OpenAI API-backed models and optional OpenAI embeddings. During onboarding you can choose local embeddings, OpenAI embeddings, or no embeddings:

worklab onboard --embedding local
worklab onboard --embedding openai
worklab onboard --embedding no

OpenAI embeddings use openai:text-embedding-3-small by default. Local embeddings use Ollama nomic-embed-text or an embedding-capable LM Studio model when available.

First Setup

Start in the UI, not in config files:

1. Open Providers and confirm the models Worklab can use. Built-in CLI models and custom OpenAI-compatible providers can be managed there.
2. Open Agents and review the default planner, executor, and reviewer. Create additional agents only when you need a distinct role.
3. Open Teams when you want lead-cycle coordination across a roster of agents, with a lead agent responsible for keeping the work pointed at the outcome.
4. Open Projects and add the repositories or work directories you want Worklab to operate on. If a repo has AGENTS.md, Worklab treats it as repository instructions for agent prompts.
5. Open Goals for longer-lived outcomes tied to a project and team. Goals track the objective, north star, stopping condition, validation loop, and lead-cycle context that should shape related work.
6. Open Tasks and create the work you want the agents to plan, execute, and review.
7. Use Knowledge for durable notes that agents should reuse, and Settings for runtime, search, Slack, MCP, notification, and assistant controls.

Runtime data defaults to ~/.worklab; task workspaces default to ~/worklab-workspace.

Daily Use

• Use Tasks as the active work queue.
• Use Goals to keep larger project outcomes, north-star criteria, and recurring lead-cycle decisions visible.
• Use Runs to inspect completed runs and historical output.
• Use Projects to keep repo context, allowed agents, task progress, and project knowledge together.
• Use Teams to manage lead agents, member agents, budgets, and project goal assignments.
• Use the assistant dock in the UI for quick questions against the current Worklab view.

Agents that need stdio MCP access to Worklab can run:

worklab mcp

Useful Commands

| Command | Purpose | | --- | --- | | worklab onboard | First-install wizard for tools, skills, auth guidance, providers, embeddings, service startup, and doctor checks. | | worklab auth pi openai-codex | Create Pi OAuth credentials for OpenAI Codex under the active data directory. | | worklab install-skill --target codex\|claude\|all | Install the Worklab host skill into Codex or Claude Code. | | worklab start | Build the UI, install or refresh the user service, and start Worklab. | | worklab status | Show service, coordinator, health, and runtime configuration status. | | worklab restart | Rebuild the UI and restart the managed service. | | worklab stop | Stop the managed service. | | worklab doctor | Check runtime health, service wiring, database integrity, MCP config, and embeddings. | | worklab doctor performance | Measure endpoint timings, response sizes, database size, and large event logs. | | worklab mcp | Run the full-access Worklab admin MCP bridge over stdio. | | worklab update --apply --version <latest> | Apply a supported global npm update and restart the service. | | worklab backup | Create a tar.gz backup of the active data directory. | | worklab compact-logs --apply | Compact old large SQLite run logs while preserving raw JSONL logs. |

Configuration

Worklab loads .env from the active data directory, while shell environment variables and CLI flags take precedence.

Common overrides:

WORKLAB_PORT=9000
WORKLAB_HOST=127.0.0.1
WORKLAB_DATA_DIR=/tmp/worklab-dev
WORKLAB_WORKSPACE=/tmp/worklab-workspace
WORKLAB_LOG_LEVEL=info

CLI flags are passed after the command:

worklab start --port 9000
worklab restart --port 9000
worklab serve --port 9000 --data-dir /tmp/worklab-dev

worklab start and worklab restart regenerate the host service definition with the effective host, port, data directory, workspace, and log level.

Development

For a foreground API/static server from this checkout:

npm run dev:api

For UI hot reload, run the API and Vite UI in separate terminals:

npm run dev:api
npm run dev:ui

Open the Vite URL, normally http://127.0.0.1:5173. worklab serve, npm start, and npm run dev:api serve the built UI from src/ui/dist; Vite is the hot-reload path for src/ui.

Tailnet Access

Keep Worklab bound to localhost and use Tailscale Serve for tailnet-only access:

worklab start
tailscale serve --bg --yes --http 7878 7878
tailscale serve status

Use the MagicDNS URL shown by tailscale serve status. Raw Tailscale IP requests can return a Serve 404 because Serve routes by hostname.

Disable the proxy with:

tailscale serve --http=7878 off

Testing

Run the full suite:

npm test

Useful focused checks:

npm run build:ui
npm run pack:check
npm run lint
npm run lint:size
./scripts/guard-imports.sh

Browser regressions use Playwright against a freshly built UI:

npm run test:e2e:ollama

See AGENTS.md for repository instructions and testing expectations.

License

GPLv3. See LICENSE.