Prove what your agent did

# Assemble the Decosa agent flight recorder on this machine

You are setting up a flight recorder for browser and computer-use agents: every step an agent takes (what it saw, what
it decided, what it did, what happened) is chained into a signed record that anyone can re-verify, and a change to one
screenshot, decision or step fails verification at that step. Optionally, agents get their decisions from Qwen3.8-27B
with a receipt per decision. Work step by step, show me each command before you run anything with `sudo`, and stop to
ask if a check fails.

## Step 0: set up with a coding agent, rehearse on mock data, then go private

This prompt is for a coding agent running on the machine that will host the service. We recommend Claude Code with
Claude Opus 5.5; any capable coding agent works. Work in this order:

1. Set up on mock data only. During the whole setup you (the agent) work with the synthetic sample bundle below and
   nothing else. Do not ask me for real data, and do not open, read, list or copy files that hold real data, even to
   "test with something realistic".
2. Rehearse. When the steps below are done and the service is healthy, fetch the mock-data bundle for this tool,
   https://decosa.ai/samples/flight-recorder.zip (39 KB, 9 checks, synthetic or openly licensed: see `licence` in expected.json),
   show me what is in it, and run the rehearsal against the local API:
   `docker compose exec api python scripts/rehearse.py flight-recorder` (the api image carries the same bundle under /app/rehearsal/flight-recorder/;
   with no key set, the script asks the local API for a short demo token). From a decosa-api checkout instead:
   `python scripts/rehearse.py flight-recorder --bundle flight-recorder.zip --base-url http://127.0.0.1:<PORT>`.
   It sends the mock inputs to the local API and prints PASS or FAIL for each expected property (for example: "on the cart page the model chooses to click Checkout", "on the review page the Place order click is caught by the needs_approval guard", "the agent is stopped and the run escalated to a person"). Show me
   the full output. Every check must pass. If one fails, fix the install and run it again; never edit `expected.json`
   to make a check pass.
3. Stop there. Once the rehearsal passes, tell me, and I will run my own data against the local API myself, on this
   machine.

For the person running this: a coding agent that runs in the cloud sees everything in its context, including files it
reads, command output and anything pasted into the chat. Keep real data out of the chat and out of anything the agent
can read. Switch to your own data only after the rehearsal has passed and the agent's work is done.

## 0. Ground rules and licences
- Recorder: decosa-api (AGPL-3.0-or-later), CPU only. Thumbnails: Pillow (MIT-CMU). Demo browser, optional: Playwright
  (Apache-2.0) with Chromium (BSD-3-Clause). Decision model, optional: Qwen3.8-27B (Apache-2.0).
- Screenshots of back-office screens hold personal data. Everything stays on this machine: bind every port to
  127.0.0.1, keep the data directory 0700, and prefer hash-only mode in the SDK so agents send only screenshot hashes.
- The signing key is the trust anchor. It is created on first start; back it up, never print it, and keep it away from
  the people whose agents are being recorded if the record must hold them to account.
- Be honest about what a record proves: what was reported, in what order and when, and that nothing changed after
  signing. Not that a website did what it displayed, and not that an agent's self-reported step is true.

## 1. Check the machine
1. Recorder only: any Linux x86_64 or macOS machine with Docker, or Python 3.11+. No GPU.
2. With receipted decisions: `nvidia-smi` shows one GPU with at least 32 GB (an RTX PRO 6000 96 GB runs Qwen3.8-27B
   NVFP4 with room to spare; an RTX 5090 32 GB fits it with a shorter context). Driver 570 or newer. On a card without
   NVFP4 use `Qwen/Qwen3.8-27B-FP8`.
3. `docker --version` and `docker compose version`. If Docker or (for the model) the NVIDIA container toolkit is missing,
   install them from the official Docker and NVIDIA repositories after asking me, then run
   `docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi`.
4. Disk: 2 GB for the recorder image (about 400 MB more with the demo browser), about 25 GB more for the model, plus
   room for records (15 KB per step with thumbnails, about 3 KB hash-only).

## 2. Images and weights
- `${DECOSA_REGISTRY}/decosa-api:<tag>` (**publishing soon**). If the pull fails, build from source:
  `git clone <decosa-api source: on request at https://decosa.ai/contact?topic=self-host>` (access required), check out a release that contains
  `decosa_api/verticals/flight/`, and `docker build -f docker/api/Dockerfile -t decosa-api:local .`. Add
  `--build-arg WITH_BROWSER=1` only if you want the hosted-style browser demo on this box.
- Without Docker: `python -m venv .venv && .venv/bin/pip install ".[flight]"` in the checkout, then
  `.venv/bin/python -m decosa_api`.
- For decisions: `vllm/vllm-openai:v0.29.0` and weights `nvidia/Qwen3.8-27B-NVFP4`.

## 3. docker-compose.yml
Write this in `~/decosa/flight/`. Drop the `llm` service and `depends_on` if agents bring their own model.

