https://github.com/roerohan/flarbor
Cloudflare harbor
https://github.com/roerohan/flarbor
Last synced: about 1 month ago
JSON representation
Cloudflare harbor
- Host: GitHub
- URL: https://github.com/roerohan/flarbor
- Owner: roerohan
- Created: 2026-04-22T13:52:05.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-05-11T21:05:26.000Z (2 months ago)
- Last Synced: 2026-05-11T22:31:48.784Z (2 months ago)
- Language: TypeScript
- Size: 459 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Flarbor
Flarbor is a toolchain for building, running, and benchmarking RL environments for AI agents and model-driven workflows.
An RL environment is the loop around a model: it gives the model a task, exposes tools and state, records the model's actions, and scores the result with reward functions. For agentic software tasks, that environment often needs durable state, a filesystem, git, logs, evaluation code, and repeatable trials.
Flarbor is designed for input/output-heavy environments where most of the work is reading, writing, diffing, scoring, and coordinating state rather than running long-lived OS processes. It runs the core workflow on Cloudflare primitives: Durable Objects for state, Workspaces for filesystems, Dynamic Workers for sandboxed code execution, and the Cloudflare Agents SDK for the agent loop.
Flarbor is inspired by [Harbor](https://www.harborframework.com/docs), which showed how useful isolated RL environments can be. Harbor runs each environment in a Docker container, which can be slow to spin up and expensive to run in large parallel batches. Flarbor explores the same environment model on Cloudflare primitives, using containers only when an environment needs `npm build`, `npm test`, compilers, or other OS-level toolchains via the [Sandbox SDK](https://developers.cloudflare.com/sandbox/).
## Why
RL environments will soon be democratized. People will train and fine-tune models for their specific use cases by running task-specific RL loops with reward functions tailored to their domain.
The bottleneck is environment infrastructure. Harbor proved the concept with Docker containers, but containers are heavy, slow to cold-start, and expensive at scale. The core agentic workflow - clone a repo, read files, make changes, push - doesn't need an OS. It needs a filesystem, git, and an LLM.
Flarbor runs that workflow on Cloudflare's execution ladder: Durable Objects for state, Workspaces for filesystems, Dynamic Workers for sandboxed code execution, and isomorphic-git for version control. No containers, no VMs, no cold starts. A thousand idle environments cost nothing.
When you _do_ need a real OS — for `npm test`, compilers, build toolchains — Flarbor spins up a container on demand via the Sandbox SDK. Containers as a last resort, not the default.
## Quick start
```bash
pnpm install
# Verify the local workspace
pnpm typecheck
pnpm test
# Set secrets
wrangler secret put ANTHROPIC_API_KEY --name code-change-flarbor
wrangler secret put GITHUB_TOKEN --name code-change-flarbor
# Run locally
pnpm dev
# Or deploy
pnpm deploy
```
If your local npm config routes `@cloudflare/*` packages to a private registry, install with a command-local public registry override:
```bash
pnpm install --config.@cloudflare:registry=https://registry.npmjs.org/
```
Trigger a PR replay task:
```bash
curl http://localhost:8787/tasks
curl -X POST http://localhost:8787/run \
-H "Content-Type: application/json" \
-d '{
"taskId": "zod-5855",
"branch": "flarbor/zod-5855"
}'
```
You can also set defaults via wrangler env vars (`TASK_ID`, `MAX_STEPS`, etc.) and send a minimal or empty POST body. Request fields override env var defaults.
## Repository structure
```
flarbor/
├── packages/
│ ├── flarbor/ Core library: FlarborEnvironment, GitWorkspace, runTask
│ ├── flarbor-shared/ Shared types, glob matching, dispatch, test helpers
│ ├── flarbor-container/ Sandbox-backed container offload for build/test commands
│ ├── flarbor-job/ Batch job orchestration and optional JobObject helper
│ ├── flarbor-reward/ Reward/scoring kit for evaluating agent outputs
│ └── flarbor-verify/ Verifier orchestration and Harbor-compatible checks
└── environments/
├── code-change/
│ ├── flarbor/ PR-replay benchmark on Workers + Durable Objects
│ └── harbor/ Docker/Harbor comparison implementation
├── repo-audit/
│ ├── flarbor/ Read-only repository audit with batch jobs
│ └── harbor/ Docker/Harbor comparison implementation
└── support-simulation/
└── flarbor/ Customer-support simulation and scoring environment
```
### `packages/flarbor`
The core library. Exports `FlarborEnvironment`, an abstract base class extending `@cloudflare/think` that handles infrastructure: lifecycle hooks, token tracking, error capture, chat recovery, git workspace, and code execution wiring.
Environments subclass it and implement `getEnvironmentConfig()` with their domain-specific model, prompt, tools, and safety rules.
### `packages/flarbor-shared`
Zero-dependency shared package for common types and behavior used across packages: token usage, trial results, criterion context, glob matching, budget decay, dispatch helpers, runtime trial-result validation, and test helpers.
### `packages/flarbor-reward`
Composable reward/scoring kit. Define criteria (file checks, diff analysis, token budgets, LLM-as-judge), group them into rewards with aggregation strategies, and score trials.
```typescript
import { run, reward, fileExists, trialSuccess, tokenBudget } from "flarbor-reward";
const result = await run(
[
reward({ name: "correctness", criteria: [fileExists("output.txt"), trialSuccess(3.0)] }),
reward({ name: "efficiency", criteria: [tokenBudget(50_000)] }),
],
{ workspace, filesChanged, success: true, usage },
);
```
### `packages/flarbor-container`
Core library for offloading heavyweight build/test commands from a Durable Object agent loop to Cloudflare Sandbox/Containers. It exports a `ContainerRunner`, workspace sync helpers, command allowlist validation, and an AI SDK-compatible `createContainerCommandTool()`.
The package is intentionally not a deployable Worker. Environments provide the Sandbox binding, container image, command policy, and prompt wiring.
### `packages/flarbor-job`
Batch orchestration for running task sets across agent targets with bounded concurrency, retries, lifecycle hooks, and aggregate stats. The pure `runJob()` runner is in-request; the optional `JobObject` Durable Object helper adds RPC methods for persisted `start()`, `get()`, and `cancel()` state.
### `packages/flarbor-verify`
Verifier orchestration for turning executable checks into reward-shaped results. It supports deterministic criteria such as command success/output, file checks, JSON paths, HTTP checks, CSV/XLSX/SQLite checks, image checks, and dynamic verifier scripts. It can execute through Cloudflare Sandbox via `flarbor-container`.
### `environments/code-change/`
Side-by-side Flarbor and Harbor implementations for PR replay. The Flarbor environment exposes `GET /tasks` and `POST /run`, clones a repository at a captured base commit, gives the agent the original PR task, verifies the result with `flarbor-verify`, and returns a `TrialResult` with reward scores.
### `environments/repo-audit/`
Read-only repository audit environment. It exposes `POST /run`, in-request batch jobs at `POST /jobs/run`, and persisted Durable Object job state through `POST /jobs`, `GET /jobs/:id`, and `POST /jobs/:id/cancel`.
### `environments/support-simulation/`
Customer-support conversation simulation. It exposes `GET /scenarios`, `POST /run`, and the same batch/persisted job endpoints as repo audit. It scores outcomes, tool correctness, policy compliance, conversation quality, and efficiency.
## Concept mapping
| Harbor | Flarbor | Cloudflare primitive |
| ------------------------------------ | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `BaseEnvironment` (Docker container) | `FlarborEnvironment` (Durable Object) | [Durable Objects](https://developers.cloudflare.com/durable-objects/) + [`@cloudflare/shell`](https://www.npmjs.com/package/@cloudflare/shell) |
| `BaseAgent` | Think subclass | [`@cloudflare/think`](https://developers.cloudflare.com/agents/api-reference/think/) |
| Task (instruction + test) | `TaskConfig` via `POST /run` | Think chat turn |
| Trial (one attempt) | `runTask()` -> `TrialResult` | DO instance lifecycle |
| Container filesystem | `GitWorkspace` (Workspace + isomorphic-git) | [`Workspace`](https://www.npmjs.com/package/@cloudflare/shell) |
| `docker exec` | `@cloudflare/shell` state API | Dynamic Workers |
| `git` CLI | `@cloudflare/shell/git` | Pure-JS git |
| `npm test` / `npm build` | Sandbox SDK | [`@cloudflare/sandbox`](https://developers.cloudflare.com/sandbox/) |
## Execution ladder
| Tier | What | Container? |
| ----------------------- | ---------------------------------------- | ---------- |
| 0: Workspace | Durable virtual filesystem (SQLite + R2) | No |
| 1: Dynamic Worker | Sandboxed V8 isolate, no network | No |
| 2: Dynamic Worker + npm | Isolate with bundled packages | No |
| 3: Browser | Headless Chrome via Browser Run | No |
| 4: Sandbox | Full Linux container | Yes |
Tiers 0-2 handle the core workflow. Tier 4 is only for build/test.
## Comparing Flarbor vs Harbor
The code-change and repo-audit environments both include Flarbor and Harbor implementations, so you can benchmark Workers/Durable Objects against Docker/Harbor directly.
### Running both
```bash
# Flarbor
pnpm dev
curl http://localhost:8787/tasks
time curl -s -X POST http://localhost:8787/run \
-H "Content-Type: application/json" \
-d '{"taskId":"zod-5855"}' | jq .
# Harbor
cd environments/code-change/harbor
export TASK_ID="zod-5855"
export GITHUB_TOKEN="ghp_..."
export ANTHROPIC_API_KEY="sk-ant-..."
time ./run.sh
```
### Cost comparison
Both use the same model (`claude-opus-4-6` via Anthropic API directly), so LLM costs are identical.
**Flarbor (Cloudflare)**:
- DO compute: $12.50/M requests + $0.10/GB-s wall-clock
- DO storage: $0.20/M reads, $1.00/M writes, $0.75/GB stored
- Idle cost: **$0** (DOs hibernate)
**Harbor (Docker)**:
- Local Docker: free (your machine)
- Cloud sandboxes: per-second billing (Daytona, Modal, E2B)
- Idle cost: $0 locally, per-second on cloud
### What to measure
| Metric | How |
| ------------------ | ------------------------------------------------------------- |
| Wall-clock latency | `time curl` / `time ./run.sh` |
| Token usage | `usage` field in result JSON |
| Cold start | First request after deploy (Flarbor ~50-200ms; Harbor 10-60s) |
| Files changed | `filesChanged` in result |
| Success rate | Run N trials, compare `success` rate |
Run 3-5 trials per side with the same repo and instruction. LLM output is non-deterministic.
## Roadmap
- [x] Core library (`FlarborEnvironment`, `GitWorkspace`, task runner)
- [x] Shared package (`flarbor-shared`) for common types and utilities
- [x] Reward/scoring kit (`flarbor-reward`)
- [x] `flarbor-container` — Sandbox SDK integration for build/test offload
- [x] `flarbor-job` — batch runner plus optional persisted Job DO helper
- [x] `flarbor-verify` — verifier orchestration and Harbor-compatible checks
- [x] Code-change PR replay environment with Harbor comparison
- [x] Repo-audit environment with Harbor comparison
- [x] Support-simulation environment
- [x] Root `typecheck` and test verification scripts
- [ ] End-to-end validation on deployed Workers
- [ ] Eval runner environment (run task datasets, collect results)
- [ ] Queue-backed job orchestration for larger/background workloads
- [ ] Task/dataset registry
## License
Apache-2.0