@akeyless-community/railway-runtime

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

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

Install

npm install @akeyless-community/railway-runtime

Requires Node.js 18+.

Quick start

1. Set bootstrap variables on Railway

In your Railway service Variables tab, add read-only Akeyless credentials:

| Variable | Required | Example | |----------|----------|---------| | AKEYLESS_ACCESS_ID | Yes* | p-xxxxx | | AKEYLESS_ACCESS_KEY | Yes* | access key secret | | AKEYLESS_SECRET_PREFIX | Recommended | /railway/my-project/production | | AKEYLESS_GATEWAY_URL | No | https://api.akeyless.io |

* Or use another auth method below.

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

/railway/{RAILWAY_PROJECT_NAME}/{RAILWAY_ENVIRONMENT_NAME}

Railway sets RAILWAY_PROJECT_NAME, RAILWAY_ENVIRONMENT_NAME, and RAILWAY_SERVICE_NAME automatically on every deployment. See the Railway variables reference.

2. Store application secrets in Akeyless

/railway/my-project/production/DATABASE_URL
/railway/my-project/production/STRIPE_SECRET_KEY

For multi-service projects, either use a shared project/environment prefix or opt into per-service prefixes:

AKEYLESS_INCLUDE_SERVICE_IN_PREFIX=true
# → /railway/my-project/production/api-service/DATABASE_URL

3. Fetch secrets in your app

const express = require('express');
const { getSecret } = require('@akeyless-community/railway-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

| Railway environment | Typical prefix | |---------------------|----------------| | production | /railway/my-project/production | | staging | /railway/my-project/staging | | development | /railway/my-project/development |

Set AKEYLESS_SECRET_PREFIX explicitly when you need a custom layout.

API

Convenience (singleton, replica-friendly)

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

const dbUrl = await getSecret('DATABASE_URL');

Explicit client

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

const client = createClient({
  gatewayUrl: 'https://api.akeyless.io',
  secretPrefix: '/railway/my-project/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 Railway service variables 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 /railway/... path.

Local development with Railway CLI

Run your app locally with the same variables as your Railway project:

railway link
railway run npm start

Or export variables manually:

export AKEYLESS_ACCESS_ID=p-xxxxx
export AKEYLESS_ACCESS_KEY=your-key
export AKEYLESS_SECRET_PREFIX=/railway/my-project/development
export RAILWAY_PROJECT_NAME=my-project
export RAILWAY_ENVIRONMENT_NAME=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 Railway replicas 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 Railway | | Push sync | Copy secrets into Railway variables (future Akeyless Destination Sync or CI) |

Runtime pull works today without any Railway partnership or marketplace listing.

Example app

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

Set AKEYLESS_* env vars (or use railway run) before starting.

Publishing

This package is Apache-2.0 and published as @akeyless-community/railway-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
• buildkite-akeyless-plugin — CI secret injection

License

Apache-2.0