Quickstart

Quickstart

Two commands to a running coordinator, one more to make it do work.

1. Start it

You need Docker. Nothing else — no database, no Redis, no object store.

git clone https://github.com/usewrit/writ.git && cd writ
./scripts/gen-env.sh
docker compose up -d --build

Open http://localhost:8000 and create your account.

The first build takes a few minutes: the OCR runtime and its model weights are baked into the image so document extraction works offline, and the web UI is built from source.

gen-env.sh writes a .env with freshly generated signing keys. It refuses to overwrite an existing one — pass --force if you really mean to (you will lose the old secrets, which invalidates every session and agent token).

Back up SECRET_ENCRYPTION_KEY from .env now, somewhere other than this machine. It encrypts your stored credentials at rest. A database backup without it cannot be decrypted, and there is no recovery path.

2. Connect one agent

The coordinator runs no browsers. It is the control plane; the browsing happens in a separate writ-agent process that you run wherever you want the work done. Until one is connected, nothing executes — runs queue and sit there.

Open Fleet → Connect a new agent, copy the line it shows, and run it on whichever machine should do the browsing. Your laptop is fine:

curl -fsSL http://localhost:8000/agent.sh | sh -s -- WRIT-4K2P-9XQ

That installs the agent, enrols it, and starts it. The pairing code is single-use and expires in 15 minutes; everything else — the coordinator URL, the document-extractor address and its shared secret — the installer fetches for itself.

The agent dials out over WebSocket, so it needs no inbound port and works behind NAT. It appears in Fleet within a few seconds.

Prefer to do it by hand? The same modal has Binary and Docker tabs with the raw token. Connecting agents is the full reference.

3. Record something

New workflow → Record. Drive the site in the live browser view: click, type, scroll. Every action lands as an editable step on the right.

Two things worth knowing while recording:

• Click into the live view before you type. That click is what tells the recorder your keystrokes belong to the page rather than to the app's own toolbar.
• Typing is captured as a fill step per field, not per keystroke. The step appears when you move on — Tab, Enter, or clicking elsewhere.

Stop the recording and you have a workflow. Run it, schedule it, or call it as an API — the workflow's Connect tab has a ready-to-paste curl.

Day-to-day

docker compose logs -f    # follow logs
docker compose restart    # restart
docker compose down       # stop, keep your data
docker compose down -v    # stop and DELETE everything, including your data

Run these from the repository root.

Next

• Put it on a domain — one command for HTTPS.
• Configuration — every setting.
• Troubleshooting — when something does not behave.