Bifrost is a local workstation bridge: you run the backend + frontend on your laptop, expose them over Tailscale, and then a mobile client (or any other Tailnet device) connects through the private mesh. The backend hosts command execution/agent sessions, WebSockets, and local session discovery; the frontend is a Vite-powered React UI that authenticates via Firebase (optional dev bypass) and speaks to /ws.
- Node 18+ (uses
npmworkspaces forpackages/backendandpackages/frontend) - PostgreSQL available locally (you are responsible for creating the
bifrostandbifrost_testdatabases that the backend expects) - A Firebase project if you want real authentication
node-ptynative build tools on macOS/Linux/Windows (on mac installxcode-select --install; on Linux installbuild-essential, Python, etc.)- Tailscale installed and logged in on the devices you plan to use
Populate each package’s .env from its .env.example.
| Variable | Purpose |
|---|---|
FIREBASE_PROJECT_ID |
Firebase project ID for token verification |
FIREBASE_SERVICE_ACCOUNT_KEY |
Optional raw JSON service account |
GOOGLE_APPLICATION_CREDENTIALS |
Optional path to the service-account JSON file |
ALLOWED_EMAILS |
Comma-separated list of allowed Firebase emails |
AUTH_DISABLED |
Set true for dev-only bypass mode; false for real auth |
DATABASE_URL / TEST_DATABASE_URL |
Connection strings for your bifrost and bifrost_test databases |
WORKSPACE_BASE |
Directory under which per-session folders live |
WORKSPACE_MODE |
isolated for per-session dirs, host to reuse the base path |
COMMAND_TIMEOUT_S, OUTPUT_MAX_BYTES, TERMINAL_MODE |
Execution guardrails (keep TERMINAL_MODE=headless on mac) |
AGENT_PROVIDER, SECURITY_PROFILE, CLAUDE_CODE_PATH, CODEX_PATH |
Default agent runtime & CLI paths |
PORT |
Backend HTTP/WebSocket port |
| Variable | Purpose |
|---|---|
VITE_AUTH_DISABLED |
true to skip Firebase sign-in (matches backend AUTH_DISABLED=true) |
VITE_SHOW_EXECUTION_LOG |
Toggle visibility of the execution log panel |
VITE_FIREBASE_* |
The usual Firebase Web config values (apiKey, authDomain, etc.) used when auth is enabled |
Create the PostgreSQL databases manually or via createdb bifrost bifrost_test. Point DATABASE_URL/TEST_DATABASE_URL at those names. Then run:
npm install npm run build --workspace=packages/frontend npm run dev:backend
This installs dependencies, builds the frontend so packages/frontend/dist exists, and starts the backend (which runs migrations on boot).
npm run dev:backend(from repo root) starts the Fastify server on the port configured inpackages/backend/.env.- If you make frontend changes, run
npm run build --workspace=packages/frontendbefore running the backend sopackages/frontend/distexists for static hosting.
- Install Tailscale on every device that needs access (laptop + mobile).
- Log in with the same account so they share a Tailnet. The backend listens on
0.0.0.0, which means it accepts connections from any interface; Tailscale provides the private IP you share with the mobile client. - On the mobile device, open the browser/app and point it to
http://<your-laptop-tailnet-ip>:<backend-port>/ui(use the backend port from.envand thetailscale statusaddress). The WebSocket connection is made from the frontend to the same origin, so both backend and frontend must be reachable through Tailscale. - If you expose the backend port over the public internet, Tailscale is no longer the gatekeeper—keep that port private to avoid unwanted access.
- If you enable
AUTH_DISABLED=true, the backend and frontend both bypass Firebase entirely. In that mode, any Tailnet device that can reach the backend can send/wscommands unrestricted. - Document the FIRBASE credential paths and
CLAUDE_CODE_PATH/CODEX_PATHto match whatever binaries live on your machine.