Forge is a from-scratch execution engine for running shell commands on remote workers. It combines a Spring Boot control plane, a multithreaded C++ worker, a bidirectional gRPC command stream, PostgreSQL-backed state, DAG workflows, and failure-aware recovery.
Quick start · Architecture · API · Development · Operations
Important
The Forge engine executes arbitrary processes and its internal REST/gRPC APIs are trusted-network interfaces. The public demo configuration exposes only the dashboard and ten fixed, bounded workflow templates behind HTTPS. See Security.
Forge focuses on the parts of distributed execution that become difficult after the happy path:
- Durable worker events: task-start and task-result messages are persisted to a filesystem outbox before transmission, replayed after reconnects, and removed only after controller acknowledgement.
- Worker session fencing: a stable worker ID is paired with a per-process session ID so stale incarnations cannot report results or reclaim authority.
- Atomic takeover: PostgreSQL stores the authoritative worker session, retired sessions, and recovery grace periods so controller restarts do not erase ownership decisions.
- DAG workflows: dependency validation rejects missing nodes, self-dependencies, and cycles; downstream tasks are released or skipped as prerequisites resolve.
- Failure-aware execution: bounded exponential retry, worker-loss recovery, cancellation, timeouts, ordered attempts, and persisted execution timelines are built into the model.
- Capacity-aware scheduling: the controller reserves worker capacity atomically and selects by effective load, CPU usage, and a deterministic worker-ID tie-breaker.
The REST API is the user-facing control surface. The controller persists logical tasks and physical attempts, schedules work onto connected workers, and reconciles failure. Workers execute commands in dedicated process groups and use the outbox to bridge network or controller outages. The shared Protocol Buffers contract keeps both runtimes aligned.
Docker with Compose is enough to run the complete demo:
docker compose up -d --buildOpen Workflow Templates to launch any of ten workflows. Start with parallel processing, retry recovery, or distributed video processing. Click DAG nodes to inspect attempts and worker assignments. Templates that intentionally fail explain their expected results before launch.
The images include the Java/C++ build tools, verification source, and a compact 30-second Tears of Steel footage excerpt. No full film download, host compiler, or source bind mount is required. PostgreSQL, worker outboxes, and video artifacts use persistent Docker volumes.
For an interactive recruiter-facing deployment, follow the public deployment guide, which adds HTTPS, private backend ports, launch budgets, and resource limits. For native development, see Development.
| Concept | Role |
|---|---|
| Workflow | A validated DAG of named tasks. Successful nodes are preserved when failed workflows are manually retried. |
| Task | The logical unit requested by a client, including command, arguments, timeout, dependencies, and retry policy. |
| Attempt | One physical execution of a task, bound to a worker ID and worker session. |
| Worker | A C++ process that registers capabilities, receives commands, reports load, and runs up to four executor threads. |
| Session | A unique identity for one worker process incarnation, used to reject stale heartbeats, streams, and results. |
| Execution event | An append-only timeline record associated with a workflow, task, attempt, or worker. |
forge_app/
├── controller/ Spring Boot REST and gRPC control plane
│ └── src/main/
│ ├── java/dev/forge/ API, scheduling, recovery, and persistence
│ └── resources/db/ Versioned Flyway migrations
├── worker/ C++20 worker and POSIX process executor
├── proto/forge.proto Shared wire contract
├── scripts/ End-to-end and failure-injection smoke tests
├── docs/ Architecture, API, development, and operations
└── docker-compose.yml Complete local Docker stack
- Public demo deployment — Docker setup, HTTPS, template outcomes, and operating limits
- Architecture — components, execution flow, state machine, recovery design, and data model
- API reference — REST resources, payloads, lifecycle values, and gRPC contract
- Development guide — prerequisites, builds, tests, migrations, protocol changes, and repository conventions
- Operations guide — configuration, persistence, failure behavior, observability, and troubleshooting
- Contributing — a focused change workflow and review checklist
- Security — trust assumptions and production-hardening gaps
Forge deliberately demonstrates orchestration and recovery mechanics rather than presenting itself as a finished hosted platform. The current controller is a single instance, worker transport uses insecure gRPC, the REST API is unauthenticated, and worker capacity is local to controller memory. These boundaries are documented so future work can be evaluated against a clear baseline.