@boardsketch/worker

BoardSketch Local Worker 0.6.1 is one portable, foreground-only npm package for one-time Game generation and ephemeral participant-controller leases. Linux and WSL2, macOS, and native Windows support is experimental in this pilot.

npm install --global @boardsketch/worker
boardsketch-worker login
boardsketch-worker doctor
boardsketch-worker start

The package has an exact runtime dependency on the official @openai/codex package and resolves the Codex executable from that installation. It never searches PATH for an unrelated executable. One managed Codex App Server starts over stdio for the Worker lifetime and is the only Codex execution integration.

BoardSketch gives Codex a dedicated home beneath the operating system's normal application-data directory: BoardSketch application data on Linux and WSL2, BoardSketch Application Support on macOS, or BoardSketch Local AppData on Windows. It does not import or modify ~/.codex. Codex owns login, credential storage, provider configuration, and refresh; BoardSketch never reads or prints credential files or token values.

Manage that account through the App Server:

boardsketch-worker login
boardsketch-worker login --device-code
boardsketch-worker account
boardsketch-worker logout
boardsketch-worker doctor

The default login uses Codex's ChatGPT browser flow. The platform adapter opens the returned URL; Codex owns its callback and exchange. doctor reports the Worker, protocol, Node, operating system, bundled Codex, App Server, account, native sandbox, resource-limit, generation, and controller readiness without revealing credentials. If the native sandbox cannot initialize, diagnostics remain available but generation and controllers fail closed—there is no unsandboxed fallback.

The process listens only at http://127.0.0.1:47831. Every start creates a new in-memory Ed25519 identity. Protocol 5 exposes coarse browser-safe readiness and capacity at GET /v5/status, accepts generation at POST /v5/tasks, and accepts Local Agent activation at POST /v5/controllers. protocolVersion must be exactly 5; workerVersion records the valid semantic package version, allowing compatible 0.6.x patches. Account, provider, and detailed sandbox state remain local to doctor.

The default capacity is two concurrent tasks or controllers and can be set from one through eight with start --capacity N; a full Worker rejects new work instead of queuing it. Browser task queries and stop requests require the task-local control issued to the originating tab. Local administrators can inspect or stop active work from another terminal:

boardsketch-worker tasks
boardsketch-worker stop TASK_ID

Each GenerationTask gets the exact starter or parent-Game repository, byte-exact immutable REQUEST.md, a fresh App Server thread, and a narrow workspace-write native sandbox with network disabled. Reads are restricted to Codex's platform defaults, the exact bundled runtime, the Node runtime needed for generation commands, and the Task workspace. Interruption goes through App Server. The Worker verifies REQUEST.md, runs npm test and npm run build through Codex's sandboxed command interface, then collects and submits the complete immutable result as before.

Each controller observation gets a separate bounded turn containing only public Game context and that participant's current view. Its structured output schema enumerates the currently selectable IDs and produces exactly one canonical select input. Controllers never share a view, thread, prompt, or result. Their read-only profile has no unrelated user roots, and BoardSketch never inspects or automates the Human Client UI.

Stopping the Worker interrupts active work, stops App Server, and closes the loopback listener. An App Server crash may fail current local work; this release has no restart recovery or persistent local task restoration. The Worker has no persistent device identity, registration, pairing, presence, cloud polling, or hidden queue.