@akeyless-community/fly-runtime

Fetch Akeyless secrets at runtime on Fly.io Machines (Node.js). Application secrets stay in Akeyless — only bootstrap auth variables are stored on Fly.

Repository: github.com/akeyless-community/fly-runtime

Install

npm install @akeyless-community/fly-runtime

Requires Node.js 18+.

Quick start

1. Set bootstrap secrets on Fly.io

Store read-only Akeyless credentials as Fly secrets (or in [env] in fly.toml for non-sensitive bootstrap values):

fly secrets set \
  AKEYLESS_ACCESS_ID=p-xxxxx \
  AKEYLESS_ACCESS_KEY=your-access-key \
  AKEYLESS_SECRET_PREFIX=/fly/my-app/production

| Variable | Required | Example | |----------|----------|---------| | AKEYLESS_ACCESS_ID | Yes* | p-xxxxx | | AKEYLESS_ACCESS_KEY | Yes* | access key secret | | AKEYLESS_SECRET_PREFIX | Recommended | /fly/my-app/production | | AKEYLESS_GATEWAY_URL | No | https://api.akeyless.io | | FLY_ENV or AKEYLESS_ENV | No | staging (used when prefix is derived) |

* Or use another auth method below.

If AKEYLESS_SECRET_PREFIX is omitted, the library derives it from Fly metadata:

/fly/{FLY_APP_NAME}/{FLY_ENV or AKEYLESS_ENV or production}

Fly sets FLY_APP_NAME, FLY_REGION, and FLY_PROCESS_GROUP automatically on every Machine. See the Fly runtime environment.

2. Store application secrets in Akeyless

/fly/my-app/production/DATABASE_URL
/fly/my-app/production/STRIPE_SECRET_KEY

For multi-process apps, either use a shared app/env prefix or opt into per-process-group prefixes:

fly secrets set AKEYLESS_INCLUDE_PROCESS_GROUP_IN_PREFIX=true
# → /fly/my-app/production/worker/DATABASE_URL

3. Fetch secrets in your app

const express = require('express');
const { getSecret } = require('@akeyless-community/fly-runtime');

const app = express();

app.get('/health', async (_req, res) => {
  const dbUrl = await getSecret('DATABASE_URL');
  res.json({ ok: true, hasDb: Boolean(dbUrl) });
});

app.listen(process.env.PORT || 3000);

Use getSecret only in server code. Never expose fetched secrets to the browser.

Per-environment prefixes

| Fly environment | Typical prefix | |-----------------|----------------| | production | /fly/my-app/production | | staging | /fly/my-app/staging | | development | /fly/my-app/development |

Set FLY_ENV or AKEYLESS_ENV on each Fly app, or set AKEYLESS_SECRET_PREFIX explicitly when you need a custom layout.

Many teams use separate Fly apps per environment (my-app-staging, my-app-prod) with the default production segment — both patterns work.

API

Convenience (singleton, replica-friendly)

const { getSecret, getDefaultClient } = require('@akeyless-community/fly-runtime');

const dbUrl = await getSecret('DATABASE_URL');

Explicit client

const { createClient } = require('@akeyless-community/fly-runtime');

const client = createClient({
  gatewayUrl: 'https://api.akeyless.io',
  secretPrefix: '/fly/my-app/production',
  accessId: process.env.AKEYLESS_ACCESS_ID,
  accessKey: process.env.AKEYLESS_ACCESS_KEY,
});

await client.getSecret('DATABASE_URL');
await client.getSecretAtPath('/custom/full/path');
await client.getDynamicSecret('db-creds');
await client.getRotatedSecret('rotated-api-key');

Authentication

Configure via Fly secrets / [env] or createClient({ ... }).

| Method | AKEYLESS_ACCESS_TYPE | Additional variables | |--------|------------------------|----------------------| | Access key (default) | access_key | AKEYLESS_ACCESS_ID, AKEYLESS_ACCESS_KEY | | API key | api_key | AKEYLESS_ACCESS_ID, AKEYLESS_ACCESS_KEY | | Universal Identity | universal_identity | AKEYLESS_UID_TOKEN | | JWT | jwt | AKEYLESS_ACCESS_ID, AKEYLESS_JWT | | AWS IAM | aws_iam | AKEYLESS_ACCESS_ID, optional AKEYLESS_CLOUD_ID | | Pre-authenticated | — | AKEYLESS_TOKEN |

Use a dedicated Akeyless auth method with read-only access to your /fly/... path.

Local development with Fly CLI

Run your app locally with the same secrets as your Fly app:

fly secrets list
fly secrets import < .env.local   # optional: sync local env file
fly proxy 3000:3000               # if your app needs Fly-internal services

Or export variables manually:

export AKEYLESS_ACCESS_ID=p-xxxxx
export AKEYLESS_ACCESS_KEY=your-key
export AKEYLESS_SECRET_PREFIX=/fly/my-app/development
export FLY_APP_NAME=my-app
export FLY_ENV=development

Caching

• Auth tokens refresh before expiry (default margin: 1 minute).
• Secret values cache in memory for 5 minutes by default (AKEYLESS_SECRET_CACHE_TTL_MS).
• Long-lived Fly Machines reuse the module singleton.

Lower TTL or use ignoreCache: true for frequently rotated secrets.

Push sync vs runtime pull

| Pattern | When to use | |---------|-------------| | Runtime pull (this package) | Akeyless stays source of truth; only bootstrap creds on Fly | | Push sync | Copy secrets into Fly secrets (future Akeyless Destination Sync or CI) |

Runtime pull works today without any Fly marketplace listing.

Example app

npm run build
cd examples/express && npm install
npm start

Set AKEYLESS_* env vars before starting.

Publishing

This package is Apache-2.0 and published as @akeyless-community/fly-runtime on npm.

To publish from a standalone clone:

npm ci
npm test
npm publish --access public

Related community projects

• @akeyless-community/vercel-runtime — Vercel runtime secrets
• @akeyless-community/netlify-runtime — Netlify runtime secrets
• @akeyless-community/heroku-runtime — Heroku runtime secrets
• @akeyless-community/railway-runtime — Railway runtime secrets
• buildkite-akeyless-plugin — CI secret injection

License

Apache-2.0