Skip to main content
Agent skill

Pyric Node Host

Install Pyric from a local checkout, start a project's sandbox in Node host mode, and exercise it. Use to test hosted mode, where one Node process runs the sandbox for every browser and tool and keeps state in SQLite. Requires a cloned Pyric repository, because Node host mode is not published to npm. Don't use for ordinary Pyric work (use pyric) or to convert an app that already runs the SharedWorker sandbox (use pyric-migrate-to-node-host).

All install options
Quick install · Personal (~/.claude/skills)Project / Cursor / Desktop →
mkdir -p ~/.claude/skills/pyric-node-host && curl -fsSL 'https://raw.githubusercontent.com/davideast/pyric/main/.agents/skills/pyric-node-host/SKILL.md' -o ~/.claude/skills/pyric-node-host/SKILL.md

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Pyric Node Host when an AI agent needs a reusable SKILL.md workflow for this job: Install Pyric from a local checkout, start a project's sandbox in Node host mode, and exercise it. Use to test hosted mode, where one Node process runs the sandbox for every browser and tool and keeps state in SQLite. Requires a cloned Pyric repository, because Node host mode is not published to npm. Don't use for ordinary Pyric work (use pyric) or to convert an app that already runs the SharedWorker sandbox (use pyric-migrate-to-node-host).

When not to use it

Skip Pyric Node Host when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
One-line install (Claude Code)
mkdir -p ~/.claude/skills/pyric-node-host && curl -fsSL 'https://raw.githubusercontent.com/davideast/pyric/main/.agents/skills/pyric-node-host/SKILL.md' -o ~/.claude/skills/pyric-node-host/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/pyric-node-host/SKILL.md. For a shared project, commit the folder at .claude/skills/pyric-node-host/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Pyric Node Host skill for this task: Use Pyric Node Host when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

69/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
56/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Test Pyric's Node host mode

Run this project's sandbox in one long-lived Node process instead of a per-browser SharedWorker, then exercise it and report what you find.

## What is different in this mode

