Skip to content
oma

Quickstart

This walks you through getting OMA running — choose the path that fits your environment.

Pick Your Path

Section titled “Pick Your Path”

Fastest way from zero to a running agent. Requires only Docker.

Prerequisites

Section titled “Prerequisites”
ToolVersionWhy
DockerLatestRuns the sandbox, database, and vault sidecar
curlAnyTest the API from the terminal
jqAnyParse JSON responses in the terminal

Steps

Section titled “Steps”

  1. Clone the repository.

    Terminal window
    git clone https://github.com/duyet/oma.git
    cd oma

  2. Configure environment variables.

    Terminal window
    cp .env.example .env

    Generate two required secrets and append them to .env:

    Terminal window
    echo "BETTER_AUTH_SECRET=$(openssl rand -hex 32)" >> .env
    echo "PLATFORM_ROOT_SECRET=$(openssl rand -base64 32)" >> .env

    .env.example already sets API_KEY=dev-test-key-change-me (same as .dev.vars.example). A provider key is required for a successful turn — set ANTHROPIC_API_KEY in .env or add a Model Card after you open the Console.

  3. Launch with Docker Compose.

    Terminal window
    docker compose up -d

    This starts the API, Console UI, and database. Wait a few seconds for migrations, then verify:

    Terminal window
    curl localhost:8787/health

    Expected (pid, uptime, and backend paths vary):

    {
      "status": "ok",
      "runtime": "node",
      "pid": 1,
      "uptime_s": 12,
      "auth": "better-auth-sqlite",
      "backends": {
        "agents": "sqlite",
        "events": "sqlite",
        "hub": "in-process",
        "memory_blobs": "localfs /app/data/memory-blobs",
        "db": "sqlite /app/data/oma.db"
      }
    }

  4. Create your first agent.

    Terminal window
    export OMA_BASE="http://localhost:8787"
    export OMA_KEY="$(grep '^API_KEY=' .env | cut -d= -f2-)"
    # .env.example / .dev.vars.example ship API_KEY=dev-test-key-change-me
    

    AGENT_ID=$(curl -s -X POST "$OMA_BASE/v1/agents" \
      -H "x-api-key: $OMA_KEY" \
      -H "content-type: application/json" \
      -d '{
        "name": "hello-agent",
        "model": "claude-sonnet-4-6",
        "system": "You are a helpful assistant. Keep replies short.",
        "tools": [{"type": "agent_toolset_20260401", "default_config": {"enabled": true}}]
      }' | jq -r .id)
    

    ENV_ID=$(curl -s -X POST "$OMA_BASE/v1/environments" \
      -H "x-api-key: $OMA_KEY" \
      -H "content-type: application/json" \
      -d '{"name":"local","config":{"type":"cloud"}}' | jq -r .id)
    

    echo "Agent: $AGENT_ID"
    echo "Environment: $ENV_ID"

  5. Send a message.

    Terminal window
    SESSION_ID=$(curl -s -X POST "$OMA_BASE/v1/sessions" \
      -H "x-api-key: $OMA_KEY" \
      -H "content-type: application/json" \
      -d "{\"agent\": \"$AGENT_ID\", \"environment_id\": \"$ENV_ID\"}" | jq -r .id)
    

    curl -N -X POST "$OMA_BASE/v1/sessions/$SESSION_ID/messages" \
      -H "x-api-key: $OMA_KEY" \
      -H "content-type: application/json" \
      -d '{"content": "Say hello and tell me what tools you have available."}'

    You’ll see the model’s reply stream token-by-token. A real model key is required for a successful turn — set ANTHROPIC_API_KEY in .env (or add a Model Card in the Console) and restart if the session stays silent.

  6. Open the Console.

    Open localhost:8787 in your browser. Sign up, or for a single-user local trial set AUTH_DISABLED=1 in .env, recreate the container, and the Console skips login (default tenant). Do not use that flag in production. From here you can:

    • Add a Model Card — go to Model Cards → Add and enter your API key
    • Create an agent — Agents → + New agent with the visual builder
    • View sessions — Sessions to see all runs and monitor activity

Next Steps

Section titled “Next Steps”

Troubleshooting

Section titled “Troubleshooting”
SymptomLikely causeFix
docker compose up failsPort 8787 in useStop the conflicting process or change the port in docker-compose.yml
health returns 503Migrations not finished, or missing BETTER_AUTH_SECRET / PLATFORM_ROOT_SECRETWait 10s and retry; for pnpm dev, set both secrets in repo-root .dev.vars
pnpm dev asks for a Cloudflare accountAlways-remote Workers AI bindingUse current pnpm dev (--local + wrangler.dev.jsonc; AI omitted)
Agent creation fails with 401Wrong API keyOMA_KEY must match API_KEY in .env (dev-test-key-change-me from .env.example)
Session create returns 400 environment_id is requiredNo environment on the requestCreate one with POST /v1/environments and pass environment_id (CLI: --env)
Session message returns no replyNo model card or ANTHROPIC_API_KEYAdd a Model Card in the Console, or set ANTHROPIC_API_KEY in .env and restart
setup-cf.sh failsWrangler not logged inRun npx wrangler login first

What’s Next

Section titled “What’s Next”
Self-host overview Full self-host guide: Postgres, BoxRun, vault sidecar, sandbox modes, operator gotchas.
Build with the API REST surface, auth, SSE streaming, the CLI, and the SDK types package.
Custom harness Replace the default agent loop with your own harness logic.
Deploy to Cloudflare Deploy to Workers, Durable Objects, and Cloudflare Containers.
Deploy guides Docker, Cloudflare, and Kubernetes deployment guides.