Environment

This interface is experimental — no production implementation exists yet. The API surface may change.

Overview

The Env interface provides kernel-level access to environment variables in the execution environment. It defines a convergent surface for creating, reading, updating, and removing configuration variables across deployment platforms such as Vercel, Cloudflare Workers, and Railway.

Variables can be scoped to specific deployment targets and marked as sensitive to control how they are handled by the platform.

TypeScript API

import type {
  Env,
  EnvEntry,
  EnvContext,
  EnvActions,
} from 'osprotocol/system/env'

EnvEntry

A single environment variable, including its value, optional target scopes, and sensitivity flag.

interface EnvEntry<T = string> {
  key: string
  value: T
  target?: string[]
  sensitive?: boolean
  metadata?: Record<string, unknown>
}

EnvContext

Read-only access for the context phase of the agent loop.

interface EnvContext {
  get(key: string): Promise<EnvEntry | null>
  list(): Promise<EnvEntry[]>
}

EnvActions

Write operations for the actions phase of the agent loop.

interface EnvActions {
  set(entry: Omit<EnvEntry, 'metadata'>): Promise<EnvEntry>
  remove(key: string): Promise<boolean>
}

Env

Full environment management interface for provider implementations.

interface Env {
  get(key: string): Promise<EnvEntry | null>
  set(entry: Omit<EnvEntry, 'metadata'>): Promise<EnvEntry>
  remove(key: string): Promise<boolean>
  list(): Promise<EnvEntry[]>
}

Usage Examples

Read a variable

const entry = await env.get('DATABASE_URL')

if (entry) {
  console.log(entry.key)       // 'DATABASE_URL'
  console.log(entry.sensitive) // true
}

Set a variable scoped to production

await env.set({
  key: 'API_SECRET',
  value: 'sk-live-...',
  target: ['production'],
  sensitive: true,
})

Rotate a key

await env.set({
  key: 'OPENAI_API_KEY',
  value: 'sk-new-...',
  sensitive: true,
})

// Or remove it entirely
await env.remove('OPENAI_API_KEY')

Integration

The Env interface integrates with:

Sandbox: Sandboxes inherit or override environment variables at creation time
Settings: Settings may reference environment variable keys for dynamic configuration
Preferences: Preference resolution can fall through to system-level values sourced from environment

On this page