Work with an agent in the browser sandbox

Pyric connects your coding agent on your machine to the sandbox running in your browser. The agent does not get a second copy of the backend: its MCP calls cross the bridge into the tab your app and Studio already use.

Start the bridge, then keep the served app open in a browser tab:

pyric dev --bridge

pyric dev records the running server in .pyric/serve.json. The pyric mcp process used by Claude Code, Cursor, Codex, or another MCP client reads that pointer and proxies tool calls to /__pyric/mcp. The browser tab is the peer that owns the sandbox state, so forwarded data tools need that tab to stay open. Rules-only tools such as linting and module resolution run in the MCP process and do not need the tab.

If you have not configured the client yet, follow Connect an agent to the sandbox.

Diagnose a denied write

Give the agent the task you actually need solved, including the user and operation:

Alice is signed in but cannot update profiles/alice. Find the denial, explain which rule rejects it, and propose the smallest rules change. Do not edit the rules yet.

The agent starts with sandbox_inspect, which returns the loaded rules, lint summary, document counts, and recent requests. It can then use firestore_simulator_events to inspect the request history and firestore_get_document to compare the stored document with the attempted write.

The important part of the prompt is not a tool name. It is the real identity, path, operation, and desired outcome. The agent chooses the inspection tools from that task.

Seed a scenario and prove the access rules

Ask for both the useful path and the attack you want rejected:

Create projects/p1 owned by Alice. Prove Alice can rename it and Bob cannot. Show me both verdicts and leave the sandbox with the seeded project.

The agent can create the document with firestore_create_document, read it with firestore_get_document, and run the two hypothetical requests with firestore_simulate_rules. For a longer sequence it can open a stateful session with firestore_simulator_create, execute operations with firestore_simulator_execute, and inspect the result with firestore_simulator_read.

This is also useful for query rules:

Seed three posts: two published and one private draft owned by Alice. Find a query that lets a signed-out user list only published posts, run it, and confirm the draft is absent.

That task exercises firestore_create_document and firestore_query_where against the same data visible in the browser.

Correct rules and check the result

Ask the agent to prove the fix before it changes your file:

Update these Firestore rules so users can edit only their own profile and cannot change ownerId. Lint the candidate, simulate an owner update and an ownership-transfer attempt, then edit the file only if both cases pass.

The agent can use:

• firestore_lint_rules to catch invalid rules syntax, production limits, and common JavaScript-shaped mistakes;
• firestore_simulate_rules to evaluate explicit allow and deny cases;
• firestore_rules_stdlib_list and firestore_rules_stdlib_get to find tested helpers;
• firestore_resolve_modules to compile 2+modules imports into deployable Firestore Rules.

Those tools return evidence the agent can show: lint findings, each simulated verdict, and the resolved source. They do not deploy anything.

Inspect Realtime Database data

The browser bridge also exposes the current RTDB sandbox:

Inspect the Realtime Database tree. Check whether a signed-in user can write another user’s /profiles/{uid}/displayName, and explain the rule that decides it.

The agent uses rtdb_crawl_structure to discover the current paths and rtdb_simulate_access to test the request. These tools inspect and simulate local state; they do not connect to a production database.

Know which side runs each tool

There are two execution paths:

If a Firestore document tool reports that no browser peer is connected, open the served app and retry. Do not start a second dev server: that creates a second sandbox, and the agent may modify the one you are not looking at.

Review what the agent changed

Keep the Traffic view open while the agent works. Every sandbox request appears there with its identity and verdict, so you can compare the agent’s report with the operations the browser actually saw. Review agent activity shows how to filter that stream and replay a request.