A parameter store provides a centralized way to manage configuration values for your applications running on Eyevinn Open Source Cloud. This guide shows you how to set up a parameter store using the App Config Service backed by Valkey.

A parameter store is a key-value storage system for managing application configuration. It consists of two components:

1. Valkey - A Redis-compatible in-memory data store that holds the configuration values
2. App Config Service - A web UI and REST API for managing the configuration

• Centralized Configuration - Store all your application settings in one place
• Easy Updates - Change configuration values without redeploying your application
• Environment Variables - Automatically inject configuration as environment variables into Web Runner and WASM Runner instances
• Feature Flags - Toggle features on/off dynamically
• Secrets Management - Store API keys and sensitive configuration (combined with OSC Service Secrets for sensitive values)

Parameter store names must be alphanumeric only (letters and digits, no underscores, hyphens, or other special characters):

• ✅ Valid: myconfig, myStore123, configprod
• ❌ Invalid: my_config, my-config, my.config

The same name is used for both the Valkey instance and the App Config Service instance.

The fastest way to set up a parameter store is using the OSC MCP tools with an AI agent.

• An OSC account
• Claude Desktop, Claude Code, VS Code, or Cursor with MCP configured (see setup guide)

Simply ask your AI agent:

"Set up a parameter store for me"

Or be more specific:

"Create a parameter store called myconfig"

The AI agent will use the setup-parameter-store MCP tool which:

1. Creates a Valkey instance for data storage
2. Retrieves the Valkey connection details
3. Creates an App Config Service instance
4. Configures the App Config Service to use the Valkey instance
5. Verifies the setup is working

The entire process takes about 30 seconds.

If you prefer to set up manually:

1. Navigate to the Valkey service
2. Click Create valkey
3. Enter a name (e.g., configstore)
4. Click Create
5. Wait for the instance to be ready

1. Go to your active services dashboard
2. Click on your Valkey instance
3. Note the External IP and External Port
4. Construct the Redis URL: redis://<external-ip>:<external-port>

1. Navigate to the App Config Service
2. Click Create app-config-svc
3. Enter a name (e.g., myconfig)
4. In RedisUrl, enter the URL from Step 2
5. Click Create

1. Click on your App Config Service instance
2. Click Open to access the web UI
3. Try adding a test configuration key/value pair

# Create Valkey instance
npx @osaas/cli create valkey-io-valkey configstore

# Get the Valkey instance details
npx @osaas/cli describe valkey-io-valkey configstore

# Extract IP and port from the output, then create App Config Service
npx @osaas/cli create eyevinn-app-config-svc myconfig \
  -o RedisUrl="redis://123.45.67.89:12345"

Replace 123.45.67.89:12345 with the actual external IP and port from the Valkey instance.

1. Open your App Config Service instance from the dashboard
2. Click Open to access the web UI
3. Add key-value pairs:
   • Key: DATABASE_URL
   • Value: postgresql://user:pass@host:5432/db
4. Values are immediately available via the API

When creating a Web Runner instance, specify your parameter store in the ConfigService field:

npx @osaas/cli create eyevinn-web-runner myapp \
  -o SourceUrl="https://github.com/yourusername/yourapp" \
  -o ConfigService="myconfig"

All configuration values will be loaded as environment variables when your app starts.

Similarly for WASM Runner:

npx @osaas/cli create eyevinn-wasm-runner mywasm \
  -o WasmUrl="https://example.com/app.wasm" \
  -o ConfigService="myconfig"

curl https://myconfig.eyevinn-app-config-svc.auto.prod.osaas.io/api/v1/config/DATABASE_URL

Response:

{
  "key": "DATABASE_URL",
  "value": "postgresql://user:pass@host:5432/db"
}

curl -X POST https://myconfig.eyevinn-app-config-svc.auto.prod.osaas.io/api/v1/config \
  -H "Content-Type: application/json" \
  -d '{"key":"API_KEY","value":"sk_live_abc123"}'

curl https://myconfig.eyevinn-app-config-svc.auto.prod.osaas.io/api/v1/config

If your Web Runner application needs to fetch config at runtime:

