Configuration Reference

Authoritative reference for oma’s configuration shapes. The TypeScript source of truth lives in packages/api-types; the in-repo human-readable schema doc is AGENTS.md.

Agent

interface AgentConfig {
  id: string;                   // assigned by the platform
  name: string;
  model: string;                // e.g. "claude-sonnet-4-6"
  system: string;               // system prompt
  tools: ToolDefinition[];
  skills?: string[];            // skill ids
  environment_id?: string;
  mcp_servers?: McpServerConfig[];
  memory_store_id?: string;
  harness?: string;             // defaults to "default"
  archived?: boolean;
  version: number;              // platform-bumped on every update
  created_at: string;
  updated_at: string;
}

Tool definitions

type ToolDefinition =
  | { type: 'agent_toolset_20260401' }                    // built-in toolset
  | {
      type: 'custom';
      name: string;
      description: string;
      input_schema: JsonSchema;
      execution:
        | { type: 'http'; endpoint: string; method?: string }
        | { type: 'sandbox'; command: string };
    };

MCP server config

interface McpServerConfig {
  name: string;                 // becomes the prefix: mcp__<name>__<tool>
  type: 'url' | 'stdio';
  url?: string;                 // required for HTTP/SSE; derived for stdio
  authorization_token?: string; // inline bearer (otherwise: matched vault credential)
  stdio?: {
    command: string;
    args?: string[];
    env?: Record<string, string>;
    port: number;               // 127.0.0.1:port the spawned process binds to
    ready_timeout_ms?: number;  // default 60_000
  };
}

For type: 'stdio', oma spawns the process inside the sandbox container, waits for the port to bind, and proxies the existing HTTP-based MCP tool wiring at it. Tool discovery is bounded at 15 s per server; up to 20 servers per agent.

Environment

interface EnvironmentConfig {
  id: string;
  name: string;
  base_image: string;            // e.g. "openma/sandbox-base:python-3.12"
  packages: {
    pip?: string[];
    npm?: string[];
    apt?: string[];
    cargo?: string[];
    gem?: string[];
    go?: string[];
  };
  network?: {
    allowlist?: string[];        // hostnames the sandbox may reach
    denylist?: string[];
  };
  env?: Record<string, string>;
}

Vault

A vault is a tenant-scoped credential bundle; credentials inside it are bound to MCP servers or sandbox CLIs.

interface Vault {
  id: string;
  tenant_id: string;
  name: string;
  created_at: string;
  updated_at: string;
  archived_at?: string;
}

// Credentials live in a separate table; each is one of three types
type CredentialAuth =
  | { type: 'static_bearer'; token: string; mcp_server_url: string }
  | { type: 'mcp_oauth'; access_token: string; refresh_token?: string;
      token_endpoint?: string; expires_at?: string; mcp_server_url: string }
  | { type: 'cap_cli'; cli_id: string; token: string };  // e.g. cli_id: "gh", "glab", "aws"

Binding to a host happens via the credential, not the vault: a static_bearer / mcp_oauth credential matches by parsing the request hostname against mcp_server_url; a cap_cli credential matches by cli_id lookup in the cap spec registry. Up to 20 credentials per vault. Tokens are AES-GCM-encrypted at rest under PLATFORM_ROOT_SECRET and never returned via the API once written.

Skill

interface SkillMetadata {
  type: 'skill';
  id: string;
  display_title: string;
  name: string;                  // SKILL.md frontmatter `name` — also the mount-folder name
  description: string;
  source: 'anthropic' | 'custom';
  latest_version: string;        // numeric epoch string
  created_at: string;
  updated_at: string;
}

// Per-version detail returned by GET /v1/skills/:id/versions/:version
interface SkillVersion {
  version: string;
  files: Array<{ filename: string }>;  // R2 objects under t/{tenant}/skills/{id}/{version}/<filename>
}

The platform mounts skill files at /home/user/.skills/{name}/ (using the SKILL.md name, not id) and inlines the SKILL.md body directly into the system prompt at session start — no lazy read. The injected wrapping is:

<source name="skill:{id}">
<skill name="{name}">
{full SKILL.md body}
</skill>
</source>

