🌉 Bifrost
The bridge between your portal and local CLI agents. Fire-and-forget autonomous execution with real-time streaming.
What is Bifrost?
Bifrost is a local Node.js Express server that bridges the portal UI with CLI agents (Claude and Gemini). It receives job instructions, spawns CLI processes, streams their output in real-time via SSE, and reports results back to the portal.
Think of it as your autonomous execution engine — you submit a job from the portal, and Bifrost runs it for you while you're away. No interactive prompts, no approvals needed.
Architecture
Bifrost uses an air-gapped pull model — no public tunnels or webhooks needed. The portal writes jobs to D1, and Bifrost polls for pending work.
Execution Flow
Components
| Component | File | Purpose |
|---|---|---|
| Server | apps/bifrost-api/server.js |
Express app with routes, auth, SSE streaming, heartbeat |
| Job Controller | apps/bifrost-api/controllers/jobs.js |
Job queue, CLI spawning, NDJSON parsing, error detection |
| Retry Queue | apps/bifrost-api/lib/retry-queue.js |
In-memory queue for rate-limited jobs awaiting auto-retry |
| Portal Client | apps/bifrost-api/lib/portal.js |
Helper to PATCH jobs and POST messages to portal D1 |
Key Concepts
| Concept | What |
|---|---|
| Stateless | Bifrost holds jobs in-memory while running. Durable state lives in D1. Restarting Bifrost loses active jobs but not history. |
| PM2-managed | Runs as a PM2 service for auto-restart and process management. Port 4003, accessible at bifrost.mipos.io. |
| Dual-backend | Supports both Claude CLI and Gemini CLI. Switch globally or per-job. See LLM Providers. |
| Auto-retry | Rate-limited jobs auto-queue for retry when quota resets. Countdown timer shown in portal UI. |
| SSE Streaming | Real-time output via Server-Sent Events. Portal connects to /jobs/:id/stream for live logs. |
| Channel Messages | Each job gets a #job-{id} channel with start, progress, and completion messages. |
Quick Links
▶️ Getting Started
Submit your first job from the portal — three entry points explained.
📦 Job Types
Session, research, workflow, clara, autopilot — when to use each.
🤖 LLM Providers
Claude vs Gemini — models, effort budgets, and switching backends.
🔄 Job Lifecycle
Status flow, timeouts, rate limits, auto-retry, and scheduled jobs.
🔧 Troubleshooting
Error states, common issues, and debugging tips.
🚀 Remote Job Entity
D1 schema, API endpoints, and data model reference.
Bifrost API Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /health | Service health + active job count + uptime |
POST | /jobs | Submit a new job (id, type, payload) |
GET | /jobs | List all active in-memory jobs |
GET | /jobs/:id | Single job status + metadata |
DELETE | /jobs/:id | Cancel a running job |
GET | /jobs/:id/stream | SSE stream — live output from CLI |
DELETE | /jobs/:id/retry | Cancel a queued auto-retry |
GET | /settings | Current config (backend, models, effort levels) |
POST | /settings | Update config (switch default backend) |
/health and /jobs/:id/stream require X-API-Key header.