import { Context } from "@osaas/client-core";
import { getEyevinnAppConfigSvcInstance } from "@osaas/client-services";

async function getConfig(key) {
  const ctx = new Context();
  const configService = await getEyevinnAppConfigSvcInstance(ctx, 'myconfig');

  const response = await fetch(
    new URL(`/api/v1/config/${key}`, configService.url),
    { cache: 'no-store' }
  );

  if (response.ok) {
    const data = await response.json();
    return data.value;
  }
  return undefined;
}

// Usage
const apiKey = await getConfig('API_KEY');

For sensitive values like API keys and passwords, combine parameter store with OSC Service Secrets:

1. Store the sensitive value as a Service Secret
2. Reference it in your parameter store value using {{secrets.secretname}}
3. The secret value will be injected when the configuration is loaded

See Working with Secrets for details.

Use consistent naming conventions:

• Environment-specific: PROD_DATABASE_URL, DEV_DATABASE_URL
• Service-specific: AUTH_SERVICE_URL, PAYMENT_SERVICE_URL
• Feature flags: FEATURE_NEW_DASHBOARD, ENABLE_BETA_FEATURES

• Configuration changes are immediate - no restart required for Web Runner or WASM Runner
• If your app caches config values, implement a refresh mechanism
• Use the web UI for manual updates, use the API for automated deployments

Parameter store values are stored via JSON and preserved faithfully in the parameter store itself. However, when values are injected as environment variables into your application at startup, shell metacharacters can cause problems.

⚠️ Avoid shell metacharacters in parameter values that will be injected as environment variables. The following characters may be silently corrupted or cause unexpected behaviour at runtime:

! $ # & * ? [ ] ( ) { } | ; < > `

Safe characters for environment variable values:

• Alphanumeric characters (a-z, A-Z, 0-9)
• Hyphens (-), underscores (_), dots (.), slashes (/), colons (:), at-signs (@)
• Most printable characters except the shell metacharacters listed above

If your password or secret must contain shell metacharacters (e.g., Mypassword2024!), use base64 encoding:

# Encode the value
echo -n 'Mypassword2024!' | base64
# Output: TXlwYXNzd29yZDIwMjQh

# Store the base64-encoded value in the parameter store

Then decode it in your application code:

// Node.js example
const password = Buffer.from(process.env.MY_PASSWORD, 'base64').toString('utf-8');

This ensures the value is preserved faithfully through the environment variable injection.

• Verify the Valkey instance is running and healthy
• Check the Redis URL format: redis://<ip>:<port> (no trailing slash)
• Ensure the external IP and port are correct

• Verify the ConfigService parameter matches the exact name of your App Config Service instance
• Check that the App Config Service instance is running
• Look at the Web Runner logs for connection errors
• If logs show [CONFIG] ERROR or Authorization: command not found, the config service token may have expired — recreate the app with delete-my-app + create-my-app

If logs show [CONFIG] Loaded 0 environment variable(s) or [CONFIG] WARNING: Config service returned no valid environment variables:

1. Verify the parameter store has values: use list-parameters MCP tool or the App Config web UI
2. Check if the config service authentication failed (look for error messages in the logs)
3. If auth failed, rebuild the app (restart-my-app with rebuild=true) to migrate to a long-lived refresh token
4. Monorepo apps (subPath): If your app uses both subPath and configService, the workspace's start command may bypass the root-level config loading. See Monorepo Apps with subPath and configService for details

• Ensure the App Config Service instance is in "Running" state
• Try refreshing the instance URL
• Check the service status page for any platform issues

• Service: App Config Svc - Detailed App Config Service documentation
• Service: Valkey - Redis-compatible data store
• Service: Web Runner - Using parameter store with Web Runner
• Service: WASM Runner - Using parameter store with WASM Runner
• User Guide: Working with Secrets - Managing sensitive configuration
• User Guide: Enable OSC with AI agents - MCP setup for automated parameter store creation
• Developer Guide: Overview - Example code using parameter store

Both Valkey and App Config Service are billed separately based on runtime. See Pricing for details.