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.

Storing credentials? See Secrets vs Parameter Store to choose the right primitive.

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

1. App Config Service - A web UI and REST API for managing the configuration
2. Valkey - A Redis-compatible in-memory data store that holds the configuration values (provisioned automatically when using MCP or the web console)

• 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 kicks off provisioning and returns immediately. The tool response includes { ready: false, nextStep: "wait-for-parameter-store" } so the agent knows to follow up automatically. The full sequence:

1. setup-parameter-store triggers creation of Valkey and App Config Service (provisioned together by the platform)
2. wait-for-parameter-store polls until both services are healthy (up to 120 seconds), then returns the CONFIG_API_KEY

The entire process takes about 30 to 120 seconds.

Instead of setting parameters one by one, you can use bulk-set-parameters to configure several keys in a single call:

"Set the following parameters in my configstore: DATABASE_URL=postgres://..., SMTP_HOST=mail.example.com, APP_ENV=production"

The agent will call bulk-set-parameters which writes all keys in parallel and reports any that failed while continuing with the rest.

You can list the keys in a parameter store to check which parameters are configured:

"List the parameters in my configstore"

The agent will call list-parameters, which returns each key name along with a presence indicator (set with a coarse size hint, or empty) — it does not return the stored values. To retrieve a specific value, ask:

"Get the value of DATABASE_URL from my configstore"

To retrieve all values at once, use bulk-get-parameters:

"Show me all parameters in my configstore"

Note that bulk-get-parameters returns plaintext values. Use it only when you need to inspect the actual stored values, not just confirm which keys exist.

For workflows where you want to kick off store creation and then check back when ready, use the two-step approach directly:

Step 1 — start (fast, returns immediately): Ask your agent to set up the store:

"Set up a parameter store called myconfig"

The agent calls setup-parameter-store, which triggers Valkey and App Config Service provisioning and returns right away with { ready: false, nextStep: "wait-for-parameter-store" }.

Step 2 — wait (up to ~120 s): Once you are ready to use the store, ask:

"Wait for the parameter store myconfig to be ready"

The agent calls wait-for-parameter-store, which polls the platform status endpoint (up to 40 checks, 3 seconds apart) until both Valkey and App Config Service are healthy, then returns the CONFIG_API_KEY. Save this key as an OSC Service Secret immediately; it is shown only once.

When you create a parameter store via the setup-parameter-store or create-parameter-store MCP tool, encrypted secrets are enabled by default. Values marked as secrets are stored encrypted at rest, and a CONFIG_API_KEY is generated automatically. You do not need to pass any extra options.

To create a plaintext-only store (not recommended for production), explicitly opt out:

"Set up a parameter store called myconfig without encrypted secrets"

The agent then calls setup-parameter-store with enableSecrets: false.

Encrypted secrets can only be enabled at creation time. You cannot add encryption to an existing store — delete and recreate it to enable encryption.

If your account has parameter stores whose key names look sensitive (containing words such as KEY, SECRET, TOKEN, PASSWORD, or CREDENTIAL) but were created without encryption enabled, the OSC dashboard shows a warning in two places:

• Dashboard banner — a yellow advisory bar at the top of any dashboard page, with a link directly to the parameter stores list. The banner is dismissible for the current browser session.
• Parameter stores table chip — a warning chip on the affected row in the My Apps → Stores tab.

To resolve the warning, recreate the affected stores with encryption enabled (encryption cannot be added to an existing store). See the Encrypted Secrets section above for the creation steps.

Ask your AI agent to create a store with encryption (the default):

"Set up a parameter store called myconfig"

The agent calls setup-parameter-store, which:

1. Generates a PARAMETER_ENCRYPTION_KEY stored server-side in the App Config Service instance
2. Generates a CONFIG_API_KEY — shown once, cannot be retrieved later. Copy it before the conversation continues and store it as an OSC Service Secret.
3. Creates the App Config Service with both keys configured

Callers use CONFIG_API_KEY as a bearer token to read decrypted values:

curl https://myconfig.eyevinn-app-config-svc.auto.prod.osaas.io/api/v1/config/API_KEY \
  -H "Authorization: Bearer <CONFIG_API_KEY>"

Without the header, secret values are returned as ***.

Marking parameters as secrets

Once your store has encrypted secrets enabled, mark individual values as secrets when writing them:

"Set the parameter API_KEY to sk-abc123 as a secret in my configstore"

The agent calls set-parameter with secret: true. Secret values are stored encrypted and shown as *** in the web UI.

To set multiple secrets at once:

"Set DATABASE_URL, STRIPE_KEY, and WEBHOOK_SECRET in myconfig as secrets"

The agent calls bulk-set-parameters with those keys listed in secretKeys.

Creating via the web console

When creating a new parameter store from the My Apps dashboard, toggle Enable Encrypted Secrets before clicking Create. The modal shows the CONFIG_API_KEY once on success — copy it before clicking Done.

To remove a parameter store and all its associated resources, ask your AI agent:

"Delete the parameter store myconfig"

The agent calls delete-parameter-store, which removes the App Config Service instance, the Valkey instance, and the associated encryption secrets in a single operation. The deletion is best-effort and idempotent, so you can retry safely if a partial failure occurs.

Warning: Deleting a parameter store is permanent. Any application that depends on the store will lose access to its configuration values.

If you mistype a store name, the AI agent automatically resolves it to the closest match. For example, if your store is called altravoconf and you ask for altravo, the agent will find the correct store via prefix match and note the correction in its response. Auto-resolve applies to read-only operations (list-parameters, get-parameter, bulk-get-parameters). Write operations (set-parameter, delete-parameter) require the exact store name to avoid accidental writes to the wrong store.

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, use encrypted secrets (the recommended approach):

1. Create the parameter store with enableSecrets: true (see Encrypted Secrets above)
2. Mark sensitive parameters with secret: true when writing them

The values are stored encrypted at rest and masked in the UI. See the Encrypted Secrets section above for details.

Alternatively, you can combine plaintext parameter store values 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 the second approach.

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 keys set: use list-parameters MCP tool or the App Config web UI. The tool shows each key name with a presence indicator (set or empty) so you can quickly check whether values have been written without exposing the raw values.
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: Secrets vs Parameter Store - Choosing the right primitive for credentials
• 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.