Skip to main content

Fadebox 1.5

The 1.5 line: fadebox/fadebox:1.5 follows its newest release, and the 1.5 docs describe every release on it. Moving between releases is covered in Upgrading.

1.5.0 — 2026-10-14​

This release is about reaching an instance's services from your own machine. Until now, an instance's databases and brokers answered only to the other containers of the instance and to whatever its URLs exposed. Now psql, DBeaver or a Kafka client on your laptop can reach them on their native ports, two ways: through a small agent Fadebox runs in every instance, or over a tailnet. The command-line client is rebuilt for it, and now runs on Linux, macOS and Windows.

The instance agent and fadebox connect. Fadebox now runs a small agent in every instance. It publishes nothing and dials Fadebox back. fadebox connect pr-42 then opens a local port for each of the instance's services and tunnels every connection through Fadebox:

fadebox connect pr-42
psql "postgresql://app@localhost:5432/app"

A port that is taken on your machine gets another one, which connect remembers, so saved connections keep working. Fadebox checks every connection against the project role and the instance's gate, with viewer as the floor, and writes it to the audit log; removing someone from the project refuses their next connection. No tailnet is needed. The agent is on by default and comes with the Fadebox image, for amd64 and arm64: nothing is pulled from a registry, so an air-gapped installation runs agents too. It dials only its own instance's services. The System page's Instance agent card shows whether the agents run, and why not. See Without a tailnet: the instance agent.

Native access over a tailnet. An environment can give each instance a subnet of its own and a gateway on your Tailscale or Headscale tailnet. Every service then has a fixed address that does not change across redeploys, and any tool on a laptop running the stock Tailscale client reaches it. The instance drawer's Connect section and fadebox instance connect show where each service answers, and fadebox connect uses the tailnet when your machine is on it. Each installation keeps to the gateways it deployed, so two installations on one tailnet do not remove each other's nodes. See Native access.

The CLI for six platforms. fadebox is rewritten in Go and built for Linux, macOS and Windows on amd64 and arm64. Your installation serves every build at /cli/fadebox-<os>-<arch> (with .exe on Windows), and the sidebar footer links the one for your machine. It keeps the 1.4 CLI's commands, flags, tables, error messages, exit codes and context file, so a machine that is logged in stays logged in. A few things differ on purpose: -o json and -o yaml print the server's whole response, a malformed server URL is a usage error, the help text is laid out differently, proxy variables are honoured, and a redirect is never followed. See Coming from the 1.4 CLI.

Templates can expose a port without publishing it. A service's expose: lists ports that fadebox connect opens but no host port publishes. A second listener only developers need, such as a broker's external one, no longer needs a ports: entry, and no longer collides with a sign-in-gated instance on the same runtime. See the supported Compose subset.

Upgrade notes. Six migrations run on start, V026 to V031: an index on the audit log, and the tables for native access and the instance agent. Then:

  • Set FADEBOX_PUBLIC_URL, or switch the agent off. The agent dials FADEBOX_PUBLIC_URL, so set it to an address every runtime host reaches, an elastic runtime's machines included. While it is unset, no instance gets an agent and Fadebox warns once at startup; deploys go on as before. A value that is not an absolute http(s) URL with a host, or that carries user info, a query or a fragment, refuses every deploy with 409 agent_no_public_url, and a loopback host is warned of at startup. If you do not want the agent, set FADEBOX_INSTANCE_AGENT_ENABLED=false.
  • Your reverse proxy has to pass WebSocket upgrades to the agents and to fadebox connect, and keep an idle one open for at least a minute. Traefik and Caddy do so as they are; nginx needs the upgrade headers, and HAProxy a timeout tunnel above 30 seconds if you set one. See WebSocket upgrades.
  • An instance gets its agent at its next deploy. One deployed before the upgrade has none: fadebox connect says … runs no agent: it was deployed while instance agents were off; redeploy it to connect. Nothing is pulled for it; a Docker host that is neither amd64 nor arm64 fails the deploy with agent_architecture_unsupported until you switch the agent off or name an image of your own with FADEBOX_INSTANCE_AGENT_IMAGE.
  • Download the CLI again. /cli/fadebox-linux-amd64 keeps its URL and now hands out the new CLI, so a pipeline's curl line needs no change. The notices are now /cli/fadebox-THIRD-PARTY-NOTICES.txt; the old /cli/fadebox-cli-THIRD-PARTY-NOTICES.txt still answers with the same file. Check a script that parses -o json or -o yaml against the server's full response; jq paths keep working. A machine with proxy variables set for other tools that reaches Fadebox directly lists the server in NO_PROXY.
  • Templates that use expose: need 1.5. A 1.4 installation refuses to save or import one, so a catalog entry that adopts it updates only on installations that have upgraded.
  • Every managed ingress stack shows outdated once, since the check now covers each of its containers' whole configuration; press Update in each runtime's Ingress dialog. The pinned images are unchanged.
  • Native access is off until an admin saves the tailnet settings on the System page. A template or an environment service stored under a name that is now reserved (fadebox, or ending in fadebox-tailnet or fadebox-agent) is reported at startup; rename it before its next save or deploy, as Upgrading in the native access guide explains.

In the compose file, change the image line to fadebox/fadebox:1.5; the installation file is otherwise unchanged. The new settings are under Native access and Instance agent.

For API clients: an instance's status carries an access block (the gateway, the agent and the services they reach); environments gain nativeAccess; GET/PUT/DELETE /api/system/tailnet, GET /api/system/tailnet/status, POST /api/system/tailnet/verify, GET /api/tailnet-providers and GET /api/system/agent are new. GET /api/admin, GET /api/public and GET /api/users/me, left over from a quickstart, are gone; GET /api/me is the signed-in identity.