Setup Omnara Agent

Read https://docs.omnara.com/llms.txt and the Quickstart guide first. Fetch other documentation pages as you need them.

Choose an interface

Check whether the Omnara MCP server is attached to this session: look for its tools, such as whoami, profiles_create, and agents_launch.

• MCP server attached: use the Omnara MCP tools for every step they cover. Do not install or log in to the CLI for those steps.
• No MCP server: use the npx omnara CLI for every step.

Steps below name both forms as MCP tool / CLI command.

Authenticate

• MCP: call whoami. If it fails with an authorization error, ask the user to complete the Omnara browser authorization for the MCP server in their client, then call whoami again. Do not continue setup until it succeeds.
• CLI: run npx omnara whoami. If not logged in, run npx omnara login in an interactive terminal session without piping output; add --no-browser on headless or remote machines. By default, login opens a browser for the user to sign in and approve access. Whenever login starts, immediately share the approval link and code and keep the command running while the user approves. Do not continue setup until login completes and npx omnara whoami succeeds.

Set up the agent

Then, ask the user questions on what type of agent they'd like to create:

1. Ask two questions before creating anything. a. What should the agent do? Examples include a coding agent, deep research agent, etc. b. How will you interact with the agent (Omnara web console, Slack, GitHub, Discord, or your own app using the public API/TypeScript SDK)?

2. Look up the user's org, its default project, and the granted model and machine pool (orgs_list, projects_list, grant_models_list, grant_pools_list / the equivalent npx omnara commands). Tailor the instruction to the user's request. Create a reusable profile with profiles_create / npx omnara profiles create.

   • Select ordinary built-in tools from tools_catalog / GET /tool-catalog, excluding create_machine and delete_machine. Do not include integration tools through blanket selection; they require a saved integration.
   • For integration capabilities, follow https://docs.omnara.com/integrations/overview and the provider's setup guide. Tools use int__<integration-name>__<tool-name> under tools; handlers use interaction_handlers: {integration-name: {}}. Integration launchers add the integration's missing tools to a derived config, preserving existing profile entries; Slack and Discord launchers also add their interaction handler with list_interaction_handlers and set_interaction_handler. Slack and Discord tools use the thread assigned at launch; GitHub tools use the assigned PR. Adding tools alone does not assign a conversation.
   • For manual configs with an interaction handler, include list_interaction_handlers and set_interaction_handler under tools. These tools are not added to every config. The dashboard remains available for questions and approvals.
   • Incoming subscriptions belong to the integration, independently of config. Removing a tool does not stop forwarding; remove the specific subscription through the integration Conversations page or subscription API.
   • Validate source against the source JSON Schema. The OpenAPI contract defines matching API/SDK schemas.
   • The granted model and machine pool
   • Relevant secrets or startup scripts for the machine pool env override. For example, if the user wants to clone a Github repository, you may setup a script which clones the repo upon starting the machine. If needed, you can pipe a Github PAT via a secret into the env var overlay

3. Launch an agent from the profile with agents_launch / npx omnara agents launch and a simple first message. Provide the user with a link to the agent at https://app.omnara.com/projects/{project_id}/agents/{agent_id}

4. (optional: interact via Slack) Create a project integration with integration_kind: slack_thread through npx omnara integrations create, and select the profile in its launcher with npx omnara integrations profiles. Then connect the saved integration with npx omnara integrations slack {integration_id} .... Use -h for current arguments and follow the Slack guide for creating a Slack registration with a configuration token from https://api.slack.com/apps or connecting an existing registration. The MCP server has no integration setup tools, so authenticate the CLI as described above before this step.

   Newly launched agents receive the integration's thread tools, interaction handler and a subscription for replies; the profile's base config is unchanged. This does not attach the earlier dashboard-launched agent to Slack. To forward messages to an existing agent, use the integration subscription API. A normal API launch can supply subscriptions separately from config; subscriptions alone do not assign sending context. For GitHub or Discord, use the current provider guide.

5. (optional: interact via SDK or REST API) Help the user setup their own custom application to interact with Omnara. Omnara can be used via a Typescript SDK, install the @omnara/sdk package to use it. Alternatively, in non-Typescript environments, Omnara can be used directly via the API, see the openapi specification at https://docs.omnara.com/api-reference/openapi.yaml. In the case of a frontend application, these APIs may need to be proxied through the user's API in order to avoid CORS errors. Help the user generate an organization-level API token to interact with the API through the CLI or API.

   If you're building your own integration using Omnara's API, follow https://docs.omnara.com/integrations/custom-integrations. Give its API key the required project role. Your service decides which agent receives each message and sends ordinary inputs with actor attribution and an Idempotency-Key; no Omnara integration registration is needed. Custom tools use the ordinary tool-call/result lifecycle. Your service also chooses where to display questions and approvals, then submits the answers through the API. The dashboard can answer those same interactions.