Run Firebase locally
Pyric adds a development-only resolution layer to a Firebase application. During Vite development, supported firebase/* imports resolve to a browser-local backend. A normal production build resolves those imports to Firebase again.
Start with a coding agent
Install the Pyric plugin:
npx plugins add davideast/pyric
Antigravity CLI and OpenCode use the standalone skill installer:
# Antigravity CLI
npx skills add https://github.com/davideast/pyric/tree/main/pyric-plugin/skills/pyric --agent antigravity-cli
# OpenCode
npx skills add https://github.com/davideast/pyric/tree/main/pyric-plugin/skills/pyric --agent opencode
Then invoke the skill:
| Agent | Enter |
|---|---|
| Codex | $pyric |
| Claude Code | /pyric:pyric |
| Antigravity CLI | /pyric |
| OpenCode | /pyric |
The leading $ or / is part of the command.
The skill selects the project launcher, starts one local sandbox bridge, opens the application, and confirms that the browser sandbox is connected.
Start from the terminal
Create a new Vite or Next.js application with canonical Firebase imports, Firestore rules, and Pyric already configured:
# Start a Vite application
npm create pyric@latest my-app
# Or start a Next.js application
npm create pyric@latest my-app -- --template nextjs
cd my-app
npm install
npm run dev
Open the local URL printed by the development server. The application and Pyric Studio use the exact same local backend. Studio is at /__pyric/ui/studio on that origin.
Pyric also adds a small, collapsed runtime chip in the bottom-right corner. It stays quiet while the sandbox is healthy and signals when there is an error to inspect or a newer worker to activate. Resolve runtime errors and stale workers covers both actions.
Add Pyric to an existing application
Install the CLI and development plugins as a development dependency:
npm install --save-dev @pyric/cli
Vite
Add it to the Vite configuration:
// vite.config.ts
import { defineConfig } from 'vite';
import { pyric } from '@pyric/cli/vite';
export default defineConfig({
plugins: [pyric()],
});
Next.js
Update the Next.js configuration in next.config.mjs:
import { withPyric } from '@pyric/cli/next';
/** @type {import('next').NextConfig} */
const nextConfig = {
// Existing config
};
export default withPyric(nextConfig);
Run next dev under pyric sandbox by changing the dev script in package.json:
{
"scripts": {
"dev": "pyric sandbox -- next dev"
}
}
pyric sandbox starts the local backend that withPyric forwards to. Next.js covers server code and Node host mode.
Start the development server:
npm run dev
No application imports change. Continue using firebase/app, firebase/auth, firebase/firestore, and the other supported Firebase entry points. Pyric uses an explicit rules configuration first, then discovers firestore.modules.rules, the path in firebase.json, or firestore.rules, in that order.
Use a static application or Node process
pyric sandbox provides the same development-only package swap outside the Vite plugin:
npm install --save-dev @pyric/cli
npx pyric sandbox
It can serve static files or start an existing development command. It serves the directory hosting.public names in firebase.json, and with no hosting block it serves no static files. Put Pyric flags before the child command and use -- to mark the boundary when needed:
npx pyric sandbox --bridge -- npm run dev
Server code that uses the client SDKs (firebase/firestore, firebase/auth, and the others) reaches only the Node host, so add --hosted. Without it, the first call fails with failed-precondition. Server code that uses firebase-admin works either way.
npx pyric sandbox --hosted -- node src/app.ts
See Node host mode.
You can also set command, port, project, and rules paths in pyric.json. See the CLI reference. Test in Node covers an in-process sandbox for tests and scripts.
What remains local
The mirrored services do not connect to a production Firebase project. Local data changes stay in the sandbox. Local Security Rules changes are enforced there and are not deployed. Firebase configuration passed to initializeApp(config) is accepted so the application code stays unchanged, but it does not select a cloud backend during development.
Before you ship, check your rules against your captured sessions: The same code goes live.
Continue with How the swap works, then develop with the Firebase APIs.