/openma

name: openma
description: >
  Use an existing OpenMA instance to build and manage AI agents. Trigger when
  users want to create agents, start sessions, manage environments, configure
  model cards, handle vaults/credentials, install skills, connect MCP servers,
  or interact with the openma HTTP API. Also trigger when users mention "oma",
  "openma", "managed agents", or ask how to run/manage an agent on OpenMA. For deploying the platform
  itself, use the deploy-openma skill instead.

openma

openma is an open-source platform for building, deploying, and managing AI agents. You define an agent (model + system prompt + tools), the platform handles sandboxed execution, credential management, and session state.

Setup

npm install -g @openma/cli
oma auth login --base-url https://app.openma.ai

For self-hosted instances, replace the login URL with the user's server origin. Confirm the instance and workspace before creating resources. Let the user complete browser authentication. For automation, accept `OMA_BASE_URL` and `OMA_API_KEY` from an existing secret manager or protected environment; do not ask for secrets in chat or print them in logs.

Run `oma --help` and `oma api` to check the installed CLI's commands and API shape. The CLI connects to an existing server; installing it does not deploy OpenMA.

Core Workflow

oma models list
oma envs list
oma agents list

Use an existing Model Card's `model_id`, not its database record ID. Choose a ready environment with the needed runtime capabilities. Create missing resources only as required for the user's task; replace the placeholders below with the returned IDs:

oma agents create "my-agent" --model <model-id> --system "Help with the requested task."
oma sessions create --agent <agent-id> --env <environment-id>
oma sessions chat <session-id> "Your task here"

`chat` sends a turn and streams its reply. `message` sends without waiting; `tail` follows events. A delivered message is not proof that the task succeeded. Check the resulting session status, events and outputs.

Resources

| Resource | CLI commands | Purpose | |----------|-------------|---------| | Agent | `oma agents create/list/get/delete` | Model + prompt + tools config | | Environment | `oma envs create/list` | Sandbox runtime for sessions | | Session | `oma sessions create/list/message` | Conversation with an agent | | Model Card | `oma models create/list` | LLM API key + provider config | | Vault | `oma vaults create/list` | Secure credential storage | | Credential | `oma creds list`, `oma secret add` | Secret inside a vault | | Skill | `oma skills list/install` | Domain expertise for agents | | API Key | `oma keys create/list/revoke` | Auth token for CLI/SDK | | Linear | `oma linear list/pubs/publish/submit/handoff/update/unpublish/get` | Publish agent into a Linear workspace |

Model Cards

Prefer Console Model Cards for entering provider credentials. `oma models list` shows configured card handles; use `oma api models` for the current API contract. Providers use Pi IDs such as `anthropic`, `openai`, `deepseek`, and `openrouter`; legacy aliases remain accepted. Custom providers can require `base_url` and `pi_config.api`; use the [SDK guide](https://github.com/openma-ai/open-managed-agents/tree/main/packages/sdk#pi-backed-model-cards) for that shape rather than assuming the CLI exposes every field.

MCP Server Connections

oma vaults create "my-vault"
oma connect github --vault <vault-id>

Known servers: `airtable`, `amplitude`, `apollo`, `asana`, `atlassian`, `clickup`, `github`, `intercom`, `linear`, `notion`, `sentry`, `slack`.

HTTP API Reference

Run `oma api` for the full endpoint reference, or `oma api <resource>` for a specific resource (agents, sessions, environments, models, vaults, oauth, skills, files, memory, keys, evals, clawhub).

All `/v1/*` endpoints require `x-api-key` header. Use SSE streaming via `GET /v1/sessions/:id/events/stream` for real-time agent responses.

Tips

• Check `oma agents list` / `oma envs list` before creating — reuse existing resources.
• Sessions are stateful — send multiple messages to continue the conversation.
• Use `oma api sessions` to see the full HTTP API when you need to code against it.
• The `agent_toolset_20260401` tool type gives agents file ops, bash, and web access.

Integrations

Publish an agent into a third-party tool so it acts as a teammate there. See [`integrations-linear.md`](integrations-linear.md) for the Linear flow — covers the OAuth-app handshake, the two moments a human is genuinely needed, and how to verify / unpublish from the CLI.