Quickstart

Launch your first agent with Omnara via the dashboard, or programmatically with the CLI, the REST API, or the TypeScript SDK.

Before you start

Sign in at app.omnara.com. When you sign in the first time, Omnara creates your first organization and project, plus two default resources this guide uses:

omnara-openrouter — a model provider with frontier models such as anthropic/claude-fable-5 and openai/gpt-5.6-sol.
default-pool — a pool of Omnara-managed sandboxes.

Setup with a Skill

Use the skill located here to setup Omnara for your project. Alternatively, send this prompt to your agent:

Help me setup Omnara by fetching the Skill file here: https://github.com/omnara-ai/omnara/tree/main/skills/setup-omnara-agent/SKILL.md

Create and launch the agent

API
Dashboard

You can interact with Omnara via the CLI, the REST API, or the TypeScript SDK.

Set up

The CLI signs in through your browser; if you have not logged in yet, the first command that needs your account starts the login for you. The REST API and the SDK authenticate with an API token. In the web browser, open Tokens in the sidebar, click New token, and save the value.

npx omnara login
npx omnara config select

export OMNARA_API="https://api.omnara.com/v1"    # or your self-hosted origin + /api/v1
export OMNARA_TOKEN="omnara_pat_v1_..."

export ORG="$(curl -fsS "$OMNARA_API/me" \
  -H "Authorization: Bearer $OMNARA_TOKEN" | jq -r '.orgs[0].id')"
export PROJ="$(curl -fsS "$OMNARA_API/orgs/$ORG/projects?limit=1" \
  -H "Authorization: Bearer $OMNARA_TOKEN" | jq -r '.data[0].id')"

// npm install @omnara/sdk
import { createOmnaraClient, bearerToken, sdk } from '@omnara/sdk'

const token = process.env.OMNARA_TOKEN
if (!token) throw new Error('Set OMNARA_TOKEN')

const client = createOmnaraClient({
  baseUrl: 'https://api.omnara.com/v1',
  auth: bearerToken(token),
})

const me = await sdk.getCurrentUser({ client })
const orgID = me.data.orgs[0].id

const projects = await sdk.listVisibleProjects({
  client,
  path: { orgID },
  query: { limit: 1 },
})
const projectID = projects.data.data[0].id

Write the config

Save this config as agent.yaml. The machine tools run on the cloud machine that Omnara creates from default-pool at launch:

version: v1
instruction: |
  You are an engineering assistant. Use your machine to run
  commands. Use web search to find current information. Ask a
  question when a task is not clear.
model:
  provider_config: omnara-openrouter
  name: anthropic/claude-fable-5
tools:
  run_command: {}
  read_process: {}
  list_processes: {}
  list_machines: {}
  inspect_machine: {}
  web_search: {}
  web_fetch: {}
  ask_question: {}
machine_sources:
  - machine_pool_name: default-pool

Upload the config and launch the agent

npx omnara agents launch --file agent.yaml \
  --name "Machine assistant" \
  --message "Use your machine to report the operating system and the free disk space. Then find the latest stable Node.js release on the web and tell me the version."

# or upload the config as a reusable profile instead:
npx omnara profiles create --name machine-assistant --file agent.yaml

export CONFIG="$(
  jq -n --rawfile src agent.yaml '{source: $src, source_format: "yaml"}' |
  curl -fsS "$OMNARA_API/orgs/$ORG/projects/$PROJ/agent-configs" \
    -H "Authorization: Bearer $OMNARA_TOKEN" \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r '.id'
)"

export AGENT="$(
  curl -fsS "$OMNARA_API/orgs/$ORG/projects/$PROJ/agents" \
    -H "Authorization: Bearer $OMNARA_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "config": "'"$CONFIG"'",
      "name": "Machine assistant",
      "message": "Use your machine to report the operating system and the free disk space. Then find the latest stable Node.js release on the web and tell me the version."
    }' |
  jq -r '.agent.id'
)"

import { readFile } from 'node:fs/promises'

const source = await readFile('agent.yaml', 'utf8')

const config = await sdk.createAgentConfig({
  client,
  path: { orgID, projectID },
  body: { source, source_format: 'yaml' },
})

const launched = await sdk.createAgent({
  client,
  path: { orgID, projectID },
  body: {
    config: config.data.id,
    name: 'Machine assistant',
    message: 'Use your machine to report the operating system and the free disk space. Then find the latest stable Node.js release on the web and tell me the version.',
  },
})
const agentID = launched.data.agent.id

Follow the agent and send input

The event stream shows the tool calls and the reply as it is generated. Send a follow-up message while the stream runs:

npx omnara agents get {agent-id}

curl -N "$OMNARA_API/orgs/$ORG/projects/$PROJ/agents/$AGENT/events/stream?stream_deltas=true" \
  -H "Authorization: Bearer $OMNARA_TOKEN"

# from a second terminal:
curl -fsS "$OMNARA_API/orgs/$ORG/projects/$PROJ/agents/$AGENT/inputs" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content_blocks": [{"type": "text", "text": "Install that Node.js version on the machine and show me node --version."}]}'

import { openAgentEventStream } from '@omnara/sdk'

await sdk.createAgentInput({
  client,
  path: { orgID, projectID, agentID },
  body: {
    content_blocks: [
      { type: 'text', text: 'Install that Node.js version on the machine and show me node --version.' },
    ],
  },
})

for await (const event of openAgentEventStream({
  client,
  path: { orgID, projectID, agentID },
  query: { stream_deltas: true },
})) {
  console.log(event)
}

To watch the conversation live and send follow-up messages from the browser, open https://app.omnara.com/projects/{project-id}/agents/{agent-id}.

Open the agent editor

In your project, open Agents and click New agent.

Select a template

In the Builder form, select the Deep researcher template. It fills the instruction and enables the tools the agent needs: web_search, web_fetch, run_command, the process and machine tools, and ask_question.

Grant and select the model

Select your preferred model from the omnara-openrouter provider. Omnara automatically grants models to the default project in your organization.

Grant and select the machine pool

Select default-pool as a machine source, which provides your agent with a sandboxed environment. Omnara automatically grants a machine pool to the default project in your organization.

Name the agent and launch

Click Create and launch agent. The dashboard validates the config, launches the agent, and opens the conversation view.

Next steps

Concepts

The object model behind Omnara

Agents

Launch, update, cancel, and archive agents

Agent configuration

Define models, tools, permissions, and machines

Machine pools

Create machine pools and control their capacity

Get started

Agents

Inputs & events

Tools

Machines

Organization

Integrations

Examples

Before you start

Setup with a Skill

Create and launch the agent

Next steps

Concepts

Agents

Agent configuration

Machine pools

​Before you start

​Setup with a Skill

​Create and launch the agent

​Next steps

Concepts

Agents

Agent configuration

Machine pools

Before you start

Setup with a Skill

Create and launch the agent

Next steps