Skip to content
Application identity

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:

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.

  • You finished the onboarding guide’s earlier steps: you cloned the starter (git clone https://github.com/keycardai/getting-started-agent agent), ran keycard new agent in it, added PagerDuty as a dependency, and make watch read PagerDuty successfully. keycard new agent wrote the .env file this guide reads from, and you stored your Anthropic API key on the https://api.anthropic.com Resource 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).

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.

  1. Install flyctl and sign in

    Terminal window
    brew install flyctl
    fly auth login

    Skip brew install flyctl if you installed flyctl another way. fly auth login finishes in your browser.

  2. Create the app without deploying it

    Terminal window
    fly launch --no-deploy

    Answer 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 into fly.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 list shows the app name later.

  3. 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, and KEYCARD_RESOURCE_URL, the agent’s own Resource. The deployed agent refuses to start without them. KEYCARD_CLIENT_ID and KEYCARD_CLIENT_SECRET stay 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. --stage saves the secrets without restarting anything, since no Machine exists yet.

  4. Run it as one scheduled Machine

    Terminal window
    fly machine run . --name agent --schedule hourly --restart no

    This builds the image from the Dockerfile, starts the Machine once, and starts it again every hour. Each flag matters:

    • --name agent pins the Machine’s name. Fly.io puts it in the token’s subject, so the Deploy form needs it, and a Machine created without --name gets a random one.
    • --schedule hourly runs one cycle an hour, instead of the 15-second loop of make watch.
    • --restart no stops 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.

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.

The Machine runs again on the hour. To run a cycle now instead of waiting, start it, then follow what it prints:

Terminal window
fly machine start $(fly machine list -q)
fly logs

A 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.

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.

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 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.

Terminal window
fly secrets set --stage NAME=value
fly machine update $(fly machine list -q) --yes

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 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.

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.

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.

  • Finish the guide’s earlier steps: clone the starter (git clone https://github.com/keycardai/getting-started-mcp local-tools), enroll it with keycard new mcp, and call a local tool. Enrollment writes the .env file 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.

  1. Sign in and create the app

    Terminal window
    fly auth login
    fly launch --no-deploy

    Use the starter’s fly.toml. When fly launch asks whether to tweak the settings, answer No to keep the proposed organization and app name, or Yes to choose different ones. Use the name that fly launch writes into fly.toml; fly apps list shows it later.

  2. Stage the Zone URL

    Terminal window
    fly secrets set --stage KEYCARD_ZONE_URL="$(grep ^KEYCARD_ZONE_URL= .env | cut -d= -f2-)"

    KEYCARD_ZONE_URL is the starter’s own variable for your Zone’s Issuer URL. The KEYCARD_CLIENT_ID and KEYCARD_CLIENT_SECRET values stay in your local .env. On Fly.io, the starter uses the Python SDK’s FlyTokenSource to obtain a fresh runtime identity token from /.fly/api for each exchange.

  3. Allocate public addresses

    Terminal window
    fly ips allocate-v4 --shared
    fly ips allocate-v6

    Skip either allocation if fly ips list already shows that address type for the app.

  4. 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-tools pins the name used in Fly.io’s identity. The ports route public HTTP and HTTPS traffic to the starter on port 8181. --restart always keeps the server running; do not use the agent’s --schedule hourly or --restart no. Do not use fly 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.

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:

Terminal window
fly secrets set --stage MCP_SERVER_URL="https://<your-domain>/mcp"
fly machine update $(fly machine list -q) --yes

For 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.

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.

  • Your Application running locally, from Access APIs on Behalf of Users
  • A Fly.io account with flyctl installed; Claude can install flyctl for you if you don’t have it
  • Your keycard run claude session, still running
  1. 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.
  2. Authenticate to Fly.io

    The prompt probes for credentials. If flyctl auth whoami shows 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 run session 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:

    Keycard consent screen for Fly.io

  3. 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 credential
    export 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
    }
  4. 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 of keycard run.

  5. Verify in Keycard Console

    Open Keycard Console > Audit Log. You should see entries for the tool call flowing through your production server:

    users:authenticate You signed in
    users:authorize Keycard authorized access
    credentials:issue Keycard issued a token

    The event types match local development, because authorization and audit don’t depend on where the server runs.

Each of these pieces carries over to other runtimes.

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.

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.

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.

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.