- The sandbox runs in the dev server's Node process. Every browser, Studio, the CLI, and MCP tools attach to that one sandbox and see the same data. - State is durable. It lives in `.pyric/state/hosted/state.sqlite` and survives restarts. Persistence is always on; there is no `--persist` to add. - The bridge is mounted automatically. Do not add `bridge: true` or `--bridge` for it. - One host owns a project at a time. A second start in the same project is refused with `A hosted sandbox already owns this project's hosted state. Attach to its bridge or stop it before starting another hosted sandbox.` Attach to the running one instead. - `GET <url>/__pyric/health` reports `"sandboxConnected": true` as soon as the host starts. No page has to be open, because the Node process is the sandbox.

## Requirements

- Node 22.15 or later. Hosted mode uses `node:sqlite`. It refuses to start under Bun and in the standalone binary, and says so. Run the launcher with Node even if the project uses Bun as its package manager. - A cloned Pyric repository. Ask for its path if you were not given one. Call it `<pyric>` below. - Bun and npm on the PATH. The checkout builds with Bun; packing uses npm.

Node prints `ExperimentalWarning: SQLite is an experimental feature` on every hosted start. That is expected.

## Choose the checkout branch

Use `main`. It carries Node host mode and every fix from its review, including restoring RTDB, presence, and event-stream subscriptions after a host restart, and the bounded engine event log. Pull before you pack. Say which commit you tested in your report.

## Install from the checkout

Never install `@pyric/cli@latest` for this. The published package has no Node host.

1. Build and pack, from the project being tested. The script ships with this skill in the checkout:

```sh bash <pyric>/.agents/skills/pyric-node-host/scripts/pack-local.sh <pyric> .pyric-local ```

It builds the checkout, packs `@pyric/rules`, `pyric`, `pyric-admin`, `create-pyric`, and `@pyric/cli`, rewrites their `workspace:*` ranges, and prints the five tarball paths. 2. Install all five together as development dependencies, by relative path, with the project's package manager. With npm:

```sh npm install --save-dev ./.pyric-local/pyric-*.tgz ./.pyric-local/create-pyric-*.tgz ```

All five must be installed in one command. `@pyric/cli` depends on the other three, and `pyric` on `@pyric/rules`, at a version that exists only in these tarballs. 3. Add `.pyric-local/` and `.pyric/` to `.gitignore`. Do not commit the tarballs or the `file:` dependency lines; this install is for testing. 4. Confirm the version: `npx --no-install pyric --version` prints a version newer than npm's `latest`.

After pulling new commits in `<pyric>`, run the pack script and the install command again.

## Start one host

1. Inspect `package.json`, `vite.config.*`, `firebase.json`, and `pyric.json`. 2. Choose one launcher: - **Vite:** in the existing `plugins` array, use one `pyric({ hosted: true })` call, imported from `@pyric/cli/vite`. Keep the project's other options such as `seed` and `rules`. Start the existing dev script under Node. Hosted mode needs Vite's own HTTP server; it does not support Vite's middleware mode. - **Any other app:** `pyric sandbox --hosted --json -- <command>`, with Pyric flags before the child command. With no child command, `npx --no-install pyric sandbox --hosted --json` starts only the host. 3. Keep the URL the launcher prints. With `--json` it is the `url` field; `restoredDocs` and `restoredUsers` report what was loaded from the store. 4. Keep the process running in the background. Stop it with an interrupt signal, not a kill, so it drains in-flight work and closes the store.

## Verify before testing

1. `GET <url>/__pyric/health` returns `"sandboxConnected": true`. 2. `npx --no-install pyric serve diagnostics --json` reports `server.mode` as `"hosted"` and `server.persistence.state` as `"healthy"`.

Report the URL, the branch and commit of `<pyric>`, and both results before going further. If `persistence.state` is `"unhealthy"`, stop and report; the host refuses every further write by design until it is restarted.

The plugin's `pyric` MCP server discovers the host through `.pyric/serve.json`, as in any Pyric session. Data tools work without a page open.

## What to exercise

Work through these and record the observed result for each. Each line states what should happen.

1. **Restart durability.** Write Firestore documents, RTDB data, an Auth user, and a Storage object. Interrupt the host and start it again. All four are present, and the launcher's `restoredDocs` and `restoredUsers` are nonzero. 2. **Two clients, one sandbox.** Open the app in two browser profiles, or a browser plus MCP tools. A write from one reaches a listener in the other without a reload. 3. **Host restart with a page open.** Leave a page with Firestore and RTDB listeners open, restart the host on the same port, then write. The page recovers its listeners and receives the write without a reload. Operations issued while the host is down follow ADR-0019 decision 7 (`docs/decisions/0019-native-client-reconnect.md`), so check each case on its own: - Issued while disconnected, host back within 10 seconds of the call: the client holds the operation and sends it once, in issue order, after its listeners and Auth are restored. The write is present after the restart. - Issued while disconnected, host not back within 10 seconds: the operation fails once with `unavailable` and `The hosted sandbox connection was not restored within 10 seconds. The request was not sent.` (`The remote sandbox connection ...` from a Node process using `PYRIC_SANDBOX=remote`). It is never sent later, so the write is absent after the restart. - In flight when the socket dropped: a Realtime Database `set`, `update`, `remove`, `push`, `setPriority`, `setWithPriority`, or `get` is sent again on reconnect, as the RTDB SDK does; a sent `runTransaction` rejects with `Error('disconnect')`; any other operation, including every Firestore write, fails once with `unavailable` and is not re-sent.

A write that is sent after the 10-second window, or one that is lost or duplicated in any case above, is a finding. 4. **Reset and checkpoint load with live listeners.** Each listener fires once per state change, not twice. RTDB rules still apply after a reset. 5. **Interrupted write.** Kill the host with SIGKILL during a burst of writes, then start it. It recovers from the write-ahead log and every acknowledged write is present. 6. **Second host refused.** Start a second host in the same project. It exits with the ownership message and the first host is unaffected. 7. **Fresh start.** `--fresh` (or `fresh: true` in the Vite options) archives the current store and starts empty. The archive is a directory, `.pyric/state/hosted.archive-<time>-<id>`. To go back, stop the host, move the current `.pyric/state/hosted` aside, and rename the archive to `.pyric/state/hosted`. The launcher prints the same instruction. 8. **Memory under sustained writes.** Watch the Node process's resident memory across several minutes of writes. It levels off. Growth that keeps climbing in step with the bytes written is a finding; report the branch, the write size, and the numbers.

## When something breaks

- Never delete `.pyric/state/` to get unstuck. It is the evidence. If a start is refused with `Hosted state could not be restored`, the message names the repair command:

```sh pyric sandbox salvage --source .pyric/state/hosted --out ./recovered ```

It writes every readable record to the new directory, lists each excluded record in `recovery-report.json`, and never modifies the source. Report the refusal and the recovery report. - For any failure, capture `pyric serve diagnostics --json`, the host's stderr, the steps, and the `<pyric>` commit. Do not paste document contents that the owner would not want shared. - A first start with `--seed` into an empty store prints `--seed applied` with its counts. A later start prints the restored counts and skips the seed, because a seed loads only into an empty store.

Intended uses

  • Use Pyric Node Host when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.