```yaml
services:
  llm:
    image: vllm/vllm-openai:v0.29.0
    command: ["--model", "nvidia/Qwen3.8-27B-NVFP4", "--served-model-name", "qwen3.8-27b", "--max-model-len", "32768",
              "--language-model-only", "--enable-prefix-caching"]
    ports: ["127.0.0.1:8114:8000"]
    volumes: ["~/.cache/huggingface:/root/.cache/huggingface"]
    deploy: { resources: { reservations: { devices: [{ driver: nvidia, count: 1, capabilities: [gpu] }] } } }
    healthcheck: { test: ["CMD", "curl", "-fs", "http://localhost:8000/v1/models"], interval: 30s, retries: 20 }
  api:
    image: ${DECOSA_REGISTRY}/decosa-api:<tag>
    ports: ["127.0.0.1:8445:8445"]
    environment:
      DECOSA_HOST: 0.0.0.0
      DECOSA_PORT: "8445"
      DECOSA_DATA_DIR: /data
      DECOSA_LLM_ROUTE: direct
      DECOSA_LLM_URL: http://llm:8000/v1
      DECOSA_LLM_MODEL: qwen3.8-27b
      DECOSA_FLIGHT_TTL_S: "86400"
      DECOSA_FLIGHT_DEMO: "0"
      DECOSA_ADMIN_SECRET: ${DECOSA_ADMIN_SECRET}
    volumes: ["decosa-data:/data"]
    depends_on: { llm: { condition: service_healthy } }
    healthcheck: { test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8445/flight/info', timeout=4)"], interval: 30s, retries: 10 }
volumes:
  decosa-data:
```

The api keeps its state (keys, receipts, this box's signing key) in the named volume `decosa-data`, not in a
host folder: the image runs as an unprivileged user (uid 10001), and a host folder that Docker creates is owned by
root, which stops the api with `PermissionError: [Errno 13] Permission denied: '/data/keys.sqlite'`. Then start everything: `docker compose up -d`.
If you already run an
OpenAI-compatible Qwen3.8-27B server, drop `llm` and point `DECOSA_LLM_URL` at it; `DECOSA_LLM_MODEL` must be the
name that server serves (check `GET /v1/models`).

Put `DECOSA_ADMIN_SECRET=<a long random string>` in `~/decosa/flight/.env` (mode 0600). On the first start the api
service creates this box's Ed25519 key in the `decosa-data` volume (`/data/attest/` in the api container, mode 0600). Every decision made through `/decide` on
the direct route gets a receipt signed with that key (status `attested`): an attestation by me, the operator, not a
proof of computation.

## 4. Smoke test
1. `curl -s localhost:8445/flight/info | head -c 800` lists the entry kinds, limits, guards and the decision model.
2. Mint a key: `curl -s -XPOST localhost:8445/v1/keys -H "authorization: Bearer $DECOSA_ADMIN_SECRET" -H 'content-type: application/json' -d '{"label":"agents","verticals":["flight-recorder"]}'`.
   Keep the `dk_` key in the agent's environment as `DECOSA_API_KEY`.
3. `curl -s localhost:8445/flight/sdk/decosa_flight.py -o decosa_flight.py`, then run:
   ```python
   import base64, os, zlib, struct
   from decosa_flight import FlightRecorder
   def png(r, g, b):   # a 2x2 PNG, no dependencies
       raw = b"".join(b"\x00" + bytes([r, g, b]) * 2 for _ in range(2))
       c = lambda t, d: struct.pack(">I", len(d)) + t + d + struct.pack(">I", zlib.crc32(t + d) & 0xffffffff)
       return b"\x89PNG\r\n\x1a\n" + c(b"IHDR", struct.pack(">IIBBBBB", 2, 2, 8, 2, 0, 0, 0)) + c(b"IDAT", zlib.compress(raw)) + c(b"IEND", b"")
   rec = FlightRecorder("http://127.0.0.1:8445", key=os.environ["DECOSA_API_KEY"])
   rec.start("Smoke test: open the settings page.", agent={"name": "smoke"})
   rec.step(observation={"url": "https://app.example/", "screenshot": png(200, 30, 30), "text": "[1] link \"Settings\""},
            decision={"model": "none", "output": '{"action":"click","element":1}'},
            action={"type": "click", "target": {"index": 1, "name": "Settings"}}, result={"ok": True})
   rec.send_images = False
   rec.step(observation={"url": "https://app.example/settings", "screenshot": png(30, 200, 30)}, action={"type": "done"})
   record = rec.seal("done")
   print(rec.verify(record)["summary"])
   record["entries"][3]["target"]["name"] = "Delete account"
   print(rec.verify(record)["summary"])
   ```
   Expect `Verified: ...` and then `Verification failed at step 1 action ...`. The second step's screenshot is only a
   hash on the record.
4. With `llm`: post `/flight/runs/{id}/decide` with `{"observation": {"url": "https://app.example/"}, "elements":
   [{"i": 1, "role": "link", "name": "Settings"}], "page_text": "Home"}` on a run whose task says "open the settings
   page". Expect a `click` on element 1 and a `decide` entry with status `attested`. Tell me the latency you see.
5. Time the recorder: 20 steps with a real 1280x800 screenshot each. On our box the median was 18 ms per step with
   images and 8 ms hash-only. Tell me what you measure.

## 5. Point the agents at it
- Python agents: the SDK above (`FlightRecorder(API, key=..., send_images=False)`); Playwright agents also fetch
  `/flight/sdk/playwright_agent.py` (`observe_page(page)` gives the screenshot and element table in one call).
- The Jev macos-harness: fetch `/flight/sdk/jev_macos.py`; either hook the loop (`JevHook`) or import a finished run
  directory with `python jev_macos.py runs/<dir> --api http://127.0.0.1:8445 --key $DECOSA_API_KEY --hash-only`.
- OpenAI computer-use style loops: fetch `/flight/sdk/openai_cu.py` and wrap `computer_call` / `computer_call_output`.
- The site: set `NEXT_PUBLIC_DECOSA_API=http://127.0.0.1:8445` in `.env.local` to use the viewer against this box.
  Contract: `API_CONTRACT.md`, section "Agent flight recorder".

Off by default. Joining serves other people's requests on this GPU; never do it on a box that records screens with
personal data. If I ask for it, follow the provider guide at `/provide` on the site, and do not enable it without my
explicit yes.