Built-in tools

Omnara includes built-in tools for common agent tasks. Add ordinary tools by name under tools: in the agent’s config. Integration tools use names such as int__engineering__post_message and the credentials of that project integration. 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`
Files	`list_files`, `upload_file`, `download_file`, `read_file`, `search_files`, `write_file`
Integrations	Integration-specific tools; `list_interaction_handlers`, `set_interaction_handler`
Skills	`skill`
Tool loading	`tool_search`

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_id`	string	Public ID (`mch_...`) of the machine 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_id chooses which attached machine runs the command:

With one available machine, omit machine_id.
With several, pass the public machine_id (mch_...) returned by list_machines.
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. Use list_machines to discover pools, then pass the selected machine_pool_id. You can omit the ID when only one pool is available. Pool names are for display; renaming a pool does not change which pool an ID selects. Optional cpu and memory_mb override the defaults where supported, within pool and project limits.

`delete_machine`

Deletes a pool-backed machine. Requires machine_id.

`list_machines` / `inspect_machine`

list_machines lists the agent’s BYO and pool-backed machines, plus pools from its config that have an active project grant. Pools are included even when they have no machines yet. Each pool includes its machine_pool_id, machine_pool_name, and configured description. Pools also expose supported resource overrides, effective defaults, and CPU/memory limits. inspect_machine shows whether a specific machine is ready to run commands; provide machine_id when the agent has more than one. Machine results include cpu and memory_mb when known, identify source_kind and binding_kind, and include machine_pool_id for pool-backed machines. Only pool bindings can be passed to delete_machine. When list_machines returns next_cursor, pass it as cursor in the next call to continue listing. Pools are listed first, followed by machines. If list_machines is disabled, provide the agent with any needed pool IDs, supported resource overrides, and limits in its instructions.

Files

path addresses files stored in Omnara, not files on an attached machine. /artifacts is the destination for creating an artifact, /artifacts/<artifact_id> identifies an existing artifact, and /memory/<store-name>/<file-path> identifies a file in an attached memory store. When compiling a config with enabled tools or MCP servers, Omnara adds missing list_files, read_file, and search_files entries to the compiled config, leaving the source unchanged. Attaching a memory store also adds these retrieval tools; a read_write attachment adds write_file. Explicit tool permissions and enabled: false settings take precedence. These tools do not require an attached machine. Integration-contributed tools are compiled with the config too.

`list_files`

Lists matching files and directories without reading their contents.

Input	Type	Notes
`pattern`*	string	Path pattern under literal `/memory` or `/artifacts`; globs are allowed only below the root
`limit`	integer	1–100; default 50
`cursor`	string	`next_cursor` from the previous result; keep the same pattern

