> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Define an agent config, grant the resources, and launch an agent with the dashboard, the CLI, the REST API, or the TypeScript SDK

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](https://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.1` and `openai/gpt-6.1-sol`.
* **`default-pool`** — a pool of Omnara-managed sandboxes with [common development tools preinstalled](/machines/pools#default-machine-environment).

## Setup with a Skill

Use [the skill located here](https://github.com/omnara-ai/omnara/tree/main/skills/setup-omnara-agent/SKILL.md) to setup Omnara for your project. Alternatively, send this prompt to your agent:

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

## Create and launch the agent

**API**

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

**1. 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 your account menu at the bottom of the sidebar, choose **Personal tokens**, click **New token**, and save the value.

```bash CLI theme={null}
npx omnara login
npx omnara config select
```

```bash REST theme={null}
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')"
```

```typescript SDK theme={null}
// 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
```

**2. Write the config**

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

```yaml theme={null}
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.1
tools:
  web_search: {}
  web_fetch: {}
  ask_question: {}
machine_sources:
  - machine_pool_name: default-pool
```

**3. Upload the config and launch the agent**

```bash CLI theme={null}
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
```

```bash REST theme={null}
export AGENT="$(
  jq -n --rawfile src agent.yaml '{
    config_source: {source: $src, source_format: "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."
  }' |
  curl -fsS "$OMNARA_API/orgs/$ORG/projects/$PROJ/agents" \
    -H "Authorization: Bearer $OMNARA_TOKEN" \
    -H "Content-Type: application/json" \
    -d @- |
  jq -r '.agent.id'
)"
```

```typescript SDK theme={null}
import { readFile } from 'node:fs/promises'

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

const launched = await sdk.createAgent({
  client,
  path: { orgID, projectID },
  body: {
    config_source: { source, source_format: '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.',
  },
})
const agentID = launched.data.agent.id
```

**4. 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:

```bash CLI theme={null}
npx omnara agents chat {agent-id}
```

```bash REST theme={null}
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."}]}'
```

```typescript SDK theme={null}
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}`.

**Dashboard**

**1. Open the agent editor**

In your project, open **Agents** and click **New agent**.

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

**3. Grant and select the model**

Select your preferred model from the `omnara-openrouter` provider. Omnara automatically [grants](/concepts) models to the default project in your organization.

**4. Grant and select the machine pool**

Select `default-pool` as a machine source, which provides your agent with a sandboxed environment. Omnara automatically [grants](/concepts) a machine pool to the default project in your organization.

**5. 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

Prefer a ready-made agent? The [examples](/examples/overview) deploy with one prompt to your coding agent.

> **[Concepts](/concepts)**
>
> The object model behind Omnara

> **[Agents](/agents/overview)**
>
> Launch, update, cancel, and archive agents

> **[Agent configuration](/agents/configuration)**
>
> Define models, tools, permissions, and machines

> **[Machine pools](/machines/pools)**
>
> Create machine pools and control their capacity


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.