Run on Fly.io without secrets
Deploy the onboarding starter agent or MCP server to Fly.io, where it authenticates to Keycard with Fly.io's OIDC token instead of a client secret.
Fly.io issues every Machine a short-lived OIDC token. Keycard trusts your Fly.io organization’s issuer and pins a Workload Identity credential on your Application, so the deployed code holds no client secret and nothing to rotate. Authenticate deployed workloads explains the model for any platform with an OIDC issuer; this page is the Fly.io walkthrough.
Which section you follow depends on what you’re deploying:
- For the background agent you enrolled in the Keycard Console onboarding guide, follow Deploy the onboarding starter agent, which runs it by hand as a scheduled Fly Machine.
- For the MCP server you enrolled in the onboarding guide, follow Deploy the onboarding MCP server, which runs it as a continuously serving Machine.
- For a server you built with Access APIs on Behalf of Users, follow Deploy your own MCP server with Claude, where Claude deploys it for you.
Deploy the onboarding starter agent
Section titled “Deploy the onboarding starter agent”This section covers the Deploy step of the Keycard Console onboarding guide’s agent path: running the starter agent you enrolled as a scheduled Fly Machine, then giving Keycard the three values it needs to trust it. It assumes you don’t use Fly.io every day and covers where that step goes wrong.
Before you start
Section titled “Before you start”- You finished the onboarding guide’s earlier steps: you cloned the starter (
git clone https://github.com/keycardai/getting-started-agent agent), rankeycard new agentin it, added PagerDuty as a dependency, andmake watchread PagerDuty successfully.keycard new agentwrote the.envfile this guide reads from, and you stored your Anthropic API key on thehttps://api.anthropic.comResource in Keycard. - A Fly.io account.
flyctl, Fly.io’s CLI. The first step installs it with Homebrew; on Linux or Windows, follow Install flyctl instead.
Run every command in this section from the starter’s folder (agent).
How the agent runs on Fly.io
Section titled “How the agent runs on Fly.io”The starter is a background agent, not a server: each run authenticates, reads PagerDuty, prints a summary, and exits. On Fly.io it runs as one Machine on a schedule, started once an hour, and serves no URL. The starter’s fly.toml and Dockerfile already describe this setup, so there’s no [http_service] and nothing to fly deploy.
Each run is two model calls on your Anthropic API key, the same as one make dev.
Deploy the agent
Section titled “Deploy the agent”-
Install
flyctland sign inTerminal window brew install flyctlfly auth loginSkip
brew install flyctlif you installedflyctlanother way.fly auth loginfinishes in your browser. -
Create the app without deploying it
Terminal window fly launch --no-deployAnswer Yes when Fly.io asks to use the starter’s
fly.toml, and No to tweaking the settings. Fly.io then creates the app in your personal organization (answer Yes to tweaking to pick a team organization instead), generates an app name, and writes it intofly.toml. It prints the app name and organization on one line, and the Deploy form asks for both:Created app '<app-name>' in organization '<org-slug>'fly apps listshows the app name later. -
Set the agent’s settings as app secrets
Terminal window fly secrets set --stage \KEYCARD_ZONE_URL="$(grep ^KEYCARD_ZONE_URL= .env | cut -d= -f2-)" \KEYCARD_RESOURCE_URL="$(grep ^KEYCARD_RESOURCE_URL= .env | cut -d= -f2-)"This copies two values from
.env:KEYCARD_ZONE_URL, the starter’s name for your Zone’s Issuer URL, andKEYCARD_RESOURCE_URL, the agent’s own Resource. The deployed agent refuses to start without them.KEYCARD_CLIENT_IDandKEYCARD_CLIENT_SECRETstay in your local.env, because the deployed agent authenticates with Fly.io’s workload identity. Your Anthropic API key stays in Keycard, where the deployed agent fetches it as itself.--stagesaves the secrets without restarting anything, since no Machine exists yet. -
Run it as one scheduled Machine
Terminal window fly machine run . --name agent --schedule hourly --restart noThis builds the image from the
Dockerfile, starts the Machine once, and starts it again every hour. Each flag matters:--name agentpins the Machine’s name. Fly.io puts it in the token’s subject, so the Deploy form needs it, and a Machine created without--namegets a random one.--schedule hourlyruns one cycle an hour, instead of the 15-second loop ofmake watch.--restart nostops Fly.io from restarting a failed run, since every retry that reaches the model costs another call on your Anthropic key.
The first run happens before Keycard trusts the Machine, so it fails to authenticate; runs succeed once you submit the form in the next section.
Tell Keycard where it deployed
Section titled “Tell Keycard where it deployed”Back in the onboarding guide, the Tell Keycard where it deployed form asks for three values:
| Field | What to enter | Where to find it |
|---|---|---|
| Fly organization | The organization slug | The organization '<org-slug>' that fly launch printed, or the slug in your Fly.io dashboard URL, fly.io/dashboard/<org-slug>. For a team organization, fly orgs list shows it too. For a personal organization, fly orgs list shows personal, which never appears in Fly.io’s tokens; use your account slug instead. |
| App name | The app name | The name fly launch chose, as in fly.toml, or fly apps list. |
| Machine name | The Machine name | The --name you gave fly machine run: agent unless you changed it. fly machine list shows it. |
From these, Keycard creates:
- A Provider for your organization’s issuer,
https://oidc.fly.io/<org-slug> - A Workload Identity credential on your agent’s Application, with the subject
<org-slug>:<app-name>:<machine-name>
There’s no Resource to register: the agent serves nothing, and its own Resource already exists from enrollment.
Fly.io builds the token’s subject from the organization, the app, and the Machine’s name, and offers no way to change it, so the form asks for all three and the credential trusts exactly one Machine. Authenticate deployed workloads registers <org-slug>:<app-name>:* instead, for apps that run many Machines; the starter runs one named Machine, so the Deploy step pins it.
Watch the first scheduled run
Section titled “Watch the first scheduled run”The Machine runs again on the hour. To run a cycle now instead of waiting, start it, then follow what it prints:
fly machine start $(fly machine list -q)fly logsA successful run prints the agent’s summary of open PagerDuty incidents. The run also appears on the Application’s Activity tab: a token issued to the agent with its Fly.io identity, then the exchange for PagerDuty, with no user and no secret involved.
Agent pitfalls
Section titled “Agent pitfalls”The organization is personal
Section titled “The organization is personal”fly orgs list shows a personal organization as personal, but Fly.io’s tokens carry your account slug (https://oidc.fly.io/<account-slug>), so a credential registered under personal never matches. The form refuses personal for that reason. Copy the slug from the Created app '<app-name>' in organization '<account-slug>' line fly launch printed, or from your dashboard URL.
The Machine name doesn’t match
Section titled “The Machine name doesn’t match”Keycard compares the token’s subject character for character, and the last segment is the Machine’s name. A Machine started without --name, or recreated under another name, carries a different subject and no longer authenticates. Keep the name agent, or submit the form again with the name fly machine list shows.
fly deploy instead of fly machine run
Section titled “fly deploy instead of fly machine run”fly deploy creates two Machines with generated names and no schedule. Their tokens match no credential, so they can’t authenticate, and one of them restarts in a loop because the agent exits with an error each time. Destroy both (fly machine list, then fly machine destroy <machine-id> --force) and use fly machine run from Deploy the agent.
The deployed agent says a setting is missing
Section titled “The deployed agent says a setting is missing”The deployed agent needs ... set means a secret from step 3 isn’t on the app. Stage it again, then update the Machine so it picks up the app’s current secrets. A plain fly secrets set doesn’t reach it: it starts a Fly Launch deploy, which skips Machines that fly machine run created.
fly secrets set --stage NAME=valuefly machine update $(fly machine list -q) --yesKeycard didn’t issue a token
Section titled “Keycard didn’t issue a token”Keycard didn't issue a token in fly logs means no Workload Identity credential matched the Machine’s token. Check that the form’s organization, app, and Machine name match what Fly.io shows now; one of the other pitfalls in this section is almost always the cause. Runs before you submitted the form fail this way too.
Fly didn’t issue an identity token
Section titled “Fly didn’t issue an identity token”Fly didn't issue this Machine an identity token means the agent couldn’t reach Fly.io’s Machines API at /.fly/api, which only exists inside a Fly Machine. The agent only uses it when FLY_APP_NAME is set, which Fly.io does for every Machine, so don’t set FLY_APP_NAME in your local .env.
The agent ran but PagerDuty was denied
Section titled “The agent ran but PagerDuty was denied”Authentication worked, but Keycard refused the exchange. The message names the cause: no PagerDuty dependency on the agent’s Application, or a policy that denies it. Fix it in Keycard Console; the next run picks it up.
Deploy the onboarding MCP server
Section titled “Deploy the onboarding MCP server”The onboarding guide’s MCP server path offers Vercel and Fly.io in the Deploy to picker. Choose Fly to deploy the MCP starter as one named Machine, then register its production identity and /mcp endpoint on the Application you enrolled locally.
Before you start
Section titled “Before you start”- Finish the guide’s earlier steps: clone the starter (
git clone https://github.com/keycardai/getting-started-mcp local-tools), enroll it withkeycard new mcp, and call a local tool. Enrollment writes the.envfile used below. - Create a Fly.io account and install
flyctl.
Run these commands from the starter’s folder. The repository includes fly.toml and a Dockerfile that serves HTTP on port 8181; unlike the background agent, this Machine stays running.
Deploy the server
Section titled “Deploy the server”-
Sign in and create the app
Terminal window fly auth loginfly launch --no-deployUse the starter’s
fly.toml. Whenfly launchasks whether to tweak the settings, answer No to keep the proposed organization and app name, or Yes to choose different ones. Use the name thatfly launchwrites intofly.toml;fly apps listshows it later. -
Stage the Zone URL
Terminal window fly secrets set --stage KEYCARD_ZONE_URL="$(grep ^KEYCARD_ZONE_URL= .env | cut -d= -f2-)"KEYCARD_ZONE_URLis the starter’s own variable for your Zone’s Issuer URL. TheKEYCARD_CLIENT_IDandKEYCARD_CLIENT_SECRETvalues stay in your local.env. On Fly.io, the starter uses the Python SDK’sFlyTokenSourceto obtain a fresh runtime identity token from/.fly/apifor each exchange. -
Allocate public addresses
Terminal window fly ips allocate-v4 --sharedfly ips allocate-v6Skip either allocation if
fly ips listalready shows that address type for the app. -
Run one named HTTP Machine
Terminal window fly machine run . --name local-tools --port 443:8181/tcp:tls:http --port 80:8181/tcp:http --restart always--name local-toolspins the name used in Fly.io’s identity. The ports route public HTTP and HTTPS traffic to the starter on port8181.--restart alwayskeeps the server running; do not use the agent’s--schedule hourlyor--restart no. Do not usefly deploy, which creates Machines with generated names rather than the name you register below.The public endpoint is
https://<app-name>.fly.dev/mcp. Locally, the starter checks its Application identity at startup. That check is disabled by default on Fly.io so the server can start before you register its production identity.
Register and verify the deployment
Section titled “Register and verify the deployment”In the onboarding guide, select Fly and fill in Tell Keycard where it deployed:
| Field | What to enter |
|---|---|
| Fly organization | The slug in fly.io/dashboard/<org-slug>. For a personal organization, use your account slug, not the personal alias printed by fly orgs list. |
| App name | The app name in fly.toml or fly apps list. |
| Machine name | local-tools, unless you changed --name; fly machine list shows it. |
| Deployed URL | https://<app-name>.fly.dev, or https://<your-domain> for a custom domain. |
For a custom domain, stage MCP_SERVER_URL on Fly.io and update the Machine to load it:
fly secrets set --stage MCP_SERVER_URL="https://<your-domain>/mcp"fly machine update $(fly machine list -q) --yesFor this starter, set MCP_SERVER_URL to the full endpoint shown above. The starter passes it to the Python FastMCP integration’s keycardai.fastmcp.AuthProvider. The SDK derives the origin from that value and adds /mcp when building protected-resource metadata, so either URL form produces the same metadata. In the Console form, enter https://<your-domain> with or without /mcp; Keycard normalizes the URL and registers the /mcp Resource.
Submitting the form creates the organization’s Fly.io OIDC Provider, gives the enrolled Application a Workload Identity credential with subject <org-slug>:<app-name>:<machine-name>, and registers the deployed /mcp Resource provided by that Application. Clients obtain tokens for this Resource from the Zone Provider, not from Fly.io.
Follow the guide’s instructions to add the deployed /mcp URL to your coding agent, then call a tool. In the Application’s Activity tab, the call shows the server’s Fly.io Workload Identity alongside your delegated User identity. That call completes the Deploy step; creating the credential alone does not.
If the URL changes, use Edit deployment. First use the commands above to stage the new full endpoint URL, including /mcp, and update the Machine. Then submit the new base URL in the Console form. Keycard registers the new endpoint and removes the old one, preserving the same Application and Machine identity.
Deploy your own MCP server with Claude
Section titled “Deploy your own MCP server with Claude”If you built your own MCP server by following Access APIs on Behalf of Users, Claude can deploy it to Fly.io for you. The deployed service identifies itself with a runtime OIDC token, so there are no API keys to store or rotate.
Prerequisites
Section titled “Prerequisites”- Your Application running locally, from Access APIs on Behalf of Users
- A Fly.io account with
flyctlinstalled; Claude can installflyctlfor you if you don’t have it - Your
keycard run claudesession, still running
Walkthrough
Section titled “Walkthrough”-
Ask Claude to deploy
Inside your Keycard session, send a prompt like:
Deploy my MCP server to Fly.io. Read `zone.id` and `org.id` from `keycard.toml` — stop and explain if either is missing. Check that `flyctl` is installed (`command -v flyctl`); if not, install it with `curl -L https://fly.io/install.sh | sh`. Probe `flyctl auth whoami` to check if a deploy credential is wired; if not, stop and tell me to follow https://docs.keycard.ai/concepts/resources/#vaulted-static-credentials to configure a Fly.io org token as a brokered credential, then restart the session. Run `flyctl orgs list` and ask me to confirm the org slug before proceeding; a personal org shows as `personal` there, but its slug is my account slug from the Fly.io dashboard URL.Generate or validate `fly.toml`. Determine the app's port from `.env` (`PORT`), `keycard.toml`, `package.json` scripts, or fall back to `8080`. Align `[http_service].internal_port` to that port. Write `KEYCARD_URL = '<keycard-issuer-url>'` (the Issuer URL from Settings → Connection) into the `[env]` section. Surface `fly.toml` (and `Dockerfile` if generated) before continuing.Provision Keycard primitives idempotently using list-then-create (reuse on 409): (1) Register OIDC provider with name `fly-<org-slug>` and issuer `https://oidc.fly.io/<org-slug>` — the slug must appear in the issuer URL. (2) Look up the Application with identifier `<project-name>` (create it if missing), so the Fly.io app joins the same Application as the local server. (3) Find the zone's `keycard-sts` provider and use its ID as `credential_provider_id` when creating the deployed Resource `https://<app-name>.fly.dev/mcp` with `scopes: ["mcp:tools"]` — omitting `credential_provider_id` causes credential requests to fail with "missing a credential provider". (4) Create Application Credential with `subject: "<org-slug>:<app-name>:*"` — the trailing `*` matches every machine of that app; `<org-slug>:*` would trust every app in the org.Run `flyctl deploy --remote-only` from the app directory. Verify with `flyctl status` and `curl -sf https://<app-name>.fly.dev/.well-known/oauth-protected-resource` — confirm the `resource` field equals `https://<app-name>.fly.dev/mcp`. Run `claude mcp add --transport http <app-name> https://<app-name>.fly.dev/mcp` to register the production server. Print a summary with the deployed URL, both Resource identifiers (local dev + production), and the registered Provider/Application/Credential IDs. -
Authenticate to Fly.io
The prompt probes for credentials. If
flyctl auth whoamishows no active credential, Claude stops and walks you through one of these options before it continues:Fly.io doesn’t support federated token exchange, so you store a Fly.io deploy token in Keycard as a vaulted static credential. Keycard brokers access without persisting credentials on your machine.
Create a deploy token at fly.io/tokens scoped to your Fly.io organization, then open the Keycard Console link Claude gives you and paste the token under Credentials. Restart your
keycard runsession afterward so it picks up the new credential; Claude tells you when and how to resume.Keycard encrypts the token at rest. Claude never sees the raw value; it only receives it through token exchange at deployment time. When Claude needs the token, Keycard shows a consent screen so you can approve before it proceeds:

Run
flyctl auth loginin your terminal to sign your local user in to Fly.io. Claude can then runflyctlcommands on your behalf within the Keycard session.Terminal window flyctl auth login -
Claude configures and deploys
Claude generates the Fly.io config, sets up Keycard trust for workload identity, registers the production Resource, and deploys the container.
Here’s how the scaffolded code handles credential discovery and workload identity:
// credentials.ts - auto-detects the runtime and picks the right credentialexport function discoverApplicationCredential(options: DiscoverOptions,): ApplicationCredential {const clientId = process.env.KEYCARD_CLIENT_ID;const clientSecret = process.env.KEYCARD_CLIENT_SECRET;if (clientId && clientSecret) {return new ClientSecret(clientId, clientSecret); // local dev via keycard run}if (process.env.FLY_APP_NAME) {return new FlyWorkloadIdentity({ audience: options.zoneUrl }); // production}// ... EKS, web identity, and other runtimes}// credentials.ts - Fly.io OIDC token fetch via the runtime metadata endpointclass FlyWorkloadIdentity implements ApplicationCredential {async prepareTokenExchangeRequest(subjectToken: string, resource: string) {const oidcToken = await this.#getToken(); // fetched from /.fly/apireturn {subjectToken,resource,clientAssertionType: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",clientAssertion: oidcToken,};}} -
Test the production deployment
Your MCP server is live at
https://<app-name>.fly.dev. Ask Claude to call one of your server’s tools. The same tools that worked locally now run through the deployed server, but the server authenticates with workload identity instead ofkeycard run. -
Verify in Keycard Console
Open Keycard Console > Audit Log. You should see entries for the tool call flowing through your production server:
users:authenticateYou signed in users:authorizeKeycard authorized access credentials:issueKeycard issued a token The event types match local development, because authorization and audit don’t depend on where the server runs.
What Claude set up
Section titled “What Claude set up”Each of these pieces carries over to other runtimes.
Workload Identity
Section titled “Workload Identity”Locally, keycard run injects credentials at startup. In production there’s no human present, so the deployed service needs its own identity to authenticate with Keycard and request Resources on behalf of callers.
Claude registered a Fly.io OIDC Provider in your Zone. When your server starts on Fly.io, it gets an OIDC token from the runtime, and Keycard verifies that token against the Provider before issuing credentials, so the server stores no secret. The Application credential Claude configured specifies which Fly.io workloads can act as your Application, scoped to your organization and app name. See Applications for the identity and credential model.
Vaulted static credentials
Section titled “Vaulted static credentials”Some upstream resources offer only static API keys or long-lived tokens, with no ephemeral token exchange. For those, Keycard stores the credential as a vaulted static credential and brokers access through token exchange.
Only use vaulted credentials when native token exchange isn’t available. They have two drawbacks:
- You need to manually rotate the credential in Keycard Console when it expires or gets compromised.
- Every Application that requests this Resource receives the same static credential, so you can’t scope access per-caller or per-request.
If a resource supports OIDC or OAuth token exchange, use that instead. Ephemeral tokens expire on their own and don’t need rotation.
A second Resource for the production URL
Section titled “A second Resource for the production URL”Locally, your MCP server’s Resource identifier points to localhost. In production, Keycard needs the server’s public URL so callers can find it.
Claude registered a second Resource (https://<app-name>.fly.dev/mcp) alongside the existing localhost Resource, and both belong to the same Application. MCP clients use this identifier to locate your server, and callers authenticate through Keycard, which sends them to the right endpoint. Keycard Console lists both under your Application’s Resources.
Troubleshooting
Section titled “Troubleshooting”Claude is still calling localhost instead of the deployed URL
After deployment, Claude’s MCP client config may still point to http://localhost:8000/mcp. Ask Claude to update the MCP config to use the new production address (https://<app-name>.fly.dev/mcp), then restart the MCP connection.
Token exchange fails with “provider not found”
Keycard doesn’t recognize the Fly.io OIDC issuer yet. Ask Claude to register the Fly.io OIDC Provider, or check Keycard Console > Providers to verify it’s listed.
Deployment succeeds but the server returns 401
The Application credential may not match the deployed workload. Verify in Keycard Console > Applications that the credential’s Fly.io app name and organization match your deployment. A mismatch means the runtime OIDC token won’t pass validation.
What’s next
Section titled “What’s next”- Authenticate deployed workloads: the same model on Render, Fly.io, and any platform with an OIDC issuer
- Run on Vercel without secrets: deploy the starter MCP server or agent to Vercel
- Providers: how Keycard trusts a platform’s tokens