Statelock: Deterministic guardrails for browser agents, enforced at CDP

Statelock, an open-source project from Inferlink, released a Chrome DevTools Protocol (CDP) proxy that enforces deterministic policy checks on AI browser agents before each click, keystroke, upload or download and records evidence for every decision. The tool installs as the PyPI package `statelock-ai` (importing as `statelock`; the PyPI package named `statelock` is an unrelated project) and works with Playwright, browser-use, Stagehand, LangChain or any CDP client against headless Chromium. In its built-in finance demo, a policy comparing `bank_deposit_amount` with `erp_invoice_amount` blocked a "Mark as Paid" click because the deposit was $4,900.00 against a $5,000.00 invoice, with the page, checked values, verdict and a screenshot stored under `artifacts/sessions/<session id>/`.

Statelock adds policy checks and evidence to AI browser automations. It is a Chrome DevTools Protocol CDP proxy between your agent Playwright, browser-use, Stagehand, LangChain or any CDP client and a headless Chromium. Before each click, keystroke, upload or download, Statelock captures the page and checks your policy, then releases or blocks the action. After a commit action it checks post-conditions. It records evidence for every decision. An agent can then work in a real web portal inside clear limits: it may decline a manuscript but not send it to review, or mark an invoice as paid only when the bank deposit matches. Install it the package is statelock-ai and imports as statelock ; the PyPI package named statelock is an unrelated project : pip install statelock-ai python -m playwright install chromium Write a policy and a key for your agent. This policy blocks "Mark as Paid" on the built-in finance demo when the bank deposit and the invoice differ: cat policy.yaml <<'EOF' policies: - agent id: finance agent target url contains: /demo/finance pre conditions: - assert field equal: {left: bank deposit amount, right: erp invoice amount} EOF statelock keygen --agent-id finance agent --append keys.yaml prints the agent's key; keys.yaml holds only its hash Start Statelock with the demo pages on: STATELOCK POLICY FILE=policy.yaml STATELOCK AUTH KEYS FILE=keys.yaml STATELOCK ARTIFACT DIR=artifacts \ STATELOCK DEMO=1 statelock --port 8010 In another shell, run an agent that tries to mark a mismatched invoice as paid: export STATELOCK URL=http://localhost:8010 STATELOCK API KEY=slk ... the key keygen printed cat agent.py <<'EOF' import asyncio from playwright.async api import async playwright import statelock.client async def main - None: async with async playwright as p: async with await statelock.client.connect playwright p as governed, governed.guard : await governed.page.goto "http://localhost:8010/demo/finance?scenario=mismatch" await governed.page.click "text=Mark as Paid" asyncio.run main EOF python agent.py StatelockPolicyViolationError: pre condition/assert field equal Blocked action because bank deposit amount $4,900.00 did not equal erp invoice amount $5,000.00 ... The click never reached the page. artifacts/sessions/<session id / holds the evidence: the page, the values checked, the verdict and a screenshot. For sync Playwright, browser-use, LangChain, CrewAI, Stagehand and JavaScript agents, see Connecting an agent https://github.com/inferlink/statelock/blob/main/README.md connecting-an-agent . From a checkout of this repository, start the development proxy and run the two finance cases. The development stack supplies demo keys and enables the demo pages; no local Python installation or key generation is needed. cp .env.example .env compose.yaml reads it env file ; the defaults are fine docker compose -f compose.yaml -f compose.dev.yaml up -d --build statelock docker compose -f compose.yaml -f compose.dev.yaml --profile finance-agent run --rm finance-agent docker compose -f compose.yaml -f compose.dev.yaml --profile finance-pass-agent run --rm finance-pass-agent The first agent is blocked because the deposit is $4,900 and the invoice is $5,000; the second completes when they match. The rule is in policies/default.yaml https://github.com/inferlink/statelock/blob/main/policies/default.yaml , under finance reconciliation agent : it compares bank deposit amount with erp invoice amount before the action and checks for "Reconciliation complete" afterward. See Policies policies to write your own. For the test suite, base-proxy Docker setup and other demos, see Development development , compose.dev.yaml https://github.com/inferlink/statelock/blob/main/compose.dev.yaml and the OJS walkthrough https://github.com/inferlink/statelock/blob/main/examples/ojs/README.md . 1. Admission. The agent connects with a single-use session URL, or to ws://<host /statelock with Authorization: Bearer <key , x-statelock-agent-id optional; it must match the key , and optionally x-statelock-session-id a UUID . A missing, unknown, disabled or expired key, a key for another agent, or an agent without a policy is refused 4401 , as are invalid or reused session IDs 4409 . 2. Governed Chromium. Each session gets its own Chromium, started with a minimal environment. CDP runs over a pipe --remote-debugging-pipe , so there is no DevTools port a page could reach. CDP is forwarded in both directions; only valid JSON is forwarded, exactly as Statelock evaluated it. Commands that would bypass governance are refused: - wrapped commands Target.sendMessageToTarget and Debugger.setScriptSource ; - loading anything but an http s URL or about:blank javascript: , file: , data: , blob: , chrome: , view-source: ; - Target.exposeDevToolsProtocol , Network.replayXHR and Page.setDocumentContent ; - commands that reach Statelock's own isolated worlds; - agent network interception page.route , any Fetch. , agent-selected browser proxies and certificate-error overrides. 3. wrapped commands 4. Page guard. Installed on every page and iframe before the agent's commands reach it. On governed pages URLs your policies cover it: - cancels synthetic clicks, submits, drops and pastes element.click , dispatch event ; - clears files that code puts into file inputs including Playwright's own set input files over remote CDP; statelock.client.install routes it through Statelock, see Files https://github.com/inferlink/statelock/blob/main/README.md files ; - blocks page loads and requests started by the agent's own page code; - blocks form submissions code makes form.submit , and form.requestSubmit outside a real click, Enter or touch ; - also guards the page's iframes srcdoc, about:blank and other origins , like the page. 5. cancels synthetic clicks, submits, drops and pastes 6. Governed input. For each input command mouse, key, text, touch, drag and drop, IME, gestures, and DOM.setFileInputFiles Statelock: - captures state from the command's tab, in its own isolated world: URL, text, the element under the pointer or focused, fields, accessibility tree, screenshot; - evaluates pre-conditions; - forwards or blocks the command; - for commit actions mouse release, touch end, tap, drop, Enter release , holds the browser's response, evaluates post-conditions, then releases or blocks. 7. Attribution. Code the agent sends Runtime.evaluate , Runtime.callFunctionOn , ... is tagged, so every request can be attributed to agent code , agent navigation , site or unknown . Real input and the site's own code are never blocked by the guard, so multi-step tasks work normally. 8. Evidence. - One record per action, in sequence order: artifacts/sessions/<id /action-XXXX/context.json plus screenshots. - A request log per session: network.jsonl . - Redacted: injected secrets, SSNs, card-like numbers that pass the Luhn check, and emails. - Written to STATELOCK ARTIFACT DIR ; with Docker, this repo's ./artifacts . Plain JSON: tamper evidence comes from Statelock Enclave https://github.com/inferlink/statelock/blob/main/README.md statelock-enclave . 9. One record per action, in sequence order: 10. Violations. The agent receives an in-band CDP error and the session closes 4403 pre-condition, 4412 post-condition . GET /violations/<session id serves the details, and the client SDK raises StatelockPolicyViolationError . See COVERAGE.md https://github.com/inferlink/statelock/blob/main/COVERAGE.md for what is and is not analyzed. policies: - id: finance-reconciliation optional; names the policy in verdicts and evidence agent id: finance reconciliation agent required target url contains: /demo/finance omit to apply to every page allow synthetic events: false true disables the page guard for this policy pre conditions: one rule per entry, optionally with a trigger - require page text: {values: Bank Deposit, ERP Invoice } - assert field equal: {left: bank deposit amount, right: erp invoice amount} - prohibit click text: {values: Delete, Void } - trigger: {click text: Mark as Paid } only just before that button is pressed assert compare: {left: erp invoice amount, op: "<=", value: 10000} post conditions: the same, checked after the action - trigger: {click text: Mark as Paid } or key: Enter require page text: {values: Reconciliation complete } cookie access: optional; default: the agent reads no cookies names: csrftoken exact names; or domains: ... ; or all: true target url contains matches the page URL as scheme://host :port /path , without query, fragment or user info. A path-only scope matches as a substring. An absolute scope https://host/path needs that exact origin and a path equal to its path or below it. A trigger limits an entry to particular actions. It goes in the entry beside the rule, not inside the rule's options. On a pre-condition it runs only when an element whose text or aria-label contains a click text value is activated pressed, touched, tapped, dropped on, or Enter/Space while focused , or on the key down of a listed key : it checks the page just before the button acts. On a post-condition it runs after that action, on the page it led to. Without a trigger, pre-conditions run on every action on the policy's pages and post-conditions after every click or Enter. An unresolved click target counts as a match fail closed . restrict uploads and restrict downloads take no trigger. id names the policy in verdicts, violations and the evidence policy id , so with several policies for one agent the record says which one blocked. Without it the id is <agent id <n : the agent's n-th policy across the loaded policy files, in load order so reordering policies renames the defaults; set id where it matters . Ids are unique across all loaded policy files. cookie access applies to the agent the union of its policies . Cookies are not exported by default: with the site's session cookies, Playwright's page.request / context.request without install or another HTTP client would act as the logged-in user outside Statelock. So Statelock answers cookie reads over CDP context.cookies , storage state with only the cookies cookie access allows. With no cookie access , the read is declined cookie export , so those calls fail instead of bypassing Statelock, and the session continues. Either way the read is recorded, with cookie names, never values. Network events the agent receives are filtered too: Cookie , Set-Cookie , Authorization , Proxy-Authorization , X-Api-Key , X-Auth-Token , X-Csrf-Token and X-Xsrf-Token header values read REDACTED , cookie lists are empty, and raw header text is removed. all: true hands over the site's session cookies, which lets agent-side HTTP act as the user outside Statelock; use it knowingly. For HTTP, use request access agent-side-http-request access : after install , page.request goes through Statelock. A policy, keys or secrets file with a repeated key at any level two pre conditions: , two agents: sections is refused when it loads. An agent that needs HTTP a site's JSON API, a file behind a link can have Statelock make the request. Statelock runs it in the page, with the browser's session, so the agent needs no cookies: request access: optional; default: no requests - url pattern: "^https://portal\\.example\\.com/api/" regex matched from the start of the URL methods: GET, POST default GET max response bytes: 5000000 default 8 MiB, at most 11 MiB statelock.client.install then Playwright's own page.request works: invoices = await await page.request.get "https://portal.example.com/api/invoices" .json or without install : await statelock fetch page, url, method="POST", data={...} - Patterns. url pattern must start with ^https:// , ^http:// or ^https?:// , then a literal host escape dots as \. , an optional port :8443 , or : 0-9 + for any and / . It is matched from the start of the URL, and the URL must also begin with exactly that scheme://host :port / : no user info, and no port the pattern does not name. Wildcard hosts and | outside a group are rejected. - URLs. Statelock writes the URL as the browser reads it lowercase scheme and host, no default port, no fragment and checks, scopes and fetches that one string. A URL that Python and the browser could read differently is declined request access : spaces, control or non-ASCII characters, backslashes, user info user@host , . / .. path segments, IPv4 addresses not written as a.b.c.d , invalid ports and IPv6 zone ids. - Where it runs. Statelock makes the request with fetch in an isolated world of the page, as the site's own code would, so only same-origin or CORS-allowed URLs work. The browser's cookies go with it; the agent never receives them. - Recorded. Each request is an action record: URL, method, header names, body size, status, and the response's size and SHA-256. It shows as statelock request in the network log. - Declined. A request no rule allows is answered with an error request access , StatelockRequestError and recorded. The session continues. - Redirects. They fail before the destination request is sent. follow redirects: true is rejected during policy validation because the destination cannot be checked before the browser follows it. - Secrets. Header values may use {{secret:name}} for example Authorization: Bearer {{secret:api token}} . The secret needs password fields only: false , and the request URL must be in its scope see Credentials https://github.com/inferlink/statelock/blob/main/README.md credentials . A placeholder that is not allowed ends the session secret injection , and the value is removed from the response if the endpoint echoes it. - Concurrent. A request runs alongside the agent's other commands, at most STATELOCK MAX CONCURRENT REQUESTS 4 at once per session. One more is declined request concurrency , StatelockRequestError and recorded; the session continues. - Not supported through page.request : multipart , max redirects , max retries , ignore https errors . Rules read named fields. A field is either data-statelock-key / data-statelock-value markup on the page, or a policy fields entry, which works on sites you cannot change: - agent id: portal reconciliation agent target url contains: /demo/erp fields: - name: bank deposit url contains: /demo/bank default: the policy's target url contains allowed origins: "http://statelock:8000", "http://localhost:8010" selector: " deposit-amount" CSS selector; or key: <data-statelock-key attribute: title read an attribute instead of the text pattern: "\\$ 0-9,. + " optional regex; group 1 is the value remember: true keep the latest value for this session - name: erp invoice selector: " invoice-amount" - {name: invoice id, from url: true, pattern: "/invoice/ \\d+ "} from the page URL - {name: open dialogs, selector: ".modal", visible: true, read: count} - {name: note length, selector: "body", frame: "iframe note-editor", read: length} pre conditions: - assert field equal: {left: remembered.bank deposit, right: erp invoice} - assert compare: {left: erp invoice, op: "<=", value: 10000, on fail: review} - restrict uploads: {extensions: .pdf , max bytes: 5000000, max files: 1} A field reads one of: selector the first match's text, or attribute , key data-statelock-key markup , or from url: true the page URL; use pattern . A policy field is read only as the policy defines it, never from markup of the same name. data-statelock-value applies only to data-statelock-key fields; a selector field reads what the page shows. url contains matches like target url contains . Selector fields also take: - frame : a same-origin iframe to look in a rich-text editor's body, say ; - visible: true : only elements that are shown: rendered not display: none , visibility: hidden , opacity: 0 or hidden content, itself or an ancestor , with a box larger than a pixel that is not left of or above the page below the fold counts ; - read: count how many elements match, 0 for none or read: length characters of the value . A password field is never read; read: length is the only thing Statelock takes from one. remembered.<name is the latest value of a remember: true field seen anywhere in the session any tab . A remembered field must name trusted origins with allowed origins , or use an absolute url contains scope; a path alone could be copied on another site. Statelock captures it at each governed action, when a matching page finishes loading and again 0.5 s later , and before the agent navigates away goto, reload, back/forward . Each action record stores the remembered values with their URL, source and time, and a rule that needs a missing value blocks. Built-in rules: | Rule | Where it can be used | What it checks | |---|---|---| | require page text | pre and post | The page text contains each listed value. Text is compared after Unicode NFKC and case folding, ignoring invisible characters soft hyphen, zero-width space and differences in whitespace. | | prohibit page text | pre and post | The page text contains none of the listed values an error message, a login form after logging in , compared like require page text and also ignoring spaces altogether "MarkasPaid" matches "Mark as Paid" . Blocks if the page text was cut short or parts of the page could not be read. | | assert field equal | pre and post | Two fields or remembered values hold the same value, or a field equals a fixed value . Numbers compare as numbers; text compares after Unicode NFKC and case folding, ignoring only whitespace and punctuation punctuation between digits and a leading minus are kept . Amounts in different currencies are never equal: ISO 4217 codes upper case, next to the amount and symbols are compared "€5" equals "5 EUR" , and "$" or "¥" alone is not taken as any one code "$5" does not equal "USD 5"; "US$5" does . | | assert compare | pre and post | A numeric comparison < , <= , , = , == , = of a field with another field right or a constant value . | | prohibit click text | pre only | The clicked or touched element, or the focused element for Enter/Space, does not contain a listed text. Text is compared like require page text . | | restrict downloads | pre only | Downloads the page starts: allowed extensions , name pattern , source url pattern and max downloads per session when the download begins; max bytes when it completes. A blocked download is cancelled or deleted and ends the session. | | restrict uploads | pre only | Governed uploads: allowed extensions , max bytes per file, max files per upload, name pattern . Other actions pass. | | visual assert | pre and post | A vision-language model judges the screenshot and can read values off it; cross check compares those with page fields. Fails closed see below . | - Text rules. require page text , prohibit page text and prohibit click text need at least one value with visible characters. - Numbers. $5,000.00 , -$5 , $-5 , −5 Unicode minus and 1,234.00 negative parse. Ambiguous formats such as 5.000,00 , 5- or 12.50 do not, and the rule blocks. Amounts are compared exactly, at any length. - Loading. Entries with zero or several rules, unknown rules, and remembered.<name references to a name that is not a remember: true field of the agent are rejected when the policy file loads. Other field names cannot be checked then a page can supply them with data-statelock-key ; a missing field blocks at runtime. A rule that raises or does not answer within its time limit 30 s by default blocks the action. When a check needs more than page fields a lookup in the system that holds the decision, a call to another service , write it as a rule and name it in the policy like a built-in one: python from typing import ClassVar from statelock.policy.rules import Rule, RuleContext, RuleFailure, register rule @register rule class ApprovedInvoice Rule : rule name: ClassVar str = "approved invoice" phases: ClassVar frozenset str = frozenset {"pre"} check timeout: ClassVar float | None = 10.0 invoice field: str async def check self, ctx: RuleContext - RuleFailure | None: invoice = ctx.field self.invoice field if not await is approved invoice : your lookup; asyncio.to thread for blocking I/O return RuleFailure f"Blocked: invoice {invoice} is not approved", ctx.field evidence self.invoice field return None - trigger: {click text: Mark as Paid } approved invoice: {invoice field: invoice id} Statelock loads rule modules at startup from the statelock.rules entry point group a package that declares project.entry-points."statelock.rules" and from STATELOCK RULE MODULES module names or .py paths . Rules run inside the proxy, installed by whoever runs it; an agent cannot add one. A rule name can be registered once. examples/ojs/ojs rules.py is a worked example: it re-checks the editors' decision before a paper is declined. visual assert asks a vision-language model VLM about the screenshot Statelock captured for the action pre-conditions or after it post-conditions : pre conditions: - visual assert: check name: amounts match instruction: The bank deposit and the ERP invoice show the same amount. extract: {bank deposit: string} optional: values the model reads off the page cross check: optional: its reading must equal a page field - {extracted: bank deposit, field: bank deposit amount} when: activation default: presses, taps, drops, Enter/Space; or: all - Model. Any vision model litellm supports pip install "statelock-ai vlm " , hosted or self-hosted:Setup STATELOCK PERCEPTION MODEL STATELOCK PERCEPTION API BASE Hosted, e.g. the Gemini your agent already uses gemini/gemini-3.5-flash key in STATELOCK PERCEPTION API KEY none Ollama on the same machine ollama chat/qwen2.5vl:7b http://localhost:11434 vLLM on a GPU server in your network hosted vllm/Qwen/Qwen2.5-VL-7B-Instruct http://gpu:8000/v1 - Tested models the finance screenshots in tests/fixtures/perception : one where the amounts match, one where they differ . Gemini 3.5 Flash judged both correctly and read all four amounts, in 3–5 s per check. Qwen2.5-VL 3B through Ollama, on the CPU in Docker on a Mac, read all four amounts correctly, but called the mismatch a match, in 30–40 s per check. A model that small is not reliable for judgments: self-hosted, use a strong vision model on a GPU, and run tests/test perception model.py against it before relying on it. - What a hosted model receives. A screenshot of the page at every checked action, with the instruction. That can include customer data, and a secret typed into a field that is not a password field. Use a hosted model only where sending those screenshots to the provider is acceptable. - Local only. STATELOCK PERCEPTION LOCAL ONLY=true for air-gapped and regulated deployments makes Statelock refuse to start unless the model is self-hosted and on this machine or a private network. The model needs a self-hosted provider prefix ollama , ollama chat , hosted vllm , openai for an OpenAI-compatible server, lm studio , because a hosted provider can route to its own cloud. STATELOCK PERCEPTION API BASE must be local: loopback, RFC 1918 and Docker networks, link-local, unique-local IPv6, or an overlay network such as Tailscale 100.64.0.0/10 . A host name must resolve, and every address it resolves to must be local. This is checked once, at startup. It also stops litellm from downloading its model price list. - Strict output. The model must answer {"passed", "reason", "extracted"} matching a strict JSON schema sent as response format , temperature 0 . Output is validated with no type coercion and no extra keys. - Fails closed. No model configured, no screenshot, a timeout STATELOCK PERCEPTION TIMEOUT , a model error, or invalid output after STATELOCK PERCEPTION RETRIES more attempts: the rule fails with the reason. A failure blocks, or pauses for review with on fail: review . - Cross-checks. A model can misread or be fooled by the page. cross check compares each value it read with a DOM field numbers as numbers , so a visual check can back up, not replace, a deterministic one. - Cost. One model call per checked action: pre-conditions check activations only unless when: all . The same screenshot and question are answered from a cache. The agent's action waits for the model, so set its action timeouts above STATELOCK PERCEPTION TIMEOUT . - Evidence. The action record has the model's verdict, what it read, the model name, attempts and latency evidence.perception , evidence.cross check . - Try a model: statelock perception-check screenshot.jpg -i "The amounts match." -x bank deposit=string . tests/test perception model.py runs the finance fixtures tests/fixtures/perception against the configured model and prints its answers; it checks that they have the expected form and are correct PERCEPTION CHECK ANSWERS=false checks the form only . - Try a local model in Docker: the vlm profile in compose.dev.yaml runs Ollama with DEMO VLM MODEL default qwen2.5vl:3b and runs that test against it see Development development . It prints the answers and checks only their form, because a 3B model can misjudge; set DEMO VLM CHECK ANSWERS=true in .env to also require correct answers. Any pre-condition rule takes on fail : block the default ends the session; review pauses the action until a reviewer approves or denies it. - Only activations wait: a mouse press, a touch start, a tap, a drop, a file upload, and Enter, Space or a Ctrl/Alt/Meta shortcut. The approval covers the matching release, so one click is one review. Other actions moves, scrolls, plain typing continue; the failure is recorded as review deferred . - A failing on fail: block rule still blocks at once, without a review. - On approval, Statelock captures the page again. If a blocking rule now fails, or a reviewed rule fails differently for example, the amount changed , the action is blocked. - A denial, or no decision within STATELOCK REVIEW TIMEOUT 300 s , blocks the action and ends the session. The violation carries the review. - on fail: review is refused in post-conditions the action already ran and on restrict downloads a download cannot wait . A download whose page fails a review rule is blocked. - The action record stores a review block id, status, reviewer, comment, times, failed rules and review-screenshot.jpg , the page the reviewer judged. - Agents: Playwright's default 30 s action timeout ends before a person answers. Raise it context.set default timeout ... above the review timeout. Reviewers use http://<proxy /review , or the API with a reviewer key Authorization: Bearer : | Endpoint | Purpose | |---|---| | GET /reviews | Pending reviews of the reviewer's tenant ?status=approved\|denied\|expired\|cancelled\|all . | | GET /reviews/<id | One review: the paused action, page, fields, remembered values, failed rules. | | GET /reviews/<id /screenshot | The page when the action was paused JPEG . | | POST /reviews/<id /decision | {"decision": "approve" \| "deny", "comment": "..."} . 409 if already decided or expired. | Events review requested and review decided let plugins notify reviewers for example in chat . Policy Studio experimental helps draft a policy from tasks done by hand. Load Chrome Recorder JSON exports of runs the policy must allow and runs it must block with the step and the reason , write the checks each step needs in your own words, discuss them with a model of your choice through LiteLLM , and download a draft that passes Statelock's schema check. The raw recordings stay in the browser; you review each request before it is sent. Test a draft like any policy: start Statelock with it and run your agent on the same cases. It runs from a clone of this repository, natively or with Docker; see tools/policy-studio/README.md https://github.com/inferlink/statelock/blob/main/tools/policy-studio/README.md , and examples/ojs/POLICY STUDIO.md https://github.com/inferlink/statelock/blob/main/examples/ojs/POLICY STUDIO.md for a walkthrough. Agents authenticate with API keys STATELOCK AUTH MODE=api key , the default . The keys file stores only SHA-256 hashes. keygen --append adds each entry under its section and creates the file if it is missing ; the key is printed on stderr: statelock keygen --agent-id finance reconciliation agent --tenant acme --append keys.yaml statelock keygen --reviewer alice --tenant acme --append keys.yaml a reviewer key reviewers: section statelock keygen --auditor audit-team --tenant acme --append keys.yaml an auditor key auditors: section statelock hash-key < key.txt hash an existing key Without --append , keygen prints a complete keys file on stdout. Do not add that to an existing file with : a second agents: section makes the file invalid. agents: - agent id: finance reconciliation agent tenant: acme recorded with every action and violation key sha256: 3b1f... expires: 2027-01-01T00:00:00Z optional disabled: false optional; several entries per agent allow key rotation reviewers: - reviewer id: alice tenant: acme reviews only this tenant's sessions key sha256: 9c0d... auditors: for plugins that serve evidence - auditor id: audit-team tenant: acme reads only this tenant's evidence key sha256: 51ab... Each key has one role. Agent keys cannot use the review API, reviewer keys cannot open sessions, and auditor keys only read evidence through plugin routes. - The proxy needs STATELOCK AUTH KEYS FILE and fails at startup without it. compose.yaml mounts ./keys.yaml or STATELOCK KEYS FILE , which must exist. - The agent sends the key as Authorization: Bearer <key . The SDK takes api key= or the STATELOCK API KEY environment variable. - GET /violations/<session id needs the same key and returns only that agent's sessions 401 without a valid key, 404 for other agents' sessions . - Upload commands run on the agent's authenticated connection. - docker/dev-keys.yaml holds public development keys slk dev <agent id , slk dev dev reviewer for the reviewer, slk dev dev auditor for the auditor for the demo agents in compose.dev.yaml . Never deploy it. - STATELOCK AUTH MODE=none turns authentication off agent IDs are self-asserted; anyone may review, named by x-statelock-reviewer-id and logs a warning. Use it only for local development. - Plugins can protect their own routes with the FastAPI dependencies statelock.app.authenticated identity agents , statelock.app.authenticated reviewer reviewers and statelock.app.authenticated auditor auditors . For async Playwright, connect playwright is the whole integration: python import statelock.client statelock.client.install Playwright's file APIs and page.request go through Statelock async with await statelock.client.connect playwright playwright as governed: async with governed.guard : page = governed.page continue with existing Playwright code connect playwright reads STATELOCK URL and STATELOCK API KEY , creates a single-use session URL, connects Chromium over CDP, and returns the browser plus the session metadata; async with closes the connection at the end. Wrap the action section in async with governed.guard : so a blocked action raises StatelockPolicyViolationError with the rule and reason instead of looking like a closed browser: python from statelock.client import StatelockPolicyViolationError try: async with governed.guard : await page.click "text=Mark as Paid" except StatelockPolicyViolationError as violation: print violation.rule, violation.reason The guard looks the violation up with the key the session was created with else STATELOCK API KEY . If Statelock refuses that key or cannot be reached, it raises StatelockClientError with status instead of reporting no violation. The sync API has the same names ending in sync / Sync install sync , connect playwright sync , statelock guard sync , expect download sync , ... . statelock fetch is async only; create session url and the saved-session functions are plain blocking calls that both APIs use: python import statelock.client statelock.client.install sync with statelock.client.connect playwright sync playwright as governed, governed.guard : page = governed.page Under the hood, Statelock uses a CDP browser URL. Any framework that takes such a URL Playwright, Puppeteer, browser-use, Stagehand, LangChain or CrewAI browser tools can use one. After an action that navigates a click on a submit button, Enter in a form , wait for its result a URL, an element rather than for networkidle . Statelock returns the action once it has checked the policy's post-conditions, and by then the next page may already be idle, so a wait that only listens for a new networkidle event can miss it. Naming: a session is one governed browser session. SessionUrl is the single-use URL that opens one, PlaywrightSession is that session with its connected Playwright browser, statelock session page returns the {session id, agent id} of the page's session None for a browser not behind Statelock , and a saved session is a stored browser login that a new session can restore. The agent's key asks Statelock for a single-use URL: export STATELOCK URL=http://localhost:8010 STATELOCK API KEY=<the agent key statelock session-url prints http://localhost:8010/sessions/slt ... single use, expires in 300 s python from statelock.client import create session url session = create session url STATELOCK URL, STATELOCK API KEY browser = await playwright.chromium.connect over cdp session.cdp url async with session.guard : session.violation after the fact ... Stagehand: StagehandConfig env="LOCAL", local browser launch options={"cdp url": session.cdp url} - Two forms: cdp url is an http URL; frameworks read the WebSocket address from its /json/version . ws url is the WebSocket itself. - The token: it identifies the agent and the session. It is used up when the browser connects and expires after STATELOCK SESSION URL TTL . - Storage and logs: Statelock stores only the token's hash and redacts tokens from its logs. - Errors: a request Statelock refuses raises StatelockClientError , with the HTTP status . - Headers instead: agents that can send headers may connect to ws://.../statelock with Authorization: Bearer <key and the x-statelock-agent-id / x-statelock-session-id headers connect over cdp url, headers=... . An agent can reuse a site login without holding the cookies. A session URL names a saved session: Statelock puts its cookies and localStorage into the browser before the agent connects, and, with save session , saves them again when the session ends cleanly. A session that ends on a violation or an error is not saved, so the state after a blocked action is never kept. session = create session url saved session="bank-login", save session=True first run: logs in, saved at the end session = create session url saved session="bank-login" later runs: already logged in statelock session-url --saved-session bank-login --save statelock saved-sessions list or: statelock saved-sessions delete bank-login - Off until configured. Set STATELOCK SAVED SESSIONS KEY FILE to a path outside the saved-session directory, such as a mounted secret. Statelock creates the 32-byte key there mode 0600 if the file does not exist. Back it up: without it the saved sessions cannot be read. Without the setting, a request that names a saved session is refused 422 . - Encryption. Each file is encrypted with AES-256-GCM cryptography . The tenant, agent and name are bound to the file, so a file copied to another agent's name does not decrypt. - Scope. Saved sessions belong to one tenant and agent. Names are 1-80 characters: letters, digits, . , and - . They are stored under STATELOCK SAVED SESSIONS DIR default: STATELOCK ARTIFACT DIR/saved-sessions . - What is kept. Cookies HttpOnly included and the localStorage of each open page's origin. localStorage is restored through a hidden page at the origin that Statelock answers itself, so nothing reaches the site. Not kept: sessionStorage per tab, as after a browser restart , IndexedDB, and storage of cross-origin iframes. - API. GET /saved-sessions lists the calling agent's saved sessions and DELETE /saved-sessions/<name deletes one. The client has list saved sessions and delete saved session name . The agent never needs the password. It types a placeholder, and Statelock types the secret: await page.fill " password", "{{secret:bank password}}" the site receives the real password STATELOCK SECRETS FILE secrets: - name: bank password agents: finance reconciliation agent who may use it url contains: https://bank.example.com/login the origin, then this path or one below it value env: BANK PASSWORD or value file: /run/secrets/bank password password fields only: true default: only into password fields - Where it is typed. Statelock replaces the placeholder in typed text Input.insertText , which Playwright's fill sends, and Input.imeSetComposition after the action passes its pre-conditions. It does so only for the listed agents, on a page whose URL has exactly the origin in url contains http s ://host :port and a path equal to its path or below it /login covers /login/2fa , not /forum/login or /loginfoo , and by default only into a password field. Anywhere else, the placeholder ends the session secret injection . - What the agent sees. The placeholder. Statelock replaces the value with SECRET in every answer the browser sends the agent and in every request access response. Reading the field back returns SECRET . - Evidence. The typed text is recorded as SECRET , with the secret's name statelock secrets . The value is removed from action records and the network log. - Values. They are read from the proxy's environment or files when it starts, and a missing value fails at startup. The agent's own environment never holds them. - Limits. Typing the placeholder key by key keyboard.type sends it literally. Page code the agent runs could read the field and transform the value before returning it; no filter can recognise that. - With a saved session , the login usually happens once: later sessions start logged in. Cookies are not exported either see cookie access in Policies policies . What no SDK can stop: plain HTTP from the agent's own process for example requests with a password it holds . Use credential injection so the agent holds no password, and deploy the agent so it can reach only Statelock. statelock.client.install async or statelock.client.install sync sync , once at startup, routes Playwright's own file APIs through Statelock: - Uploads: set input files on a page, locator or element handle and FileChooser.set files upload the files through Statelock. The upload is governed, and the file's name, size and SHA-256 are recorded. - Downloads: page.expect download waits for the download Statelock checked. A download is checked when it begins the page's policies, including restrict downloads and when it completes size, SHA-256 . Its value works like Playwright's Download save as , path , suggested filename , url . Its default timeout is the page's set default timeout , as in Playwright. - Other browsers are untouched: each browser is asked once whether it is a Statelock session Statelock.session . - Without install : the session object has the same two methods: governed.set input files target, files, page=None, timeout=None and governed.expect download predicate=None, page=None, timeout=None page defaults to governed.page ; also statelock.client.set input files page, target, files and statelock.client.expect download page, predicate=None, timeout=None . timeout is in milliseconds, as in Playwright: by default the page's or context's set default timeout set after install , else 30000; 0 waits without a limit. A blocked download raises StatelockPolicyViolationError with the rule Statelock reports; a guard adds the recorded violation. A buffer must be bytes-like or str; anything else raises TypeError . A path's MIME type comes from its extension the same table as the JS SDK . Limits see the roadmap https://github.com/inferlink/statelock/blob/main/ROADMAP.md : - page.on "download" listeners are not covered, and install sync does not cover sync page.request yet. - File inputs inside iframes are not supported yet main frame only . - Upload rules restrict uploads check name, extension, size and count, not file contents. - File contents are not stored with the evidence. Only name, size and SHA-256 are recorded, and uploaded files are deleted when the session ends. Script clicks. Frameworks that click with page scripts element.click , as Stagehand does work without changes. Statelock scrolls the element into view and replays the click as real mouse input at the element, checked and recorded like any click. It is replayed only when the element is visible and not covered, in the top frame; otherwise the click is blocked. Synthetic events from the site's own code, and other synthetic events submit, drop, paste , are still blocked. browser-use. browser-use takes a CDP URL through BrowserSession and drives the browser over raw CDP, so every click and key press goes through Statelock pip install "statelock-ai browser-use " , tested with browser-use 0.13, Python 3.11+ : python from browser use import Agent from statelock.integrations.browser use import create browser use session governed = await create browser use session STATELOCK URL, STATELOCK API KEY agent = Agent task="...", browser session=governed.browser, llm=... await agent.run governed.raise if violation StatelockPolicyViolationError rule, reason browser-use reports a blocked action to its model as a failed step, not as an exception, so the run continues; Statelock has already ended the session, so nothing else gets through. governed.violation / raise if violation give the rule and reason afterwards. A lookup Statelock refuses a wrong key raises StatelockClientError , not "no violation". To build the browser-use object yourself, pass create session url .cdp url to BrowserSession cdp url=... . browser-use sends anonymous telemetry by default: set ANONYMIZED TELEMETRY=false to turn it off. LangChain and CrewAI. Give LangChain's Playwright toolkit a browser from a session URL, and wrap its tools with governed playwright tools pip install "statelock-ai langchain " : python from statelock.client import create session url from statelock.integrations.langchain import crewai tools, governed playwright tools session = create session url browser = await playwright.chromium.connect over cdp session.cdp url tools = governed playwright tools browser, session CrewAI: use sync Playwright, then tools = crewai tools governed playwright tools browser, session Every click and keystroke is governed without the wrapper. What the wrapper adds: - The agent learns why it stopped. Without it, a blocked action looks like "browser closed". With it, when a tool fails or the browser disconnects, the wrapper asks Statelock, and a violation raises StatelockPolicyViolationError rule, reason , which stops the agent run. Successful calls cost no lookup. - Timeout. It raises the click tool's 1 s timeout to 10 s, because a governed click waits for Statelock's checks. - Selector bug. It turns off the tool's visible only suffix. Current Playwright never matches it, so every click would time out. The wrapper returns copies; the tools passed in are not modified. statelock tools tools, session wraps other LangChain tools that drive the governed browser. CrewAI's StagehandTool only runs on Browserbase's cloud browsers, so it cannot use a Statelock session; use the LangChain toolkit through CrewAI instead. Stagehand. examples/ojs/ is a Stagehand agent on a mock journal: three Statelock lines in open session and run governed , and a password placeholder instead of the password pip install "statelock-ai stagehand " . JavaScript and TypeScript. @statelock/client js/ is not yet on npm; build it from js/ npm ci runs the build . It has: - createSessionUrl , session.guard , session.violation and secret ; - statelockFetch governed HTTP and listSavedSessions / deleteSavedSession ; - connectPlaywright with setInputFiles / expectDownload and install browser for Playwright's file APIs; - CDP helpers for other frameworks. examples/ojs-ts/ is the OJS agent in TypeScript on Stagehand v3. For other JavaScript frameworks, see the JS SDK README https://github.com/inferlink/statelock/blob/main/js/README.md frameworks . All settings are STATELOCK environment variables statelock/settings.py . With Docker, put them in .env : Compose passes it to the proxy container .env.example lists the common ones . The compose files set the policy, artifact and keys paths, and compose.dev.yaml also sets the demo, debug, secrets, saved-session, extra policy and rule module settings; those values override .env . | Variable | Default | Purpose | |---|---|---| | STATELOCK POLICY FILE | /app/policies/default.yaml | Policy bundle. A missing file fails at startup. | | STATELOCK EXTRA POLICY FILES | none | More policy files, comma-separated, loaded with STATELOCK POLICY FILE as one bundle ids unique across them . The dev stack adds examples/ojs/ojs policy.yaml . | | STATELOCK RULE MODULES | none | Custom rule modules, comma-separated: module names or .py paths, loaded before the policy files see Custom rules . | | STATELOCK ARTIFACT DIR | /app/artifacts | Local artifact root. | | STATELOCK PLUGINS | auto | auto , none , or a comma-separated list of plugin names. | | STATELOCK DEBUG | false | Also writes the latest action record to artifacts/latest.json . | | STATELOCK DEMO | false | Enables the demo pages /demo/finance , /demo/bank and /demo/erp . | | STATELOCK LOG LEVEL | INFO | Python logging level, set on the root logger all libraries . Empty leaves logging to the host. DEBUG also turns on statelock.cdp : one line per CDP message method and ids, never page data , to see where a stalled page load stopped. | | STATELOCK AUTH MODE | api key | api key or none development only . | | STATELOCK AUTH KEYS FILE | none | Keys file hashes . Required when STATELOCK AUTH MODE=api key . | | STATELOCK SESSION URL TTL | 300 | Seconds a session URL POST /sessions , statelock session-url stays usable at most 3600 . | | STATELOCK SECRETS FILE | none | Secrets agents type as {{secret:name}} credential injection . Values come from value env or value file ; a missing one fails at startup. | | STATELOCK SAVED SESSIONS KEY FILE | none saved sessions off | AES-256-GCM key for saved browser sessions, outside the saved-session directory. Created if missing. | | STATELOCK SAVED SESSIONS DIR | STATELOCK ARTIFACT DIR/saved-sessions | Where saved browser sessions are stored. | | STATELOCK UPLOAD DIR | system temp | Base folder for per-session upload folders deleted when the session ends . It must be readable by Chromium. | | STATELOCK UPLOAD MAX FILE BYTES , STATELOCK UPLOAD MAX SESSION BYTES | 100 MiB, 500 MiB | Upload limits. | | STATELOCK DOWNLOAD DIR | system temp | Base folder for per-session download folders deleted when the session ends . | | STATELOCK DOWNLOAD MAX FILE BYTES , STATELOCK DOWNLOAD MAX SESSION BYTES | 100 MiB, 500 MiB | Download limits; a larger download is cancelled download limit . | | STATELOCK PERCEPTION MODEL | none visual checks fail closed | litellm model for visual assert , e.g. gemini/gemini-3.5-flash , ollama chat/qwen2.5vl:7b or hosted vllm/Qwen/Qwen2.5-VL-7B-Instruct . Needs statelock-ai vlm . | | STATELOCK PERCEPTION API BASE , STATELOCK PERCEPTION API KEY | none | The model server's URL and key a local vLLM or Ollama server needs only the URL . | | STATELOCK PERCEPTION TIMEOUT , STATELOCK PERCEPTION RETRIES | 20, 1 | Seconds per model call; extra attempts after invalid output or an error. | | STATELOCK PERCEPTION LOCAL ONLY | false | Refuse to start unless the model server ... API BASE is on this machine or a private network. | | STATELOCK REVIEW TIMEOUT | 300 | Seconds a paused action waits for a reviewer before it is blocked. | | STATELOCK REVIEW HISTORY SIZE | 1000 | Decided reviews kept in memory for the review API. | | STATELOCK VIOLATION REGISTRY SIZE | 1000 | Violations kept in memory for GET /violations/<session id . | | STATELOCK MAX CONCURRENT REQUESTS | 4 | Statelock.fetch requests request access running at once in one session. Another one is declined request concurrency and recorded; the session continues. | | STATELOCK REPLAY SCRIPT CLICKS | true | Replay a plain element.click from agent code as a governed real click. false : such clicks are violations. | | STATELOCK AGENT SCRIPT GRACE | 0.5 | Seconds after agent code returns that a click it started still counts as the agent's and is replayed . | | STATELOCK REPLAY WAIT | 10 | Seconds the agent's next command waits, at most, for a replayed click to finish. | | STATELOCK CHROMIUM SANDBOX | false 1 in compose.yaml | Chromium sandbox. It needs a non-root user and a seccomp profile that allows user namespaces; compose.yaml provides both see docker/README-sandbox.md https://github.com/inferlink/statelock/blob/main/docker/README-sandbox.md . If the sandbox cannot start, sessions are refused. | | STATELOCK CHROMIUM START TIMEOUT | 30 | Seconds Chromium has to start and answer on its CDP pipe; otherwise the session is refused. | | STATELOCK CAPTURE TIMEOUT | 2.5 | Seconds a state capture may take before the action is blocked. | | STATELOCK POST CAPTURE SETTLE | 0.2 | Seconds to wait after a commit action before capturing the page for post-conditions. | | STATELOCK HELD RESPONSE TIMEOUT | 10 | Seconds to wait for the browser's response to a held commit action. | | STATELOCK VIOLATION CLOSE DELAY | 0.5 | Seconds between the in-band violation error and closing the session. | | STATELOCK GUARD READY TIMEOUT | 10 | Seconds an agent command on a new page or iframe waits for Statelock's setup there the page guard . | | STATELOCK CDP COMMAND TIMEOUT | 5 | Seconds Statelock's own CDP commands to the browser may take. | | STATELOCK ATTRIBUTION TIMEOUT | 1 | Seconds to wait for a request's initiator before it is logged as unknown . | | STATELOCK NAVIGATION STALL TIMEOUT | 10 | Seconds after which a page load that Chromium started but never handed to the page guard ends the session. Chromium rarely does this seen on a session's first page load, and later loads in that browser stall too . The agent's waiting command fails with "Chromium stopped loading pages; start a new Statelock session" instead of hanging, and the proxy log lists Chromium's processes and stderr. | | STATELOCK TRUSTED SUBMIT WINDOW | 3 | Seconds after a submit from real input during which the form's navigation counts as trusted. | | STATELOCK AGENT NAVIGATION WINDOW | 10 | Seconds after an agent navigation command during which a page load is attributed to it. | | STATELOCK MEMORY SETTLE | 0.5 | Seconds after a page load before the second capture of remembered fields. | Every number must be positive, except STATELOCK PERCEPTION RETRIES , STATELOCK POST CAPTURE SETTLE , STATELOCK VIOLATION CLOSE DELAY , STATELOCK AGENT SCRIPT GRACE and STATELOCK MEMORY SETTLE , which may be 0. An invalid value fails at startup. - Rules. Subclass statelock.policy.rules.Rule , decorate it with @register rule , and load it with a statelock.rules entry point or STATELOCK RULE MODULES see Custom rules . - Storage. Implement statelock.audit.sink.ArtifactSink . It receives versioned ActionRecord s schema "4" , statelock.audit.records ; the schema history is in that module in sequence order. - Plugins. Expose an object with name and setup ctx in the statelock.plugins entry point group. setup can: - replace or wrap ctx.services.sink ; - subscribe to ctx.services.events violation , action written , request recorded , review requested , review decided , session closed ; - add routes to ctx.app , which reach services with statelock.app.get services request.app . - replace or wrap - Perception. visual assert uses LiteLLMPerceptionEvaluator when STATELOCK PERCEPTION MODEL is set. For another backend, implement statelock.policy.perception.PerceptionEvaluator and set it on get services app .evaluator.perception in a plugin. Statelock Enclave is InferLink's commercial add-on for production and audit, built on the extension points above. It adds: - tamper-evident evidence storage hash chains, signed anchors, S3 Object Lock ; - a witness run by InferLink that countersigns each session's anchors in an append-only log, so an auditor who trusts neither you nor InferLink can check the evidence with statelock-verify , a verifier InferLink provides to auditors; - a forensic replay dashboard; - deployment inside your own cloud. src/statelock/ core/ shared types: actions, state, verdicts, enums; URL scopes and request URLs urls.py ; CDP JSON helpers policy/ policy schema, fields and remembered values, rule registry, triggers, evaluator, request access, cookie access, regex checks patterns.py , text normalization text.py , currencies currency.py , custom rule loading extensions.py , perception VLM audit/ record schema, redaction, sequenced writer, ArtifactSink, LocalJsonSink proxy/ bridge session , browser Chromium over a CDP pipe , connection, governor, replay script clicks , memory watcher, reporter, targets, inspector, guard, attribution, scripts, commands, cookies, network filter, requests, uploads, downloads, download policy, files, tasks, pages, worlds, js/ guard.js, page state.js, describe element.js, focused element.js, replay point.js, replay hits.js, fetch.js client/ SDK: session URLs, connect playwright / connect playwright sync playwright.py , install / install sync for Playwright's file APIs async files.py + install.py, sync files sync.py + install sync.py, protocol in transfer.py, patching.py , connection header path, internal , requests statelock fetch , violations integrations/ langchain.py LangChain / CrewAI browser tools , browser use.py browser-use review/ human review: queue of paused actions, review API, /review page demo/ /demo/finance, /demo/bank, /demo/erp STATELOCK DEMO=1 only app.py create app factory and routes; re-exports get services and the authenticated dependencies dependencies.py FastAPI dependencies: authenticated identity, authenticated auditor sessions.py, tokens.py session URLs POST /sessions, single-use tokens , /saved-sessions saved sessions.py encrypted saved browser sessions AES-GCM store, restore, save credentials.py credential injection: secrets file, {{secret:name}} placeholders, scrubbing auth.py agent, reviewer and auditor API keys main .py the statelock command: the proxy no subcommand , keygen, hash-key, session-url, saved-sessions, check-sandbox, perception-check settings.py, plugins.py, events.py, services.py, registry.py, wire.py, fileio.py tests/ unit tests; browser tests test browser .py, skipped without Chromium unless STATELOCK REQUIRE BROWSER=1 ; helpers conftest.py, helpers.py, fakes.py, browser support.py, ojs support.py ; fixtures/perception examples/ rogue agent.py, finance agent.py, portal agent.py; ojs/ Stagehand OJS agent, mock OJS site, its policy and custom rule, POLICY STUDIO.md ; ojs-ts/ the OJS agent in TypeScript on Stagehand v3 tools/policy-studio/ Policy Studio experimental, run from a clone : server.py, draft with model.py, core.js, studio.js; test/ js/ @statelock/client: the JavaScript/TypeScript SDK; src/ index.ts, sessions.ts, violations.ts, cdp.ts, http.ts, mime.ts, playwright.ts @statelock/client/playwright ; test/ policies/ default.yaml docker/ Dockerfile targets: runtime, dev, ojs , seccomp profile, dev keys, dev secrets, README-sandbox.md compose.yaml the proxy; compose.dev.yaml adds demos, demo agents, tests, the vlm profile and the policy-studio profile .github/workflows/ ci.yml lint, types, tests, extras, Policy Studio, JS , dco.yml sign-off check , release.yml PyPI and GitHub release Compose commands that use compose.yaml need .env , because it reads it env file: .env : run cp .env.example .env first. The Docker Quick start uses compose.dev.yaml , which mounts public development keys and enables demo pages. To run compose.yaml alone, first install the statelock-ai CLI, configure a policy for your agent, and create its keys file: statelock keygen --agent-id my agent --append keys.yaml docker compose -f compose.yaml up -d --build To run the test suite in Docker, use the development override: docker compose -f compose.yaml -f compose.dev.yaml --profile test run --rm statelock-tests To drop the -f flags, set COMPOSE FILE=compose.yaml:compose.dev.yaml in .env . To try visual assert with a local vision model profile vlm ; it needs only compose.dev.yaml : docker compose -f compose.dev.yaml --profile vlm up -d ollama docker compose -f compose.dev.yaml --profile vlm run --rm ollama-pull download the model, once docker compose -f compose.dev.yaml --profile vlm run --rm perception-tests perception-tests runs tests/test perception model.py against DEMO VLM MODEL default qwen2.5vl:3b , about 4 GB of memory . It prints the model's answers and checks only their form; set DEMO VLM CHECK ANSWERS=true in .env to also require correct answers. Other demo services and profiles are listed in compose.dev.yaml https://github.com/inferlink/statelock/blob/main/compose.dev.yaml ; the OJS walkthrough https://github.com/inferlink/statelock/blob/main/examples/ojs/README.md covers the journal agent. For a local development install: pip install -e ". dev " python -m playwright install chromium ruff check src tests examples tools/policy-studio && ruff format --check src tests examples tools/policy-studio && python -m mypy && python -m pytest -q - The proxy runs on Linux and macOS also under uvloop ; Windows is not supported. - Python 3.10+ the browser-use extra needs 3.11+ . The Docker images use Python 3.12 Playwright's Ubuntu 24.04 "noble" image . mypy is strict for core and policy . - The Docker image pins Playwright 1.64.0 Chromium 156 and runs as pwuser . On Linux hosts, ./artifacts must be writable by that user. - Injected JavaScript lives in src/statelock/proxy/js/ . - CI .github/workflows/ci.yml also runs the browser tests with STATELOCK REQUIRE BROWSER=1 , so they fail instead of skipping without Chromium, plus the extras' tests, the Policy Studio tests and the JavaScript SDK. - Contributions: see CONTRIBUTING.md https://github.com/inferlink/statelock/blob/main/CONTRIBUTING.md . Every commit needs a DCO sign-off git commit -s ; a check on pull requests enforces it. - Security issues: see SECURITY.md https://github.com/inferlink/statelock/blob/main/SECURITY.md . - Releases: the manual Release workflow publishes statelock-ai to PyPI and creates the GitHub release see CONTRIBUTING.md https://github.com/inferlink/statelock/blob/main/CONTRIBUTING.md releases . See ROADMAP.md https://github.com/inferlink/statelock/blob/main/ROADMAP.md .