firefly forge is the Firefly software factory. Describe a product's users, journeys and acceptance checks, connect its repositories, then choose a stack and coding provider. Review the implementation, actual checks and retained evidence before publishing a pull request.
The factory combines native pyfly services and controllers, a PostgreSQL execution ledger, Firefly Agentic, Studio and official local coding agents. Build new software, maintain an existing source or run model-free tests. Every run retains its source baseline, configuration, plan, command results and recovery history.
Documentation · Installation · Studio walkthrough · Architecture · Capabilities
The managed local stack includes forge, its PostgreSQL ledger, Flycanon, a separate pgvector database, durable knowledge objects and local embeddings. Fresh setup requires knowledge retrieval and enables verified project memory. Use Docker Compose and a dedicated macOS or Linux development environment. Source development also needs Python 3.13+, Git and Node.js 22.12+.
Complete the installation prerequisites, including the separately configured Keycloak client and private environment settings, before starting:
git clone https://github.com/fireflyframework/firefly-forge.git
cd firefly-forge
docker compose up --build -d
docker compose ps --allOpen http://127.0.0.1:8787, sign in and verify the included knowledge service. Connect a repository and an authorized coding provider before creating a run. Existing knowledge connections and queued configuration snapshots are preserved. Factory infrastructure covers server and cluster preparation, storage, backup and recovery.
Start with concepts and factory journeys to distinguish the product contract, repository, component, project, campaign and run. The guide follows monorepo and multiple-repository setup, source-control conversations, execution evidence and product support.
- Connect. Sign in to the factory, verify the selected coding provider, and grant repository access through a native SCM application or register a local Generic Git source. GitHub, GitLab, Bitbucket Cloud, Azure DevOps and Gitea have their own grants and callback settings. See SCM connections and provider configuration.
- Define. Map users and journeys to features, observable behavior and failure paths. Choose pyfly or larafly as the project's backend. Review architecture, brand and journey references before saving the product revision. An API-only product still needs a process and acceptance criteria. Start with your first product and product definition.
- Review and run. Inspect the brief, saved revision, foundation, executable checks and review policy. Follow the run's diff, command output, artifacts and journal. The guided Studio tour illustrates this path with labeled fixtures, including a failed check and an unresolved intent.
A passing run records its verified source and local checkpoint. Publication rechecks that retained source before creating a remote branch or pull request. Deployment and rollback have separate targets and receipts. An intent without an outcome requires reconciliation, even when its journal hash chain is valid. Keep failed checks and uncertain effects visible when deciding whether to continue.
The default combined service admits and executes work. A split installation separates API replicas from headless workers: one execution leader runs the jobs while other workers wait as standbys. Processes share the PostgreSQL ledger and retained private storage. Standbys provide takeover; they do not add a distributed pool of active workers. See runtime roles and factory infrastructure.
Choose and verify the execution environment before admitting a run. Git workspaces protect the consumer checkout; host commands still run with the worker's operating-system identity. Project users require isolated execution, while host coding and host verification require current administrator authority. Runner configuration and security describe the enforced boundaries.
In Studio, a run's Plan tab can review an original queued command for explicit continuation after one controller replacement. The original Factory worker must still be waiting. The browser retains the request before submission and reads its exact receipt after a lost response. Follow the continuation guide for the admission and recovery limits.
Open a paused run’s Agent questions tab to review the agent’s question and context. Choose a suggested answer or use the Markdown editor, review it, then send it under a retained response identity. Readback confirms the recorded answer after reload or a lost response; answering leaves the run paused until you resume it. Current project permissions and the authenticated replying user are checked separately from the recorded actor label. See operator decisions.
A factory administrator can review source-control delegation under Project access: choose an account asserted by a signed delivery, an existing Forge user, repository components and allowed requests. The wizard retains one request before saving and confirms its exact receipt. Agent questions display the historical delegation behind a mapped answer, while each new action still needs current permissions and application access. This grants no project membership or personal OAuth login. Follow the delegation walkthrough.
SDK, CLI and MCP clients can inspect those original-command candidates through the same authenticated read. Inspection never creates a continuation request or dispatches work. API-only installations report local admission and execution separately in health and metrics; accepting a request does not establish that a remote worker is ready.
For a local factory without an incoming webhook route, an administrator can enable GitHub App issue polling. Complete the baseline and separate account consent before posting a new status or answer comment. The mapped user's current permissions still apply, recorded answers retain their provenance, and answering leaves the existing run paused. Product edits and continuation use their separate signed-ingress grants; polling does not create projects or provide full GitFlow.
Use the run evidence reader to inspect or export a consistent cut of activity, tasks, WAL and tool results. A separately granted implementation agent can read bounded evidence from its own run. Reading evidence never replays a command or clears an unresolved outcome. Optional Bridge original-request recovery also retains the first submission and its pending or terminal observations; it keeps the graph-continuation hold until a supported checkpoint exists.
For a product spanning components, open Product projects > Campaign reports to read saved task, check and source evidence. Evidence state is separate from recorded workflow status; unresolved operations prevent verified delivery. The campaign guide explains unavailable counts, component references and the SDK, CLI and MCP entry points. Studio's report-and-review wizard can save the selected report under a retained request identity and read that same historical result later. Saved history retains its original evidence boundary; it does not refresh source control or approve delivery.
After admitting a campaign, use Studio’s waves, milestones and review wizard to save reporting criteria. Select an exact saved report to inspect component and task-receipt progress against that plan. The SDK, CLI and factory MCP expose the same contracts. These criteria support post-admission reporting; execution-wave orchestration remains separate work.
Administrators can explicitly configure a mutually authenticated local command controller with frozen execution profiles and project quotas. Its isolated containers receive sanitized component source and return bounded command receipts and artifacts. This adapter has local qualification on a trusted Factory host; browser pools, full coding-provider isolation, Kubernetes and multi-host placement remain separate work. Follow the local pool setup before selecting it.
flycanon supplies cited project and framework context. Fresh managed installations require retrieval and enable automatic memory after final verification. Knowledge and memory use a separate forge-<repository_id> workspace for each repository; a product spanning several components does not automatically create one combined memory scope. Read knowledge and memory before indexing source or changing scope grants.
Knowledge > Learning records shows saved outcomes, failed-check candidates and projection provenance for an authorized repository. The learning walkthrough explains record inspection, separate lookup eligibility checks, reviewed invalidation and verification of an existing indexed source, with exact-request recovery. Receipts retain the original actor, reason, request and journal event; Studio, SDK, CLI and MCP readback does not authorize replay when a write response is missing. A frozen same-run proposal cap can hold repeated coding repairs after actual QA; it preserves verification and the existing no-progress guard.
Select agent roles, project policies and the configured runner capabilities. Firefly Agentic and bridge execution use bounded native file, search, edit, diff, command and browser tools. Official Codex and Claude Code follow their own CLI permissions; a role tool list is advisory for those providers. Browser checks use a fresh restricted container context, and internet search requires explicit Brave or Tavily provider configuration and an authorized credential. The optional profile_python, trace_python and profile_php tools require their explicit diagnostic and command grants and an isolated Docker runner. They report bounded cProfile output, line-hit counts or PHP runtime observations with execution receipts. Diagnostic results do not approve the work or authorize replay. See native tools and browser journeys.
Project policies can use the public central policy catalog. Teams can connect a separately installed Firefly Agent Bridge. Studio, the CLI, SDK and the factory's own MCP tools operate the authenticated application contracts; agent integrations explains those entry points.
Repository-scoped learning binds exact questions to verified local outcomes and current applicability. Invalidated or expired evidence cannot supply a cached answer. Explicit flycanon projection retains one submission identity and preserves uncertain outcomes. Opt-in retrieval can read the verified projection of an exact eligible local record. Automatic discovery of other projected lessons, cross-run failure classification and sharing lessons between projects remain open.
Follow the source-development setup, then install Chromium with npx --prefix studio playwright install chromium before the first browser gate. Set FORGE_TEST_DATABASE_URL to an isolated PostgreSQL test database and prepare an existing PHP 8.3+ CLI for the recipe fixtures with make php-fixture-check. make check runs Python tests, lint and types, Studio checks/tests/browser journeys/build, and the strict documentation build. make docs-pages-check also checks every built local link and exercises navigation, search and screenshots under the published repository path.
Built-in model instructions and MCP descriptions live in versioned YAML resources and use Firefly Agentic's native template loader and registry. Follow maintain model instructions for variable contracts, source digests and golden tests.
make package creates installable distributions with Studio included. Agent bridge source is maintained separately and is never included in forge distributions. See the release notes for recorded validation and remaining live-acceptance boundaries. A fixture walkthrough demonstrates presentation; it does not establish provider authentication, generated-product correctness or a successful external deployment.
Apache 2.0 for code. Firefly names and generated brand assets retain their separate trademark and asset rights notices.