Concepts

Omnara provides a stateful API for interacting with agents. This page provides an overview of the core entities you should understand when interacting with the dashboard or API.

​

Organizations and Projects

When you join Omnara, you join or create an organization. Organizations manage memberships, own shared team resources, and contain projects. Projects contain agents, their configs and profiles, and the grants that control which shared resources those agents may use.

​

Resources

Shared resources are owned at the org, project, or user scope:

• Machines and machine pools (org owned): existing computers you connect (BYO) or pools of ephemeral sandboxes that agents run commands on.
• Model providers and models (org owned): the model endpoints and configured models agents can use.
• Skills (org, project, or user owned): reusable instructions and tools for agents.
• Secrets (org, project, or user owned): credentials referenced by model providers, machine and their environments, and MCP servers.

​

Grants

A project can use a resource only if it owns it or holds an explicit grant. Org and user ownership alone don’t make a resource visible to a project — granting is the deliberate step that shares a model, pool, machine, secret, or skill with a project. Own each resource at the narrowest scope that needs it, and grant outward. In the web app, this step is called sharing: sharing a resource with a project creates a grant, which is the term the API and CLI use.

​

Agents

Agents are the core feature of Omnara. Define an agent’s model, tools, and instructions in a config or profile. Then Omnara runs the agent loop and runtime. Once an agent has started, interact with it by:

• Reading or streaming it’s event log
• Sending inputs, such as messages or file attachments
• Resolving questions and approvals

​

Integrations

Integrations connect one project to a provider such as Slack, Discord or GitHub. Create an integration from the project’s Integrations page, configure its credentials, and optionally choose which profiles it launches from provider events. An integration can supply tools for taking actions, a subscription capability for receiving activity, and an interaction handler for presenting questions and approvals. Agent configs select tools and handlers; launch requests or the integration subscriptions API attach conversations to agents. Changing config or removing a sending tool does not change subscriptions. Stop incoming forwarding from the integration’s Conversations list or delete the subscription through the API.

​

Continue