Handbook
Learn 101 — What is Fleet?
Outcome: explain Fleet to another engineer without opening fleet_server/main.py.
Updated
Audience: any engineer evaluating or onboarding to Fleet. Time: ~15 minutes. Prerequisites: none. Verify: you can restate what docker_argv, /v1/jobs, and /admin/ are for.
Plain-language definition
Forge Fleet is a small HTTP service (optional bearer authentication) that accepts JSON job specs, persists lifecycle + logs in SQLite, and runs docker_argv workloads on the same Linux/macOS host. Operators inspect recent jobs and host telemetry via /admin/.
When to use Fleet
| Scenario | Why Fleet fits |
|---|---|
| Forge Lenses Studio offload | Docs Health session_step runs containers via Fleet instead of in-process docker |
| Central job ledger + logs | SQLite-backed GET /v1/jobs/{id} + stdout/stderr tails |
| Operator dashboards | /admin/ surfaces CPU/RAM/service swimlanes plus optional git-self-update hooks |
When not to use Fleet (today)
| Scenario | Prefer instead |
|---|---|
| Remote Docker hosts / Kubernetes-only fleets | MVP binds mounts assume same host paths |
| Multi-tenant SaaS isolation | Fleet trusts operators—combine with hardened VMs/network segments (Security) |
| Deterministic governed LLM orchestration | forge-lcdl handles LLM tasks—Fleet runs containers (Forge LCDL ↔ Fleet) |
Mental model
Fleet HTTP job lifecycle
How clients submit docker_argv jobs, Fleet persists state, Docker runs workloads, and callers poll for completion.
- ClientSubmits a docker_argv job spec over HTTP to Fleet.
- Fleet APIValidates the request and opens a bounded execution path.
- SQLiteRecords job lifecycle, status, and operator-visible history.
- Docker runnerRuns the argv vector with docker run semantics on the host.
- logsCaptures stdout and stderr tails for reviewable audit.
- Poll GET jobCaller polls until the job reaches a terminal state.
Client -> Fleet API -> SQLite -> Docker runner -> logs -> Poll GET job| Concept | Meaning |
|---|---|
| Fleet server | fleet_server process exposing /v1/* & /admin/ |
| Job | POST /v1/jobs docker_argv request (argv, session_id, meta) |
docker_argv |
Literal argv vector handed to docker run semantics |
| Workspace upload | Optional PUT /v1/jobs/{id}/workspace gzip tarball (Build 201) |
| Template | GET /v1/templates catalog entries / requirement builds (Templates) |
| Container type | MECE system / job / service classification via etc/containers/types.json |
| Managed service | Long-lived compose stacks (forge_llm) registered under etc/services/ |
| Admin snapshot | GET /v1/admin/snapshot JSON bundle for dashboards |
| Telemetry | SQLite telemetry_samples + GET /v1/telemetry windows |
| Bearer token | Shared secret (Authorization header) whenever auth policy demands it |
Typical ports
| Context | Port | Notes |
|---|---|---|
| Dev / Compose “standard” | 18765 | python3 -m fleet_server --port 18765 |
User install (install-user.sh) |
18766 | systemd --user default |
| Playwright docs screenshots | 19876 | Disposable FLEET_DATA_DIR (e2e/) |
Always aim Studio + curl + /admin/ at the same Fleet instance—each process owns its fleet.sqlite.
Relationship map
| Thing | Relationship |
|---|---|
| Forge Lenses / Studio | Primary integration surface (Settings → Fleet) |
| Blueprints / ForgeSDLC | Methodology + handbook ecosystem—not runtime deps |
forge-lcdl |
Adjacent governed-LLM library—not embedded in Fleet |
Troubleshooting snapshot
| Symptom | First move |
|---|---|
Jobs empty in /admin/ but Studio “works” |
Confirm URLs map to same Fleet (Admin tour FAQ) |
401/403 everywhere |
Bearer vs bind-address mismatch (Security) |
Verify
Explain aloud:
- Where
fleet.sqlitelives (FLEET_DATA_DIR). - Difference between
docker_argvjobs vs managedforge_llmservices. - Why bind-mount paths care about same-host Studio.
Next steps
| Step | Doc |
|---|---|
| Install locally | Install & run locally |
| Fresh OS prep | Host bootstrap |
Guided curl proofs |
Quickstarts |
Deep protocol tables remain in HTTP API—finish Learn 101 before living there permanently.
Executive capsule
Outcome: explain Fleet to another engineer without opening fleet_server/main.py. Maturity: demonstrated.
Who this is for
Operators and delivery leads at the discover stage. Skim the executive capsule first; agents should respect the page frontmatter contract.
Evidence and maturity
Maturity: demonstrated. Statements here reflect the owning repo (forge-fleet) at last_reviewed; treat anything not explicitly marked as demonstrated as design direction rather than a shipped guarantee.
Trust boundary
Forge keeps humans in charge of promotion, approval, and release decisions; automation proposes and executes only within approved boundaries described here.