Attach to an agent with the object form (not a bare string array):

{ "skills": [{ "skill_id": "skill_abc123", "type": "custom" }] }

Built-in skills (source: "anthropic"): xlsx, pdf, docx, pptx — four total, no upload needed.

Memory store

interface MemoryStore {
  id: string;
  agent_id: string;
  embedding_model: string;       // defaults to platform setting
  vector_index: string;          // Vectorize index name
}

Session

interface SessionMeta {
  id: string;
  agent_id: string;
  agent_version: number;         // pinned at creation
  status: 'pending' | 'running' | 'idle' | 'done' | 'failed';
  created_at: string;
  updated_at: string;
}

interface SessionEvent {
  id: string;
  session_id: string;
  type: string;                  // 'agent.message', 'agent.tool_use', 'agent.thinking', etc.
  data: unknown;
  created_at: string;
}

The full event type catalog is in packages/api-types/src/events.ts.

Environment variables

Required for self-host. Set as Worker secrets via npx wrangler secret put NAME.

Required

Variable	Worker	Purpose
PLATFORM_ROOT_SECRET	main, integrations	Root secret for at-rest encryption (credentials, model card keys, integration tokens) and outbound MCP token signing. Workers refuse to start without it. Back it up — losing it makes every encrypted row unreadable.
BETTER_AUTH_SECRET	main	better-auth session signing key
API_KEY	main	Bootstrap REST key for first-run. .env.example / .dev.vars.example ship dev-test-key-change-me.
INTEGRATIONS_INTERNAL_SECRET	main, integrations	Shared secret between main and integrations workers

Optional auth / Console

