Workbooks + Fly.io

Connecting Fly.io lets you stand the Workbooks engine (or an app forged from a workbook) on a Fly machine on your own Fly account — headless, agent-loop and all — with nothing more than a flyctl login. It is the cloud arm of the Deploy Kit: the same OCI image you run locally, placed on Fly.

Field	Value
Toolkit id	`fly`
#+EXEC shape	`task` (a deploy recipe)
Backing CLI	`flyctl`
Status	`partial` (deploy recipe, not a registry toolkit)
Manifest	`toolkits/fly/deploy/` (recipe + templates)

What it does

Deploy the Workbooks engine to a dedicated Fly machine, headless — the engine runs the agent loop as a local subprocess on its own machine (WB_VMM_BACKEND=process, bootstrap.sh:2-4).
Provision the agent + engine app definitions from templates (fly/deploy/agent.toml.template, engine.toml.template).
Re-run as an update against an existing app (UPDATE path, bootstrap.sh:18).

Capabilities it grants

This is a deploy recipe that shells flyctl, so it runs at the posix tier (a native binary the host brokers) rather than as a pure WASM command.

Capability	Why it needs it
`posix`	Run the `flyctl` binary (`bootstrap.sh:8` guards its presence)
`secrets`	Fly auth + the engine's `WB_SIGNING_KEY` seed (a Fly secret)
`net`	flyctl reaches the Fly API

See Dock capabilities.

How to add it

Install flyctl (bootstrap.sh:8 bails with the install URL if it's missing) and run flyctl auth login.
Configure the deploy target:
```
   wb deploy init --place fly
```
Apply it:
```
   wb deploy apply
```

account — it is not how the platform publishes the compilers package or the runtime image (those are a separate, manual/CI path). The Fly token is flyctl's own; Workbooks never reads or proxies it.

Worked example

Deploy a fresh engine to Fly in the iad region, then update it after a change:

flyctl auth login
wb deploy init --place fly --region iad
wb deploy apply          # provisions the machine, boots the headless engine
# ... change config ...
UPDATE=1 wb deploy apply  # re-applies against the existing app
wb deploy status         # confirm the machine is live

The engine comes up on its own Fly machine running the agent loop as a local subprocess; you get a runtime endpoint your workbooks can connect to over RCP.

Related toolkits

Workbooks + Cloudflare — single-account D1 + Pages, no second provider (toolkits/cloudflare/)
Workbooks + Railway — Postgres + container hosting, the BYOD path (toolkits/railway/)
Deploy how-to: Deploy to the cloud · The three release layers
All integrations: Toolkits & integrations

Maturity

partial. The Fly deploy recipe ships and works (toolkits/fly/deploy/), but it is a Deploy-Kit recipe invoked through wb deploy, not a registry toolkit and not a general Fly API surface. It deploys the engine headless to a single Fly machine; broader Fly operations are not in scope. Keep it distinct from the three platform-release layers.

Capability Matrix row: /maturity
Source of truth: toolkits/fly/deploy/bootstrap.sh