Services & boxes

A service is a local HTTP app you expose through Finch. A box is a machine running the Finch agent. This page explains how the two fit together, what lives in finch.yml, and how to add more boxes.

The model

A service is any local HTTP app: an MCP server, a web app, any HTTP or WebSocket app. Finch publishes it at https://<slug>.finchmcp.com/<app_path>/. The service URL must be http(s).

A box is a machine running the Finch agent. It dials out to the hub, so nothing listens on the box and no ports open. One finch run process serves every rule in finch.yml.

Adding a service

Your service must already be running locally, then:

finch add printer --service http://127.0.0.1:8000
finch run
✓ https://your-slug.finchmcp.com/printer/

finch add writes or extends finch.yml. The file holds no secrets, so it is safe to commit. Credentials live on disk elsewhere, never in finch.yml.

finch.yml

hub: https://finchmcp.com
box: this-box
ingress:
  - app_path: printer                # becomes <slug>.finchmcp.com/printer/
    service: http://127.0.0.1:8000

hub is where the box connects. box names this machine. Each ingress entry maps a public path (app_path) to a local URL (service).

Multiple services

Run finch add once per service. Each call appends an ingress rule, and one finch run process fronts them all. It auto-approves new services while you are logged in.

finch add printer --service http://127.0.0.1:8000
finch add scraper --service http://127.0.0.1:8001
finch run

To remove a service:

finch rm printer

States

When a box goes offline

If a box loses its connection, its endpoint is marked offline. Nothing is deleted and nothing needs re-installing: the agent reconnects on its own, and the service goes back to online when it does.

Keeping boxes up to date

A box on an older agent shows an ⬆ badge next to its version. Two ways to update it:

From the dashboard — open the service and click update now on the box. The hub pushes an update command down the box's existing connection: the agent downloads the new binary from the hub, swaps it in place, and restarts itself — no SSH, no second process, about a second of downtime. The box comes back on the new version within a few seconds. (An offline box can't receive the push; the dashboard shows the command to run instead.)

On the box — run:

finch update

Same swap, run locally. If a systemd service manages the agent it restarts cleanly; otherwise the process replaces itself in place. Either way the update is atomic — a failed download never touches the running binary.

Enrolling another box

You do not need finch login on every machine. Mint a ticket in the dashboard (Add box), then on the new box:

finch enroll printer --ticket <ticket>   # writes the credential, one time
finch run                                # resumes ticketless thereafter

Tickets are one-shot credentials. They are saved to disk by enroll and never appear in finch.yml.

echo <ticket> | ssh newbox "finch enroll printer --ticket -"

Provisioning a box from a logged-in box

From a box that is already logged in, you can set up another one with no human step at all. finch token mints a fresh, revocable CLI token; the browser step is only ever needed for your first box.

finch token | ssh user@newbox "finch login --token -"
ssh user@newbox "finch add api --service http://127.0.0.1:9000 && finch run"

Inspecting state

finch status --json     # am I logged in? what does finch.yml serve?
finch fleet --json      # every service + its state (online/offline/pending)

Both print JSON you can parse in a script. See the CLI reference for every command.