Built-in tools

Omnara includes built-in tools for common agent tasks. Add a tool by name under tools: in the agent’s config. Built-in tools default to always_allow, but you can change the permission for each one. This page explains what each tool does and the inputs it accepts. To retrieve the current catalog programmatically, use GET /tool-catalog. The tools are grouped by what they do:

Group	Tools
Web	`web_search`, `web_fetch`
Questions	`ask_question`
Commands	`run_command`
Processes	`read_process`, `write_process`, `stop_process`, `list_processes`
Machines	`create_machine`, `delete_machine`, `list_machines`, `inspect_machine`
Integrations	`send_integration_message`, `set_integration_target`
Skills	`skill`

A red * marks required inputs.

Web

`web_search`

Searches the public web and returns matching URLs, titles, and snippets.

Input	Type	Notes
`query`*	string
`num_results`	integer	1–20; default 5
`recency`	enum	`day`, `week`, `month`, `year`
`domains`	string[]	Restrict results to these domains

`web_fetch`

Fetches a public HTTP or HTTPS URL and returns readable content as Markdown or plain text. It cannot access localhost or private networks. To reach a service on an attached machine, use run_command with curl.

Input	Type	Notes
`url`*	string
`format`	enum	`markdown` (default), `text`
`timeout_seconds`	integer	1–120; default 30

Questions

`ask_question`

Asks a person one or more multiple-choice questions. The agent pauses until the resulting interaction is answered. Omnara automatically adds an Other option for free-text responses.

Input	Type	Notes
`questions`*	array	Min 1. Each item requires `prompt` and `options`; each option requires `label`. `multiple` defaults to false.

Commands

`run_command`

Runs a shell command on a machine attached to the agent.

Input	Type	Notes
`command`*	string
`machine_ref`	string	Which machine binding to use; omit when the agent has exactly one
`shell`	enum	`default`, `sh`, `bash`, `zsh`, `pwsh`, `powershell`, `cmd`
`cwd`	string	Overrides the binding’s working directory
`wait_ms`	integer	1–10000; how long to wait for early output or exit before returning
`io_mode`	enum	`pipe` (default) or `pty`

Every command returns a process_id (prc_…). wait_ms controls how long run_command waits for the command to finish before returning. If it finishes in time, the result includes its output:

{
  "process_id": "prc_rwz3jehcyd5n6a2bfgik7mv4qt",
  "state": "exited",
  "command": "git log -1 --format=%H",
  "output": "8c41d2e9f0a3b7c6d5e4f3a2b1c0d9e8f7a6b5c4\n",
  "done": true,
  "exit_code": 0
}

If the command is still running after wait_ms, the tool returns "state": "running". The agent can then read its output, send input, or stop it with the process tools below. Set run_command to always_ask to require approval before execution. The prompt shows the command, machine, shell, and working directory.

Picking a machine

machine_ref chooses which attached machine runs the command:

With one available machine, omit machine_ref.
With several, specify one.
With none, attach a machine in the config or use create_machine.

If Omnara cannot choose a machine, the tool returns an error to the agent so it can inspect its machines and retry.

Processes

Use these tools to follow or control commands that are still running. A process moves from starting to running, then ends as exited, failed, or killed.

`read_process`

Reads process output from a byte cursor and can briefly wait for new output.

Input	Type	Notes
`process_id`*	string
`cursor`	integer	≥ 0; resume where the last read stopped
`max_bytes`	integer	1–65536 (default 8192)
`wait_ms`	integer	1–10000

`write_process`

Sends input to a running process or closes its standard input.

Input	Type	Notes
`process_id`*	string
`data`	string	Max 128 KiB per write
`close_stdin`	boolean	Pipe mode only

`stop_process`

Interrupts a process gracefully or terminates it. Repeating the call after the process has stopped is safe.

Input	Type	Notes
`process_id`*	string
`mode`*	enum	`interrupt` (SIGINT-style) or `terminate`

`list_processes`

No inputs. Returns the agent’s active processes with their state, command label, and working directory.

When machines misbehave

Agents remain observable when machine state changes:

The machine disconnects — the agent can wait for it to reconnect or continue elsewhere. Retained output and process state remain available.
Output exceeds retention — read_process returns truncated: true when older output has been dropped. For large output, write it to a file and read only what you need.
The machine is deleted — its processes end and its binding is released.

Machines

These tools let an agent inspect its BYO and pool-backed machines, and create or delete pool-backed machines. Its config and machine or pool grants determine which machines it can use and how many pool-backed machines it can create.

`create_machine`

Creates a machine from an available pool. Specify machine_pool_name only when the config provides more than one pool.

`delete_machine`

Deletes a pool-backed machine. Requires machine_ref.

`list_machines` / `inspect_machine`

list_machines lists the agent’s BYO and pool-backed machines. inspect_machine shows whether a specific machine is ready to run commands; provide machine_ref when the agent has more than one. Results identify the machine’s source_kind and binding_kind; only pool bindings can be passed to delete_machine.

Integrations

`send_integration_message`

Sends a message to the agent’s current integration target, such as a Slack thread or DM. Requires text. For agents reached through an integration, only messages sent with this tool are visible there; ordinary model output remains in Omnara. This tool supports only always_allow.

`set_integration_target`

Changes where future integration messages and approval or question prompts are sent. Requires target_ref.

Skills

`skill`

Loads an attached skill. Requires its skill name. The tool returns the skill’s instructions and, when the agent has machines, installs its supporting files there.

Full inputs and defaults, live from your deployment: Get tool catalog.

Get started

Agents

Inputs & events

Tools

Machines

Organization

Integrations

Examples

Built-in tools

Web

`web_search`

`web_fetch`

Questions

`ask_question`

Commands

`run_command`

Picking a machine

Processes

`read_process`

`write_process`

`stop_process`

`list_processes`

When machines misbehave

Machines

`create_machine`

`delete_machine`

`list_machines` / `inspect_machine`

Integrations

`send_integration_message`

`set_integration_target`

Skills

`skill`

​Web

​web_search

​web_fetch

​Questions

​ask_question

​Commands

​run_command

​Picking a machine

​Processes

​read_process

​write_process

​stop_process

​list_processes

​When machines misbehave

​Machines

​create_machine

​delete_machine

​list_machines / inspect_machine

​Integrations

​send_integration_message

​set_integration_target

​Skills

​skill

Web

`web_search`

`web_fetch`

Questions

`ask_question`

Commands

`run_command`

Picking a machine

Processes

`read_process`

`write_process`

`stop_process`

`list_processes`

When machines misbehave

Machines

`create_machine`

`delete_machine`

`list_machines` / `inspect_machine`

Integrations

`send_integration_message`

`set_integration_target`

Skills

`skill`