Use /artifacts/* for the agent’s artifacts, /memory/* for attached stores and their descriptions, or /memory/** to list paths across attached stores recursively. For example, /memory/engineering/**/*.md finds Markdown files across directories. * matches within a path segment, ** spans directory levels, and ? matches one character. Artifact patterns such as /artifacts/*.pdf match filenames and return /artifacts/<artifact_id> paths for reading or downloading. An exact /artifacts/<artifact_id> selects one artifact; wildcards match filenames, not IDs, and a filename can match multiple artifacts. Artifacts are ordered newest first and include creation time and content type. Results include hidden entries. Continue with next_cursor until it is null; narrow the pattern if the listing exceeds its resource limit.

`upload_file`

Use upload_file to copy a file from an attached machine into Omnara. Uploads to /artifacts create artifacts, making files such as generated PDFs, images, or reports available for the user to view or download. Set path to /artifacts or /memory/<store-name>/<file-path> and pass the regular machine file’s relative, absolute, or ~-relative path as source; provide machine_id when the agent has more than one machine. Files may be up to 10 MiB. Artifacts must be non-empty; memory files may be empty. The upload process has a 30-second execution timeout. On success, an artifact appears in the conversation and the durable tool result contains its path, digest, and a media_ref that clients can use to display or download it. The returned path can be passed directly to download_file; source and destination refer to paths on the selected machine. The artifact’s contents are not added to later model context. To deliver artifacts through an integration, use its qualified posting tool, such as int__engineering__post_message, and follow its attachment schema. A memory upload requires write access and returns its path and digest. Omit expected_digest to create a file, or pass its current digest to replace changed content. On conflict, read or download the latest file and reapply your changes before retrying. Uploading identical contents succeeds without changing the file, even with a stale digest. Artifacts do not accept expected_digest.

`download_file`

Use download_file to copy a file stored in Omnara to an attached machine. Downloads support /artifacts/<artifact_id> and /memory/<store-name>/<file-path>; provide machine_id when the agent has more than one machine. Set path to the stored file’s path and destination to the exact machine file path. Relative and ~-relative destinations are supported, the parent directory must already exist, and an existing destination is replaced atomically. Downloads return the file’s digest on completion; use it when uploading an edited memory file. The download process has a 120-second execution timeout.

`read_file`

Reads a text or image file at /artifacts/<artifact_id> or /memory/<store-name>/<file-path>. Text must be UTF-8 without NUL bytes. Artifacts may be up to 48 MiB; memory files may be up to 10 MiB. Readability is determined from the file’s bytes, regardless of its declared content type. PNG, JPEG, GIF, and WebP images are returned for the model to view, with path, content_type, size_bytes, and digest instead of paging fields; paging inputs are still validated but don’t apply to images. Memory images are preserved as immutable artifacts when read and appear in the agent’s artifact listings.

Input	Type	Notes
`path`*	string	Exact artifact or memory file path
`offset_line`	integer	≥ 1; default 1
`limit_lines`	integer	1–200; default 100
`offset_char`	integer	≥ 0; default 0 in character mode; counts Unicode code points
`limit_chars`	integer	1–4096; default 512 in character mode
`expected_digest`	string	Optional digest precondition; use the first page’s digest when continuing a memory read. Unnecessary for immutable artifacts. A mismatch returns a conflict; restart the read.

Reading defaults to line mode. Supplying either character input selects character mode; do not combine line and character inputs. Each text response contains at most 4 KiB of file text, together with size_bytes, content_type, the whole-file digest, and has_more. When has_more is true, continue using the returned next_offset_line or next_offset_char. A line longer than one page returns its first chunk and a character offset; switch to character mode to continue. Reading past the end returns empty content with has_more: false.

`write_file`

Creates or edits a memory text file in a writable store attached with read_write access. Returns path and digest.

Input	Type	Notes
`path`*	string	Exact `/memory/<store-name>/<file-path>` destination
`content`	string	Text to create or replace the file with; empty text is allowed
`script`	string	GNU sed script using extended regex, at most 64 KiB; transforms an existing file
`append`	boolean	Append `content` exactly, without adding a newline; default false. Creates missing files.
`expected_digest`	string	Current digest when changing an existing file; omit to create

Supply exactly one of content or script; append only applies to content. Text must be UTF-8 without NUL bytes, at most 10 MiB. Scripts cannot read other files, write files, or run commands, and run with resource limits. Concurrent edits cause a conflict; read the file again before retrying.

`search_files`

Searches text in one artifact or in memory files matching a path or glob. Binary files may be skipped when searching with a glob.

Input	Type	Notes
`path`*	string	For artifacts, one exact `/artifacts/<artifact_id>` path. For memory, an exact file path or a glob such as `/memory/notes/*/.md`.
`args`*	string[]	Ripgrep options and `-e` patterns; for example `["-i", "-C", "2", "-e", "deploy"]`
`limit`	integer	1–100 entries across all files; default 20
`offset_line`	integer	Starting line, default 1; only for exact-file content searches

Supported options are -e (repeatable patterns), -F (literal), -i (ignore case), -w (whole word), -x (whole line), -v (invert), -U (multiline), -l (matching paths), -c (counts), and -A/-B/-C (0–5 context lines). Patterns total at most 1024 UTF-8 bytes. Other options and file operands are rejected. Content results are a sequence of match and context records with paths, original line numbers, and bounded snippets. Context does not count toward limit; counts in -c results are not capped by it. Context may be cut off at the response limit. Narrow the query when truncated.

Large tool results

For web_fetch, web_search, skill, MCP tools, and custom tools, results containing text or structured data trigger overflow handling when their serialized content exceeds 50 KiB. Omnara saves the oversized content as a text or JSON artifact and returns its path, a preview of up to 8 KiB, size_bytes, content_type, and truncated: true. Saved overflow artifacts are limited to 48 MiB. The overflow marker’s truncated field describes the shortened inline preview. In web_fetch metadata, truncated reports whether the upstream extractor shortened the fetched content; it can be false even when the overflow marker is true. For example, a large web_fetch result provides an /artifacts/<artifact_id> path. The agent can search that path for a phrase with search_files, then read the surrounding lines with read_file. Visible overflow artifacts also appear as downloadable attachments in the conversation. Hidden results remain hidden. Explicitly disabling both retrieval tools does not disable overflow handling. The agent still receives the preview and path, but cannot use these tools to retrieve the saved content. Existing media references remain inline so their attachments remain available to the model and clients. Consequently, 50 KiB is an overflow threshold, not a hard limit on the rewritten result: many retained media references can still exceed it. Media-only results are not offloaded.

Integration tools

Select integration tools by qualified name, such as int__engineering__post_message. An integration owns its credentials and defines its tools’ argument schemas and conversation requirements. Credential access, live integration state and ordinary permission govern execution. Ordinary model output remains in Omnara. Subscriptions control incoming forwarding independently of enabled tools. Manage them from the integration’s Conversations list or subscriptions API.

`list_interaction_handlers` / `set_interaction_handler`

Select these tools explicitly under tools, or use an integration launcher that supplies an interaction handler and adds them, preserving explicit tool settings. They are not global defaults. list_interaction_handlers accepts cursor and limit, returning handler keys, descriptions, eligible destinations and argument schemas. Its current selection is included independently of pagination. No eligible handlers means an empty list. set_interaction_handler takes a handler key and args matching its schema. An integration may infer the destination from its agent state; in that case its schema accepts empty arguments. Use {"handler":null,"args":{}} for dashboard only. Pass auto_select: false to pin the choice, or true to enable automatic selection; omitting it preserves the current mode. In automatic mode, the last eligible content input admitted to a turn selects its handler, or clears the choice if none applies. Dashboard and API messages therefore select dashboard-only delivery. Internal agent reports/messages and ordinary cron instructions preserve selection. An explicit integration origin takes precedence over that exception, including a scheduled integration thread’s initial input. Existing prompts keep their captured destination. Both tools report the current automatic-selection mode.

Subagents

These tools are added automatically when the config declares subagents. Each subagent is an ordinary agent with a parent_agent_id.

`spawn_agent`

Starts a subagent from a configured subagents key with a clean context. Requires agent (the key) and task; name is an optional display label. Returns immediately with the subagent’s agent_id, which the other subagent tools take. The subagent’s final answer arrives later as a message from it.

`read_agent`

Reads a subagent’s timeline by agent_id in the same shape as the turns API. Without turn_id it returns the newest turns first, each with its opening events and latest event; before_turn_sequence pages older turns and limit defaults to 10. With turn_id it returns that turn’s events, newest first; before_sequence pages older events and limit defaults to 20. Each result carries next_before_turn_sequence or next_before_sequence for the next page.

`send_agent_message`

Delivers message to the subagent identified by agent_id as a steering input. The subagent reads it once its current model call and tool batch finish, so running work is not stopped, but any open question or permission request is canceled. Parents cannot answer a subagent’s questions; those wait for a human. The reply arrives as a message from the subagent.

`stop_agent`

Cancels the current work of the subagent identified by agent_id and leaves it idle, so send_agent_message can resume it later. With archive: true it also archives the subagent and its descendants, after which it can no longer be messaged.

`list_agents`

Lists the agent’s subagents with their agent_id, name, key, state, and last activity.

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.

Tool loading

`tool_search`

Added automatically when any tool is deferred. Searches deferred tools by name, description, and argument names, and loads the matches so the model can call them.

Input	Type	Notes
`pattern`*	string	Case-insensitive regular expression, at most 200 characters
`max_results`	integer	1–50; default 5

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

​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

​Files

​list_files

​upload_file

​download_file

​read_file

​write_file

​search_files

​Large tool results

​Integration tools

​list_interaction_handlers / set_interaction_handler

​Subagents

​spawn_agent

​read_agent

​send_agent_message

​stop_agent

​list_agents

​Skills

​skill

​Tool loading

​tool_search

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`

Files

`list_files`

`upload_file`

`download_file`

`read_file`

`write_file`

`search_files`

Large tool results

Integration tools

`list_interaction_handlers` / `set_interaction_handler`

Subagents

`spawn_agent`

`read_agent`

`send_agent_message`

`stop_agent`

`list_agents`

Skills

`skill`

Tool loading

`tool_search`