Spec Studio Manager

Local-first browser task orchestration

Spec Studio Manager is a Windows-first desktop hub for browser automation work. It lets a small QA, dev/ops, or automation team queue browser tasks, dispatch them to a local self-agent or LAN remote agents, and inspect execution history without sending operator state to a cloud control plane.

Why teams try it

• Debug browser failures faster: keep queue state, execution history, screenshots, traces, and failure context together.
• Replace scattered scripts with an operator UI: move repetitive Playwright/Puppeteer-style work out of ad-hoc terminals and into a local hub.
• Keep browser work local: runtime state lives in local SQLite; remote agents connect over LAN WebSocket.
• Avoid vendor lock-in for the first workflow: use Donut profiles when available or local Playwright fallback when Donut launch is blocked.

Who it is for

• Mid/senior QA automation operators debugging repetitive browser runs.
• Dev/ops operators running internal browser workflows across local or LAN machines.
• Small teams that want a pragmatic desktop control hub, not enterprise RPA or a hosted browser cloud.

Not a fit yet: full QA test management, enterprise RPA replacement, cloud sync, broad cross-browser orchestration, or zero-setup SaaS.

What ships today

• Wails desktop shell with Go backend and React/TypeScript frontend
• Local SQLite source of truth for agents, tasks, executions, pairing, and runtime state
• Self-agent runtime and manual LAN remote-agent enrollment over WebSocket
• Browser execution modes: simulate, donut, and local-playwright
• Runtime surfaces for task queue, execution history, self-agent readiness, pairing, machines, and runtime agents
• Execution retention preview/prune, local SQLite backup, and explicit JSON exports for beta incident handoff
• Deterministic local browser recipes for smoke, queue triage, login, form, checklist, and settings flows

Fast local proof path

Requirements for the quick proof: Node.js/npm and Chrome or Edge. Go 1.23+ and Wails CLI v2 are needed for the full app/test gate.

cd spec-studio-manager
npm install
npm run smoke:local-playwright

Expected proof: the command exits 0 and prints JSON with status: "succeeded", plus non-empty screenshotPath and tracePath values. It runs against a self-contained local page, so it does not require Donut, internet, or external DNS.

For the full verification gate after installing Go, Wails, and frontend dependencies:

cd frontend
npm install
cd ..
npm run agent:dev:loop

This runs Go tests, frontend lint/tests, smoke tests, frontend build, and Wails Windows build. It is the release-confidence path, not the first-touch proof.

Public beta proof status

Verified on 2026-05-17:

• npm run smoke:local-playwright exits 0 with status: "succeeded", screenshotPath, and tracePath.
• npm run test:smoke exercises browser smoke payload checks and the subprocess remote-agent pair/run/dispatch path.
• npm run agent:dev:loop is green, including Go tests, frontend lint/tests, smoke tests, frontend build, and Wails Windows build.

Real two-machine LAN validation was not performed in this session. Treat LAN rollout as beta and track second-host validation in issue #14 before relying on a second host.

Screenshots

Runtime overview

Queue and execution visibility

Runtime agents and LAN enrollment

Remote agent path

The current remote-agent MVP is manual-first and trusted-LAN only:

1. Open the desktop app on a private network and generate a pairing token from Runtime settings.
2. Copy the hub WebSocket URL shown in the pairing panel.
3. Pair once on the agent machine; pairing tokens are stored hashed, expire, and are single-use.
4. Restart the remote runtime with persisted auth.
5. Dispatch a deterministic local Playwright task only after the runtime agents or machines surface shows the remote row online.

Do not expose hub port 9800 to the Internet or a public/untrusted LAN. See spec-studio-manager/cmd/remote-agent/README.md and docs/deployment-guide.md for the full two-machine checklist.

Current limitations

• Browser recipe coverage is still focused on deterministic smoke and operator-demo flows.
• Full auth and permissions do not exist yet; the hub is for trusted local/private-LAN use only.
• Do not expose hub port 9800 to the Internet or public Wi-Fi.
• Donut profile launch can be externally blocked by plan/license; local Playwright fallback exists for ungated local runs.
• UDP discovery, cloud sync, and installer/store packaging are not part of the current beta scope.
• Real two-machine LAN validation was not verified in the 2026-05-17 beta gate; local subprocess remote-agent smoke was verified, and issue #14 tracks second-host validation.
• Public landing page is live at https://hthmkt12.github.io/spec-studio-manager/landing/; social presence and community channel are still TBD.

Docs

• Project Overview
• System Architecture
• Codebase Summary
• Project Roadmap
• Deployment Guide
• Marketing Overview
• Customer Personas
• Design Guidelines
• Static Landing Page — live at https://hthmkt12.github.io/spec-studio-manager/landing/

Beta Ops Support

For any beta incident:

1. Export the relevant in-app JSON from the affected surface, or create a local SQLite backup from spec-studio-manager -> Runtime settings if the store state is needed.
2. Attach only the JSON, screenshots, traces, or backup DB that you intentionally want to share.
3. Do not post SQLite backups or exported JSON publicly. They may include task metadata, local file paths, execution evidence paths, runtime state, and token hashes.
4. Open a GitHub issue with the failure summary, exact command/UI action, app version or commit, and any redacted artifact paths.

See Deployment Guide for the short intake contract.

Repo metadata candidate

• Description: Local-first desktop hub for browser task orchestration across self and LAN agents
• Topics: browser-automation, desktop-app, wails, playwright, golang, react, sqlite, rpa, local-first, agent-runtime
• Social preview: use a real runtime UI screenshot with the shipped slate/blue operator palette.

License

Open source / Free