Set app secrets for Fly machines: use flyctl and API, understand restart behavior and secret availability timing

Documented steps

1. Use flyctl command: fly secrets set DATABASE_URL=postgres://host/db API_KEY=mykey to set one or more secrets at once
2. Include flags: -a/--app <name> to target specific app, --detach to return immediately without monitoring, --stage to defer machine updates
3. Without --stage flag: flyctl immediately restarts each machine in the app, which resets ephemeral file system and picks up new secrets as environment variables
4. With --stage flag: secrets update the vault but machines are not restarted; new/updated machines launched after this command will receive staged secrets
5. Secrets become available as environment variables at machine boot time via Fly.io agent decryption (API servers can only encrypt, not decrypt)
6. No direct API endpoint for secrets is documented; flyctl internally sends secrets through Fly API which writes to vault for the app
7. Set secrets before creating machines, or update existing machines to pick them up (restart required without --stage)
8. Environment variable names are case-sensitive; avoid FLY_ prefix which is reserved for platform variables
9. Verify secrets are set: fly secrets list shows key names (not values); use fly secrets import to bulk-load from .env file
10. For machines not receiving secrets: check that machines exist, are associated with correct app, and were created/updated after secrets were set
11. Docs: https://fly.io/docs/apps/secrets/