fugaro

README

Fugaro

Fleeting cloud workers for coding agents: one task, one container, one PR, then gone.

Fugax is Latin for "fleeting." Fugaro runs long, self-contained coding-agent loops (implement → test → review → fix → compile → open a PR) in ephemeral, throwaway cloud containers instead of on your laptop. Google Cloud Run is the first supported backend; AWS and Azure are wanted next (see Other clouds). Each task gets its own container, runs to completion, pushes its work, and disappears.

Status: pre-1.0. Expect breaking changes. The first release is v0.1.0. It covers the runner, the git providers (GitHub and Bitbucket Cloud), the web-node base and derived images, the Cloud Run backend with its CLI, follow-up runs, the shared budget and the plugin skills. The design is docs/design/v1.md.

Quickstart

Install, stand up an installation in your own Google Cloud project, onboard a repository, run a task. Each step links to the deep doc.

1. Install

v0.1.0 is the first release; these channels are live from that tag.

brew install dimipaun/tap/fugaro
# or
go install github.com/dimipaun/fugaro/cmd/fugaro@latest

Or download an archive from GitHub Releases (darwin and linux, amd64 and arm64). Each release has a checksums.txt signed with cosign; docs/release.md shows how to verify it.

2. Prerequisites

• A Google Cloud project with billing enabled (see Requirements)
• gcloud authenticated, with Application Default Credentials (gcloud auth application-default login)
• Terraform 1.7 or newer on PATH
• Docker, only if you build images locally
• A GitHub or Bitbucket repository to run tasks against

3. Stand up the installation (once per project)

fugaro init --name <project> --gcp-project <gcp-project-id> --region <region>

init shows its Terraform plan and applies it after you confirm by typing the project's name. Details, what it creates and how to roll back: docs/gcp-setup.md.

4. Onboard a repository

In the repository's checkout, either use the plugin's fugaro:onboard skill from Claude Code (below) or write fugaro.yaml yourself, starting from fugaro config example, and check it with fugaro validate. Then, from the checkout:

fugaro init --repo                    # its secrets, registry, job and daily image check
fugaro secrets set anthropic-api-key  # value from stdin or a hidden prompt; also github-app-key, bitbucket-token, claude-oauth-token and the secrets your workflows declare

init --repo offers the first image build (billable, confirmed separately). For a GitHub repository, pass --github-app-id. See docs/gcp-setup.md and docs/git-providers.md.

5. Run, watch, diagnose

fugaro run "add a --verbose flag to the export command"
fugaro ls                      # runs, newest first; --watch redraws until they settle
fugaro logs -f <run>           # <repo-slug>/<run-id>, or a bare run ID
fugaro diagnose <run>          # status, failed tests, review findings, last message, cost, PR
fugaro cancel <run>            # the runner finalizes first; the draft PR stays

Every run that pushed ends in a pull request, a draft one if it failed. The draft appears at the first verified push and shows the run's progress, and the configured reviewers are requested only when it becomes ready (git.pr.early_draft, docs/git-providers.md); unlike earlier versions, a failed, halted or cancelled run no longer notifies reviewers at all, so watch fugaro ls for those. To act on review comments, continue it with fugaro run --pr N (optionally with extra instructions as TEXT); it reads the comments of the accounts fugaro.yaml's followup.trusted lists.

6. Optional: the shared budget

With a Firebase project linked to billing, runs share project-wide caps and kill switches (docs/gcp-setup.md):

fugaro init --firebase <firebase-project-id>
fugaro budget show             # caps, today's counters, kill switches
fugaro budget set ...          # after a while in observe mode; see --help
fugaro watch                   # live dashboard
fugaro report --by week        # spend history: by day, week, month, year, repo, model or person

fugaro report reads the spend history that a daily job copies into Firestore (created by init --firebase; its us-east5 location is permanent), with the last days computed live and marked (partial). Model dollars, notional (subscription list-price) and compute are always separate columns. It needs the Firebase project's roles/datastore.viewer and roles/serviceusage.serviceUsageConsumer; see docs/gcp-setup.md.

The Claude Code plugin

plugin/ holds six skills for your local coding agent: fugaro:onboard (set a repository up), fugaro:launch (start a run), fugaro:status, fugaro:logs, fugaro:diagnose and fugaro:followup (continue a Fugaro PR). Add the marketplace in Claude Code with /plugin marketplace add dimipaun/fugaro, then /plugin install fugaro@fugaro.

---

Why

Running several coding agents locally, each spawning sub-agents and each compiling and running test suites, saturates even a well-equipped machine: load averages over 100, thousands of threads, thermal throttling, and leaked build daemons piling up in the background. Everything gets slower the more you parallelize.

Fugaro moves that work to the cloud:

• Real parallelism. Launch as many tasks as you like; each runs in its own isolated job.
• Automatic teardown. Containers exit when the task ends. No stray daemons, no cleanup.
• Pay per second. Nothing runs, and nothing bills, between tasks.
• Never lose work. Every run ends in a pull request, even when it fails.

How it works

Each task is a single, ephemeral container job execution (a Cloud Run job on the GCP backend):

1. Start from a pre-baked image (toolchains, warm dependency cache, a recent repo checkout).
2. Authenticate as a dedicated, least-privilege service account.
3. Restore caches (Gradle build cache, node package store) from object storage.
4. Sync code with git fetch plus a hard reset to the exact target commit, so only the delta is downloaded.
5. Run the agent loop: implement, write tests, review, fix, recompile, repeating review rounds as configured.
6. Always push, always PR.
   • Success → a PR ready for review.
   • Failure → a draft PR with the failure explanation, logs, and the stage reached.
