Interfaces
AssetRequest
Properties
FlowConfig
JSON project configuration; module paths resolve from the project root.
Properties
| Property | Type |
|---|---|
treatment? | string |
treatments? | { description?: string; id: string; label: string; module: string; }[] |
OwnersConfig
JSON project configuration for listener and operation owners.
Properties
PyricOptions
Properties
| Property | Type | Description |
|---|---|---|
ai? | PyricAiOptions | Dev-server-level AI configuration for pyric/ai (the sanctioned replacement for threading engine through every app getAI(...) call, which is first-call-wins and easy to get wrong). pyric({ ai: { model: ‘llama3.2’, proxyUpstream: ‘http://localhost:11434/v1’, // your Ollama }, }) - model is the simple OpenAI-compatible path. It becomes the catch-all upstream model. PYRIC_AI_MODEL selects the same path when neither model nor engine is explicit. - engine is pyric/ai’s EngineConfig (scripted |
avatars? | PyricAvatarsOptions | Profile photos for sandbox provider users. Default: deterministic generated avatars. A string selects a pre-created avatar set (directory path, resolved from the project root). false disables the avatar route entirely. An object supplies a custom source that runs in the dev server, never the browser. |
bridge? | | boolean | { disableAuditLog?: boolean; project?: string; } | Mount the MCP bridge on Vite’s dev origin so an external agent (Claude Code, Cursor) can drive this sandbox over MCP — POST /__pyric/mcp + GET /__pyric/health + WS /__pyric/sandbox, all on Vite’s port. true is shorthand for {}. The agent and the page share ONE sandbox. Does NOT change the sandbox topology: on the default SharedWorker path the page dials the bridge WS and relays agent tool-calls THROUGH the worker (connectBridgePeer), so multi-tab stays on. The in-page fallback engages only when the worker bundle itself fails, bridge or not. |
capture? | boolean | Write the live session fixture to .pyric/last-session.json (for pyric verify). Default true; pass false to suppress. |
flow? | FlowConfig | Overrides the shared pyric.json Flow configuration. |
fresh? | boolean | With persist or hosted: discard existing state and re-seed on startup. |
functions? | | false | { instance?: string; region?: string; watch?: boolean; } | RTDB-triggered Cloud Functions under this dev server (the pyric sandbox parity fold). By default a functions block in firebase.json is discovered automatically: its onValueCreated triggers run in an isolated node child against the shared sandbox (other trigger kinds warn and are skipped), and the discovered codebase turns the MCP bridge mount on (the child dials the sandbox over the bridge WS — the page’s sandbox topology is unchanged, see bridge). functions: false is the off switch: no discovery, no child, no functions-forced bridge mount. Field precedence: explicit option > env var > firebase files > default. - region: the trigger location. Beats PYRIC_FUNCTIONS_RTDB_REGION; default us-central1. - instance: the RTDB instance name. Default <projectId>-default-rtdb, where projectId is the resolved project (see that option), else demo-project. - watch: hot-reload the functions source (default true, matching rules). A save under the functions source dir stops the child and respawns it — redeploy semantics: in-flight executions in the old child may drop, and writes landing during the swap gap are consumed as the new child’s baseline (they do not fire). Unlike rules, a broken save cannot keep last-good live — the old child is already gone — so functions stay down until the next good save. |
hosted? | boolean | Run the dev sandbox in the Vite server process, shared across browsers and Studio, with durable project state. Automatically mounts the bridge. Default: false (SharedWorker). Requires Vite’s own HTTP server; middleware mode is unsupported. Does not affect production builds. |
owners? | OwnersConfig | Overrides the shared pyric.json owners configuration, field by field. skip lists globs for the app’s data-layer wrapper modules, so a listener’s owner shows the code that called the wrapper; the wrapper’s frame stays on the owner’s stack. frames is how many application frames each owner keeps, counted from the frame it shows (default 3). |
persist? | boolean | Persist sandbox state to .pyric/state/state.json so data + test users survive reloads/restarts. Off by default for SharedWorker; hosted mode always persists state. |
project? | string | The Firebase project the sandbox runs as: a project id or a .firebaserc alias. It names the default Realtime Database instance, selects the .firebaserc deploy targets a firebase.json database array names, and is the functions child’s project. Without it, the project resolves as the Firebase CLI resolves it: PYRIC_PROJECT, then the firebase use active project for this directory, then .firebaserc projects.default. |
root? | string | Project dir for firebase.json / rules discovery. Default: Vite’s root. |
rules? | string | Firestore rules path (relative to root). Default discovery prefers an authored firestore.modules.rules, then firebase.json, then firestore.rules in the project root. |
runtimeChip? | PyricRuntimeChipOption | Inject the collapsed Pyric runtime chip into the app during sandbox Vite dev/builds. On by default. Pass false to hide it, or { initiallyOpen: true } when actively debugging runtime errors. |
seed? | string | Seed file: a "collection/doc" → fields JSON map, or a pyric snapshot state-file envelope. Applied at page init (state wins once it exists). |
serviceWorker? | string | The app’s own service worker module (path from the Vite root), such as a vite-plugin-pwa injectManifest source. In dev, the plugin adds a fetch listener to it that answers production Storage download URLs from the sandbox (sandboxStorageFetch from pyric/storage/sw), so the file needs no Pyric import. Builds are untouched. |
sessionToken? | boolean | Require a per-boot session capability token on every local /__pyric/* route, MCP, and WS /__pyric/sandbox (workspace, project, and AI proxy routes always require one). Default: false (or pyric.json#sessionToken). |
swapInBuild? | boolean | Force whether vite build runs the firebase→pyric swap, overriding the mode default. Unset (default): swap for any NON-production mode, keep real firebase for mode production. true = always produce a sandbox build; false = never swap in build (real firebase regardless of mode). vite dev is unaffected — the swap is always on there. |
ui? | boolean | Serve the Pyric Studio app at /__pyric/ui/ on Vite’s dev origin (the pyric sandbox --ui equivalent). Mounts the disk-backed workspace/project routes Studio’s local mode talks to AND serves the unified Astro site (vendored in this package at dist/serve/site-ui). On by default, including under bridge (the bridge peer routes through the SharedWorker, so app, Studio, and agent all observe the one sandbox); pass ui: false to disable. |
Type Aliases
AssetResult
type AssetResult =
| {
url: string;
}
| {
contentType: string;
data: Uint8Array;
};
AssetSource()
type AssetSource = (req: AssetRequest) =>
| AssetResult
| Promise<AssetResult>;
Parameters
| Parameter | Type |
|---|---|
req | AssetRequest |
Returns
| AssetResult
| Promise<AssetResult>
PyricAvatarsOptions
type PyricAvatarsOptions =
| false
| string
| {
source: AssetSource;
};
Profile photos for sandbox provider users. Default: deterministic
generated avatars. A string selects a pre-created avatar set (directory
path, resolved from the project root). false disables the avatar route
entirely. An object supplies a custom source that runs in the dev server,
never the browser.
PyricRuntimeChipOption
type PyricRuntimeChipOption =
| boolean
| {
initiallyOpen?: boolean;
};
Variables
NODE_BUILTIN_RE
const NODE_BUILTIN_RE: RegExp;
The node builtins pyric’s browser graph reaches for (via the rules module
resolver). Bare and node:-prefixed both match.
NODE_BUILTIN_SHIMS
const NODE_BUILTIN_SHIMS: Record<string, string>;
Benign browser shim SOURCE per builtin (see header — droppable only when
pyric breaks the firestore/index → rules/tools → modules/resolver static
chain, #553). Exported so the Vite plugin (./vite) reuses the SAME shims
through its own resolveId/load + optimizeDeps esbuild pass, instead of
re-deriving them.
Functions
pyric()
function pyric(options?: PyricOptions): Plugin<any> & EnvironmentHooks;
The dev-only Vite plugin. Add to vite.config:
import { pyric } from ‘@pyric/cli/vite’; export default defineConfig({ plugins: [pyric()] });
Parameters
| Parameter | Type |
|---|---|
options? | PyricOptions |
Returns
Plugin<any> & EnvironmentHooks