Skip to main content
Version: 1.2

What is Fadebox?

Fadebox is a self-hosted orchestrator for ephemeral environments on Docker. You describe the services an application needs as reusable templates, compose them into environments, and spin up as many isolated, disposable copies of those environments as you need — one per feature branch, per developer, per demo — each reachable at its own predictable URL like https://shop-dev-pr42-web.envs.example.com, and gone again with one click.

It is built for teams that want preview/staging environments on their own infrastructure: a single app in front of one or more plain Docker daemons. No Kubernetes, no SaaS control plane, no phone-home — a fresh installation works fully offline.

How it fits together​

  • Service templates — reusable building blocks authored as Docker Compose YAML: one service plus its helpers (init containers, sidecars), with healthchecks, volumes, and files Fadebox injects at deploy time. Templates are global or scoped to one project.
  • Environments — an environment composes templates into an application stack (postgres + backend + frontend) inside a project. It is a pure definition; nothing runs yet.
  • Instances — running copies of an environment. Each is isolated by a namespace that prefixes containers, networks and volumes, so pr-42 and pr-43 of the same environment coexist on one host. Deploy, watch container status and logs live, stop, throw away.
  • Runtimes — the Docker daemons instances run on: the local socket out of the box, or remote daemons over tcp:// secured with mutual TLS.

Feature highlights​

  • One-click ephemeral environments — deploy an instance, watch per-container state, health and logs live, stop and redeploy at will. The daemon is the source of truth, so running instances survive Fadebox restarts.
  • Name-based ingress — mark a service's HTTP port and every instance gets a stable URL routed by Traefik. Fadebox installs and manages the ingress stack on each runtime host from the UI, including wildcard TLS via Let's Encrypt (DNS-01). Instance URLs can optionally require a Fadebox sign-in.
  • Template catalog — curated, ready-to-import templates ship inside the app (PostgreSQL, MariaDB, Redis, RabbitMQ, Keycloak — standalone or PostgreSQL-backed, pgAdmin, Mailpit and a whoami demo). Import copies an entry into an editable template, globally or into one project, under a name of your choosing (so the same entry can land twice in one scope), with version provenance.
  • Compose-native authoring — templates are the Compose subset teams already know, including depends_on conditions, healthchecks and resource limits. Ad-hoc test runs let authors verify a template before wiring it into an environment.
  • Multi-runtime, remote-capable — manage several Docker hosts; remote daemons are reached over mTLS with write-only credential handling, and a runtime can be restricted to named projects.
  • Private registries — a project holds the logins its own images pull with, so private images deploy onto a host nobody primed by hand. A runtime can also hold host-wide logins for a pull-through mirror; the project's win where both cover a registry.
  • Environments own their versions — per-service image tags are part of the environment definition, and an instance resolves that definition fresh on every deploy. A second version stream is a clone of the environment (dev, dev-v2) — named and visible in the list, not hidden in per-instance parameters.
  • Git value sources — environment variables and image tags can reference values inside files of a per-project git repository ({{git:app-repo:deploy/values.yaml#$.image.tag}}, JSONPath over YAML/JSON), resolved fresh on every deploy. The GitOps values file stays the single source of truth, and an ordinary release needs no write to Fadebox at all. A reference builder browses the repo and its parsed keys, so nobody writes placeholders from memory.
  • Single-origin apps — a service can claim a path instead of a hostname (fadebox.ingress.path: "/api", optionally stripped), so an SPA at / and its APIs under /api/* share one instance URL and relative links keep working. Values only the instance knows — {{instance.host}}, {{instance.name}}, {{ingress.scheme}} — interpolate into environment variables and injected files at deploy time, so a template with an absolute callback URL in it is deployable as-is instead of being regenerated per instance.
  • Drive it from your agent — Fadebox is an MCP server, so the coding agent you already use reads, composes and operates environments directly: find the broken container, tail its logs, pin a tag, redeploy, stand a stack up from the catalog. It hosts no model and calls none, and every tool is refused exactly where the agent's own account would be.
  • Redeploys restart only what changed — a deploy converges the running stack rather than rebuilding it, so bumping one service's tag leaves the database and everything else running, and a bad tag fails before anything is torn down.
  • Reclaim the host — orphaned containers, networks and volumes, and the image layers nothing wants any more, classified so that the cache a stopped instance redeploys from is never taken with them. By an admin host-wide, by a deployer for their own project, or on a retention timer.
  • See what it costs — CPU, memory and disk per runtime, per instance and per container, on the runtimes list and the dashboard, with a Prometheus exporter for the history a page cannot keep.
  • Command-line client — a single native binary for pipelines: fadebox instance up pr-123 --wait creates the instance, deploys it, polls until the containers are up and prints its URLs — exiting non-zero with the deploy's own error when it isn't.
  • Access control — global roles (admin / template admin / user) plus per-project roles (maintainer ⊃ editor ⊃ deployer ⊃ viewer — administer, compose, run, look), granted to a project's members directly or through groups an identity provider's group claim maps into.
  • Single sign-on, configured at runtime — any number of standards-compliant OIDC providers, added and edited in the UI with no restart and no rebuild. Form login stays enabled alongside as the break-glass path.
  • Self-hosted by design — no phone-home, no SaaS control plane, and an opt-in isolation label for the rare setup where several Fadebox installations share one Docker daemon.

Next steps​