Configuration Reference

Authoritative reference for openma’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	Initial dev API key for the REST API
INTEGRATIONS_INTERNAL_SECRET	main, integrations	Shared secret between main and integrations workers

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.)
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
GOOGLE_CLIENT_ID	main	Google sign-in for Console
GOOGLE_CLIENT_SECRET	main	Google sign-in for Console

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)

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.