Bifrost — Remote Execution Service

Hub-native bridge between the Portal and local Claude CLI agents. Runs as a Node.js Express API managed by PM2.

Overview

	Detail
What	Node.js Express API that polls D1 for remote jobs and dispatches them to Claude CLI
Where	`e:\Agentic\services\bifrost-api/`
Domain	`bifrost.mipos.io` (port 4003)
Managed by	PM2 (`ecosystem.config.cjs`)
Skill	`/bifrost` skill (start, stop, status, restart, logs)
Legacy	`services/bifrost/bifrost.ps1` — PS polling fallback (Scheduled Task disabled)

Architecture

Portal Compose UI → POST /api/remote-jobs → D1 queue
                                                ↓
                                     Bifrost API (PM2)
                                     polls D1 every 30s
                                                ↓
                                     Picks up job → spawns Claude CLI
                                     CWD: e:\Agentic (hub-native)
                                     Flags: --dangerously-skip-permissions
                                                ↓
                              ┌─────────────┼─────────────┐
                              │             │             │
                         D1 job update  #dev channel  Log entry
                         (status/result) (progress)   (if applicable)

Key Components

File	Purpose
`server.js`	Express routes: health, jobs CRUD, SSE stream
`controllers/jobs.js`	Job spawn, cancel, EventEmitter streaming
`lib/portal.js`	HTTP client for D1 API calls
`lib/retry-queue.js`	Rate-limit auto-retry with cooldown
`ecosystem.config.cjs`	PM2 config

Job Types

Type	What	Duration
`research`	Agent researches a topic, produces a report	5-15 min
`clara`	Run a Clara mode (sweep, tidy, archive, focus, align)	2-8 min
`workflow`	Run any slash command	2-10 min
`session`	Execute a task from a task folder	5-30 min
`autopilot`	Multi-step autonomous execution	5-20 min

Job Lifecycle

pending → running → done/failed
           ↓
      rate_limited → retry_at → running (auto-resume)

Rate limiting: Bifrost captures Claude CLI's session_id and retry timestamp. Jobs queue for auto-retry via retry-queue.js.
Cancellation: DELETE /jobs/:id kills the child process.
Streaming: GET /jobs/:id/stream returns SSE with real-time stdout.

API Endpoints

Method	Path	Purpose
GET	`/health`	Health check
GET	`/jobs`	List recent jobs
GET	`/jobs/:id`	Get job details
GET	`/jobs/:id/stream`	SSE stream of job output
POST	`/jobs`	Create new job (portal does this via D1)
PATCH	`/jobs/:id`	Update job status/result
DELETE	`/jobs/:id`	Cancel running job
DELETE	`/jobs/:id/retry`	Cancel pending retry

PM2 Management

# Via skill (preferred)
# Use /bifrost skill: start, stop, status, restart, logs

# Direct PM2 commands (fallback)
pm2 start e:\Agentic\services\bifrost-api\ecosystem.config.cjs
pm2 logs bifrost-api
pm2 restart bifrost-api

Startup guard: PM2 sets PM2_HOME and pm_id env vars. The server uses these to detect PM2 context. If "online" but not responding, check for conditional startup guards in the code (see memory.md lesson).

Bifrost

On this page