Quick Usage (Already Configured)
1) Start the dev stack (Docker)
Run from the OpenWork repo root:
packaging/docker/dev-up.sh
This prints:
Web UI URL (
http://localhost
:)
OpenWork server URL (
http://localhost
:)
Token file path (
tmp/.dev-env-
) containing
OPENWORK_TOKEN
+
OPENWORK_HOST_TOKEN
A
docker compose ... down
command that stops this stack
2) Verify a real UI flow (Chrome MCP)
Minimum gate:
Open the printed Web UI URL.
Navigate to the session/chat surface (typically
/session
).
Send a message (example:
smoke: hello from chrome mcp
).
Confirm a response renders in the UI.
Chrome MCP tool recipe (typical):
chrome-devtools_list_pages
(optional: see existing tabs)
chrome-devtools_new_page
with the Web UI URL (or
chrome-devtools_navigate_page
if a page is already open)
chrome-devtools_take_snapshot
to locate the chat input + Send button uids
chrome-devtools_fill
the chat input uid with your message
chrome-devtools_click
the Send button uid
chrome-devtools_wait_for
a distinctive piece of response text (or re-snapshot until the response appears)
chrome-devtools_take_screenshot
(save to
/tmp/...png
when possible)
If debugging:
chrome-devtools_list_console_messages
Evidence:
Take a Chrome MCP screenshot after the response appears.
If something fails, capture console logs and (optionally) Docker logs.
Verification checklist (copy into PR)
Started stack with
packaging/docker/dev-up.sh
from repo root.
Used the printed Web UI URL (not a guessed port).
Completed one full user flow in the UI (input -> action -> visible result).
Captured at least one screenshot for the success state.
Captured failure evidence when relevant (console and/or Docker logs).
Stopped stack with the exact printed
docker compose -p ... down
command.
Suggested screenshot set for user-facing changes:
Before action state.
During action/progress state.
Success state.
Failure or recovery state (if applicable).
3) Stop the stack
Use the exact
docker compose -p ... down
command printed by
dev-up.sh
.
If you lost it, you can find the project name via:
docker
ps
--format
'{{.Names}}'
|
rg
'^openwork-dev-'
Then stop it (replace
):
docker
compose
-p
<
project
-f
packaging/docker/docker-compose.dev.yml down
Required Gate (Non-Negotiable)
Any user-facing change or change that touches remote behavior must be validated end-to-end in the running UI.
The change is not "done" until it succeeds via Chrome MCP against the Docker dev stack started by
packaging/docker/dev-up.sh
.
Common Gotchas
Docker is required (and the
docker
CLI must be available on PATH).
dev-up.sh
uses random host ports; do not assume
5173
/
8787
.
If the UI looks up but is disconnected, confirm you opened the
printed
URL and that headless is healthy.