Developer Guide: Environment Variables

This reference documents the environment variables used in Eyevinn Open Source Cloud (OSC) — both the variables your application receives automatically and the variables you use to authenticate with the platform.

Quick Reference

Variable Where It Applies Set By
OSC_ACCESS_TOKEN CLI, SDK, CI/CD You
PORT All deployed apps OSC (auto-injected)
APP_URL Node.js apps via Web Runner OSC (auto-injected)
AUTH_URL Node.js apps via Web Runner OSC (auto-injected)
APP_CONFIG_URL Monorepo apps using parameter store You (recommended convention)

Authentication Variables

OSC_ACCESS_TOKEN

Your Personal Access Token (PAT) for authenticating with OSC APIs. This is required by the CLI and the TypeScript SDK.

How to obtain it:

  1. Log in to app.osaas.io
  2. Navigate to Settings > { } API
  3. Copy the personal access token

Where to use it:

# CLI usage
export OSC_ACCESS_TOKEN=<your-token>
npx @osaas/cli list eyevinn-web-runner

# CI/CD (GitHub Actions)
env:
  OSC_ACCESS_TOKEN: ${{ secrets.OSC_ACCESS_TOKEN }}

The TypeScript SDK (@osaas/client-core) reads OSC_ACCESS_TOKEN automatically when you create a Context with no arguments:

import { Context } from '@osaas/client-core';

const ctx = new Context(); // reads OSC_ACCESS_TOKEN from env

Auto-Injected Variables

OSC automatically injects the following variables into deployed applications. You do not set these yourself — they are provided by the platform at startup.

PORT

The port your application must listen on.

Value Runtime
8080 Node.js (Web Runner), Python, WebAssembly

Your application must read this variable and bind to it. Hard-coding a port number will prevent your app from starting.

Node.js example:

const port = parseInt(process.env.PORT || '8080', 10);
app.listen(port, '0.0.0.0');

Python example:

import os
port = int(os.environ.get('PORT', 8080))
app.run(host='0.0.0.0', port=port)

This variable is required for both the Web Runner and for services submitted to the OSC catalog.

APP_URL

The public HTTPS URL of your deployed application.

Example value: https://yourapp-yourname.eyevinn-web-runner.auto.prod.osaas.io

When it is set: OSC injects APP_URL automatically based on the app's assigned hostname. If you set APP_URL yourself (via the parameter store), your value takes precedence and OSC will not override it. This is useful when you use a custom domain.

When it is not set: OSC can only inject APP_URL if the hostname is available at startup. If you need APP_URL and it is not set, configure it explicitly via the parameter store.

Applies to: Node.js apps deployed via Web Runner (My Apps). Not available in Python or WebAssembly runtimes.

Common uses:

// Constructing absolute URLs
const absoluteUrl = new URL('/api/callback', process.env.APP_URL);

// NextAuth v5 / Auth.js
// APP_URL is not used directly by NextAuth — use AUTH_URL instead

AUTH_URL

The authentication callback URL, derived from APP_URL. Intended for use with NextAuth v5 (Auth.js).

Default value: https://{hostname}/api/auth

Customizing the auth path: If your app uses a different auth path, set AUTH_PATH in your parameter store. For example, setting AUTH_PATH=/auth results in AUTH_URL being set to https://{hostname}/auth.

Precedence: If you set AUTH_URL yourself in the parameter store, your value takes precedence and OSC will not override it.

Applies to: Node.js apps deployed via Web Runner (My Apps). Not available in Python or WebAssembly runtimes.

NextAuth v5 (Auth.js) usage:

// auth.ts
import NextAuth from 'next-auth';

export const { handlers, auth, signIn, signOut } = NextAuth({
  // AUTH_URL is read automatically by Auth.js from the environment
  providers: [...]
});

NextAuth v4 users: NextAuth v4 uses NEXTAUTH_URL instead of AUTH_URL. Set NEXTAUTH_URL explicitly in your parameter store — OSC does not inject it automatically.

Parameter Store Variables

These variables come into play when you connect your app to a parameter store (an App Config Service instance backed by Valkey).

APP_CONFIG_URL

The URL of your App Config Service instance. This is not auto-injected by OSC — it is a recommended naming convention for passing the config service URL to your application.

When your Web Runner is configured with a ConfigService, the runner automatically loads all parameter store keys as environment variables at startup (before npm install and npm run build). Your application reads those values via process.env.YOUR_KEY and generally does not need to know the App Config Service URL.

However, for monorepo apps (where the workspace start command may bypass the root-level config loading step), it is useful to store the App Config Service URL in a parameter store key named APP_CONFIG_URL. Your workspace entry point can then fetch it at runtime:

// workspace/backend/start.js
const { loadConfig } = require('./config-loader');

async function main() {
  if (process.env.APP_CONFIG_URL) {
    await loadConfig(process.env.APP_CONFIG_URL);
  }
  require('./index.js');
}

main();

The App Config Service URL format is: https://{instance-name}.eyevinn-app-config-svc.auto.prod.osaas.io

Monorepo apps: See Managing Custom Apps for a detailed explanation of the problem and solution.

Platform Authentication (Internal)

These variables are used internally by the platform and runners. You do not normally set them directly, but understanding them helps when debugging.

OSC_ACCESS_TOKEN (in Web Runner context)

When your app is deployed via My Apps with a configService, OSC stores a runner refresh token as a Kubernetes secret and passes it to the Web Runner as OSC_ACCESS_TOKEN. The runner exchanges this token for a fresh PAT at startup, then uses it to load environment variables from the parameter store.

If you see errors like [CONFIG] Action required: Your OSC_ACCESS_TOKEN may have expired, rebuild your app via the web console or MCP. Apps created before 2026-02-25 used short-lived PATs; rebuilding migrates them to long-lived refresh tokens automatically.

OSC_ENV

Used internally by the Web Runner to determine which OSC environment to contact (e.g., prod, dev, stage). Defaults to prod. You do not need to set this.

Variables for Catalog Services

If you are submitting your own service to the OSC catalog (not via My Apps), the most important variable is PORT. Your Dockerfile and application must read and use the PORT environment variable. OSC sets the port and routes traffic accordingly.

See the Creator Guide and Deploy or Publish Your Application for the full requirements.

Environment Variable Loading Order (Web Runner)

Understanding when variables are available matters for build-time vs. runtime use:

  1. Parameter store values — loaded from the App Config Service (if ConfigService is set). Available for both npm install, npm run build, and runtime.
  2. APP_URL and AUTH_URL — injected by the runner after parameter store loading. If you set these in the parameter store, your values take precedence.
  3. PORT — available throughout. Always set by OSC.

Key implication for Next.js: NEXT_PUBLIC_* variables are baked into the build at compile time. If you use the parameter store, these variables are available during npm run build because parameter store loading runs before the build step. However, if you commit them to a .env.production file in your repo, that also works and does not require the parameter store.

Setting Environment Variables

For secrets and configuration, use the Parameter Store instead of committing values to your repository. For sensitive values, store them as Service Secrets and reference them in the parameter store.

Method Use case
Parameter store All non-secret configuration and API keys
Service secrets Passwords, tokens, and other sensitive values
Repository .env.production NEXT_PUBLIC_* build-time values only
GitHub Actions secrets CI/CD automation (e.g., OSC_ACCESS_TOKEN for deployments)