🚀 Remote Job
The execution layer. Portal dispatches work to Bifrost (local Node.js API) which spawns CLI agents.
Schema
D1 remote_jobs table
Job queue — portal writes, Bifrost reads and executes.
idTEXT PK — UUID
typeTEXT — session | research |
workflow | clara | autopilot
statusTEXT — pending | running |
done | failed | rate_limited
payloadTEXT — JSON with job
instructions
outputTEXT — Job output (truncated
for D1 limits)
task_idTEXT — Linked task
(optional, set when started from TaskModal)
session_idTEXT — Claude CLI
session ID (for resume)
retry_atTEXT — ISO timestamp for
auto-retry (rate_limited jobs)
started_atTEXT — When Bifrost
began execution
completed_atTEXT — When job
finished
created_atTEXT — ISO
timestamp
updated_atTEXT — ISO
timestamp
Lifecycle
Full status flow with timeouts, auto-retry, and recovery: Bifrost → Job Lifecycle
pending
→
running
→
done
running
→
failed
running
→
rate_limited
→ (auto-retry)
running
Job Types
Detailed prompt templates and payloads: Bifrost → Job Types
| Type | What it does | CLI Backend |
|---|---|---|
session |
General-purpose interactive session | Claude / Gemini CLI |
research |
Research a topic, produce a report | Claude / Gemini CLI |
workflow |
Run a specific slash command | Claude / Gemini CLI |
clara |
Clara inbox/sweep/focus operations | Claude / Gemini CLI |
autopilot |
Long-running autonomous programs | Claude / Gemini CLI |
Architecture
Air-gapped pull model: The portal writes jobs to D1. Bifrost (local Node.js Express API,
PM2-managed) polls for pending jobs. No webhooks, no public tunnel needed for job dispatch — Bifrost pulls
from D1 via Cloudflare API. See Troubleshooting for common issues.
Execution Flow
Portal UI
→ POST
D1 (pending)
← poll
Bifrost API
→ spawn
CLI Agent
Real-time Output
Bifrost streams CLI output via SSE (Server-Sent Events) at /jobs/:id/stream. The portal connects
to this endpoint for live output display.
Auto-Resume
When a job hits a rate limit, Bifrost captures the session_id from the CLI's NDJSON output,
parses the reset time, and queues an auto-retry via retry-queue.js. The portal shows a countdown
timer with Cancel Retry / Resume buttons. See Job Lifecycle → Rate Limit & Auto-Retry.
API
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/remote-jobs |
List jobs. Filter: ?status=pending, ?task_id=A82 |
POST |
/api/remote-jobs |
Create job. Body: { type, payload, task_id? } |
PATCH |
/api/remote-jobs?id=xxx |
Update status/output. { status: "done", output: "..." } |
POST |
/api/remote-jobs?heartbeat=1 |
Bifrost health heartbeat (every 30s) |