Variable	Worker	Purpose
AUTH_DISABLED	main (Node + CF wrangler local)	Set to 1 for a single-user local trial. Every request becomes tenant_id="default" (no x-api-key), /auth-info returns providers: [], and the Console skips login. /auth/* returns 410 while auth is off. Do not use in production.
CONSOLE_DIR	main (self-host Node)	Path to the built Console SPA (index.html). Docker images set this. Local pnpm --filter @duyet/oma-main-node start also auto-detects apps/console/dist. Unset + no dist → API-only on :8787.

Optional integrations

Variable	Worker	Purpose
ANTHROPIC_API_KEY	main, agent	Fallback LLM credential when a tenant has not added a Model Card. In production, prefer per-tenant Model Cards from the Console — they’re encrypted under PLATFORM_ROOT_SECRET and rotatable without redeploy. (Alternates: OPENAI_API_KEY, MINIMAX_API_KEY.)
ANYROUTER_API_KEY	agent	Static fallback provider (routes through AnyRouter, an OpenAI-compatible gateway) used only when an agent’s model matches no Model Card and ANTHROPIC_API_KEY is unset. Bare claude-* handles are rewritten to anthropic/claude-*. AnyRouter aliases hyphenated anthropic/claude-sonnet-4-6 to dotted BYOK-only anthropic/claude-sonnet-4.6, so this path sends the catalog id anyrouter/free for those sonnet handles. Never send the dotted 4.6 slug.
CLAUDE_CODE_OAUTH_TOKEN	agent (self-host Node only)	Non-interactive Claude Code auth (claude setup-token) for agents on the claude-agent-sdk harness — the CI/CD alternative to ANTHROPIC_API_KEY for that harness’s CLI subprocess. Not available on the Cloudflare Workers deploy (the SDK can’t spawn a subprocess in a Workers isolate).
LINEAR_CLIENT_ID	integrations	Linear OAuth
LINEAR_CLIENT_SECRET	integrations	Linear OAuth
LINEAR_WEBHOOK_SECRET	integrations	Verify inbound Linear webhooks
GITHUB_APP_ID	integrations	GitHub App ID
GITHUB_PRIVATE_KEY	integrations	GitHub App private key (.pem contents)
GITHUB_WEBHOOK_SECRET	integrations	Verify inbound GitHub webhooks
SLACK_CLIENT_ID	integrations	Slack OAuth
SLACK_CLIENT_SECRET	integrations	Slack OAuth
SLACK_SIGNING_SECRET	integrations	Verify inbound Slack events
SLACK_MANAGED_CLIENT_ID	integrations	Shared managed Slack App for one-click “Add to Slack” — all three SLACK_MANAGED_* must be set together, else the wizard falls back to the bring-your-own-App manifest flow
SLACK_MANAGED_CLIENT_SECRET	integrations	Managed Slack App client secret
SLACK_MANAGED_SIGNING_SECRET	integrations	Managed Slack App signing secret
LINEAR_OAUTH_CLIENT_ID / LINEAR_OAUTH_CLIENT_SECRET	integrations	Unified OAuth connect flow (/oauth/linear/*) — provider is absent (501) unless both are set
GITHUB_OAUTH_CLIENT_ID / GITHUB_OAUTH_CLIENT_SECRET	integrations	Unified OAuth connect flow (/oauth/github/*)
SLACK_OAUTH_CLIENT_ID / SLACK_OAUTH_CLIENT_SECRET	integrations	Unified OAuth connect flow (/oauth/slack/*)
TELEGRAM_BOT_TOKEN	integrations	BotFather token — enables the /telegram/webhook route. Alone it only gets past the “not configured” 503; a bound agent is also required
TELEGRAM_AGENT_ID	integrations	Agent that Telegram chats run against (required to actually create/resume sessions)
TELEGRAM_VAULT_IDS	integrations	Comma-separated vault ids bound to Telegram sessions
TELEGRAM_ENVIRONMENT_ID	integrations	Environment for Telegram sessions
TELEGRAM_IDLE_TIMEOUT_MS	integrations	Idle window before a chat’s sandbox is auto-paused. Default 5 min (300000)
GOOGLE_CLIENT_ID	main	Google sign-in for Console
GOOGLE_CLIENT_SECRET	main	Google sign-in for Console
STRIPE_SECRET_KEY	main	Consumer payments / paywall (@duyet/oma-payments). Unset → checkout returns 501
STRIPE_WEBHOOK_SECRET	main	Verify POST /webhooks/stripe signatures
PAYMENTS_DISABLED	main	Kill-switch — set truthy to make every publication turn free regardless of pricing

Optional infra

Variable	Worker	Purpose
TAVILY_API_KEY	main, agent	Web search backend for web_search built-in
CLOUDFLARE_API_TOKEN	main	Programmatic CF resource management (optional)
CLOUDFLARE_ACCOUNT_ID	main	Programmatic CF resource management (optional)
INTEGRATIONS_PUBLIC_URL	main	Override auto-detected integrations URL
PER_TENANT_DB_ENABLED	main	Set "true" to enable per-tenant D1 isolation
STORE_BACKENDS	main	JSON config for storage backends (advanced)
DATABASE_URL	main	External Postgres URL (advanced)
SCHEDULED_AGENT_RUNS_CRON	main	Override the agent-schedule tick cron (default * * * * *, per minute). Cloudflare only

Cloudflare bindings

What each Worker needs in its wrangler.jsonc:

apps/main

Binding	Type	Name
MAIN_DB	D1	openma-auth
CONFIG_KV	KV	(your namespace)
FILES_BUCKET	R2	managed-agents-files
AI	Workers AI	(built-in)
VECTORIZE	Vectorize	openma-memory
SANDBOX_sandbox_default	Service	→ agent worker
INTEGRATIONS	Service	→ integrations worker
SEND_EMAIL	Email	(your sender)
ANALYTICS	Analytics Engine	oma_events

apps/agent

Binding	Type	Name
SESSION_DO	Durable Object	SessionDO
SANDBOX	Durable Object	Sandbox (Container class)
CONFIG_KV	KV	(shared with main)
MAIN_DB	D1	(shared with main)
WORKSPACE_BUCKET	R2	managed-agents-workspace
FILES_BUCKET	R2	(shared with main)
AI, VECTORIZE, BROWSER, ANALYTICS	(same as main)

apps/integrations

Binding	Type	Name
MAIN_DB	D1	(shared with main)
MAIN	Service	→ main worker

Where to go next

API Endpoints Endpoint-by-endpoint reference.

Glossary Every term, alphabetized.