open-ma/open-managed-agents/openma

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

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 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` 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.