7. Write caches back, exit, and let the platform tear everything down.

A warm run should take minutes, not the half hour a cold environment would.

Design principles

• Open core. The engine in this repo is generic. Anything specific to a project lives in that project's own config file, never here.
• No secrets in the engine or the image. Credentials live in the cloud's secret store (Secret Manager on GCP) and are injected at runtime, scoped per job.
• The PR is the debugging surface. When the environment is gone, the PR still holds the diff, the reasoning, and the logs.
• Light and simple. Serverless container jobs, object storage, and a secret store (on GCP: Cloud Run jobs, Cloud Storage, Secret Manager). No cluster to operate and no standing infrastructure cost.
• Cloud-neutral engine. The runner, the agent loop, and the git providers don't know which cloud they run on; each cloud is a backend behind one interface (internal/backend).

Per-repo configuration

Each consuming repository carries a small config file describing how to build and test it. The schema is not final; this sketch shows the intent:

# fugaro.yaml (draft, subject to change; see docs/design/v1.md)
version: 1
project: aurora           # the Fugaro project this repository belongs to
git:
  provider: bitbucket       # or github
  base_branch: main
workflows:
  server:
    base: server-jvm
    commands:
      build: ./gradlew assemble
      test: ./gradlew test
    secrets:                # logical names; mapped to Secret Manager by the infra layer
      - { name: artifactory-token, env: ARTIFACTORY_TOKEN }

A repository can also commit cost and model policy: an optional budget: block (mode, per_run_usd, allowed_models) and agent.max_run_tokens. It can only tighten the ceiling the project owner sets in the project config (fugaro init --repo): the runner reads it from the default branch, a run's own branch can tighten it further but never loosen it, and the tightest value wins. Prices stay with the owner. allowed_models bounds the models fugaro.yaml may choose. It is enforced on every model call only while the gateway runs (api-key or vertex with the budget on); with oauth, or with the budget off, nothing stops the agent using another model through means a branch controls (a subagent's model: frontmatter, /model, .claude/settings.json), so there it is a configuration check only (accepted risk). See docs/design/v1.md §5.1 and docs/gcp-setup.md.

With a Firebase project behind the installation (fugaro init --firebase), runs also share a project-wide budget: daily caps per repository and for the project, kill switches (fugaro budget kill), a live list of the runs in flight, and the notional spend of oauth runs. It starts in observe (counts, refuses nothing), you set caps from what you saw with fugaro budget set, and only then switch to enforce. The caps live in the database and only budget admins change them; a committed budget.per_day_usd can only tighten the repository's own day cap. A run that cannot reach the backend for three minutes halts. fugaro watch is the live view of it: the project and each repository against their caps, the burn rate, one row per running agent, and keys to kill or resume a repository (k, r) or the whole project (K, R); --plain, --json and --once print instead of drawing a screen. fugaro ls --watch stays for "did my runs finish". See docs/gcp-setup.md.

Launching a task

A task is a small hand-off spec: what to do, which repo, which branch, and which workflow. It can be launched directly or by your local coding agent, which builds the spec and starts the job through the fugaro CLI. Many tasks can run at once, independently.

Local-agent skills (plugin/): fugaro:onboard sets a repository up, fugaro:launch starts a run, fugaro:status lists running and recent runs, fugaro:logs fetches a run's logs, fugaro:diagnose explains a failure (the draft PR and its logs), and fugaro:followup continues a Fugaro PR with a follow-up run.

Observability and guardrails

• Live logs in the cloud's logging service (Cloud Logging on GCP)
• A simple status view of running, passed, and failed tasks
• Per-job timeouts so runaway tasks can't burn hours
• A billing budget alert as a cost backstop (on GCP)

Requirements

For the GCP backend, the only one today:

• A Google Cloud project with billing enabled and serviceusage.googleapis.com on; fugaro init enables the other APIs it needs
• gcloud installed and authenticated locally, with Application Default Credentials
• Terraform 1.7 or newer on PATH, for fugaro init (docs/gcp-setup.md)
• A GitHub or Bitbucket repository to run tasks against

Other clouds: help wanted

Only GCP is implemented. We want to run Fugaro on AWS (for example ECS/Fargate tasks, S3, Secrets Manager, CloudWatch) and Azure (for example Container Apps jobs, Blob Storage, Key Vault, Azure Monitor), and we would love help: design feedback, a backend, test accounts, or just telling us what your setup looks like.

A new cloud is a backend behind the interface in internal/backend plus its provisioning (today a Terraform module set driven by fugaro init), and the base images already run anywhere a container runs. The GCP backend is the reference. If you want to take a cloud on, please open an issue first so we can agree the shape together, and say so in the issue even if you can only review or test.

Roadmap

• Base images for web (Node) workflows (web-node)
• Job entrypoint implementing the task lifecycle
• Cache restore and write-back
• Always-PR finish step (ready or draft)
• Per-repo config schema
• Launch CLI and the six local-agent skills
• Status view (fugaro ls, fugaro watch)
• Follow-up runs, the shared budget, GoReleaser releases and the Homebrew tap
• AWS and Azure help wanted (see Other clouds)
• Server (JVM/Gradle) base image
• M8: Docker backend, to run a task on your own machine or any Docker host
• M9d: run history
• M9e: an early draft PR
• M10: multi-model support
• Android workflow (deferred; heavy compiles stay local for now)

Open design questions are tracked in docs/SPEC.md.

Contributing

Ideas, issues, and PRs are welcome; see CONTRIBUTING.md. The project is young, so opening an issue to discuss a direction before a large change is appreciated. Please follow the Code of Conduct; report vulnerabilities as SECURITY.md describes.

License

MIT