Configs & profiles

An agent config is a YAML or JSON document that defines the agent’s instruction, model, tools, permissions, and machines. Configs are immutable: changing the definition creates a new config ID (acfg_…). Submitting the same definition again returns the same ID. YAML and JSON configs refer to model providers, configured models, BYO machines, and machine pools by their human-readable names. When a config is created, Omnara resolves those names and stores the resources’ immutable IDs in the compiled config. Renaming a resource therefore does not change an existing config or an agent already using it. Recompiling saved source resolves its names again against the current resources, so an old name may stop resolving or may resolve to a different resource if that name has since been reused. Provider names are unique within an organization, model names within a provider, and BYO machine and machine-pool names within an organization. Machine and pool resolution also requires the project to have access to the selected resource. The example below includes every major section. If you are creating your first agent, start with the smaller config in the Quickstart.

version: v1
instruction: |
  Help engineers investigate issues in the acme/api repository.
  Run read-only commands freely; ask before anything destructive.
model:
  provider_config: openai-prod
  name: gpt-5.6
  reasoning:
    effort: high
tools:
  web_search: {}
  ask_question: {}
  run_command:
    permission:
      mode: always_ask
  write_process: {}
  read_process: {}
  stop_process: {}
  list_processes: {}
  list_machines: {}
  inspect_machine: {}
  create_ticket:
    type: custom
    description: File a ticket in our internal tracker.
    input_schema:
      type: object
      properties:
        title: { type: string }
        body: { type: string }
      required: [title]
mcp:
  linear:
    url: https://mcp.linear.app/mcp
    auth:
      type: oauth
      secret_id: sec_gik7mv4qtrwz3jehcyd5n6a2bf
machine_sources:
  - machine_pool_name: default-pool
    cwd: /workspace
skills:
  - skl_ik7mv4qtrwz3jehcyd5n6a2bfg

Instruction and identity

Field	Required	Notes
`version`	no	Only `v1` today; include it for forward compatibility.
`instruction`	yes	The system-level brief. This is the single highest-leverage field you control — be specific about the job, the boundaries, and when to ask a human.

Model

model selects a model configured in Omnara. provider_config is the name of a model provider, and name must exactly match one of its configured models. The model must also be available to the project.

model:
  provider_config: openai-prod
  name: gpt-5.6
  cache_retention: short
  reasoning:
    effort: high

Most agents can use the configured model’s defaults. Override these fields only when needed:

Field	What it does
`context_window_tokens`	Cap the effective context window below the model’s maximum.
`default_max_output_tokens`	Per-request output-token cap sent to the provider.
`cache_retention`	Prompt-cache preference: `none`, `short`, or `long`.
`reasoning.effort`	Reasoning effort for models that support it (for example `low`, `medium`, `high`).

Tools

Add a tool under tools: to make it available to the agent. Use {} to accept its defaults. You can add built-in tools that Omnara runs or custom tools that your own system runs. MCP tools are configured separately.

Built-in tools

Enable a built-in tool by name. The Built-in tools page explains the available tools and their inputs. You can also change a tool’s default permission:

tools:
  web_search: {}                # enabled, default permission
  run_command:
    permission:
      mode: always_ask          # a human approves every command
  delete_machine:
    enabled: false              # explicitly off

Permission modes decide whether a tool runs immediately, asks a person first, or is denied. See Tools & permissions for defaults and supported modes.

Custom tools

A custom tool describes an operation that your system performs. Its description tells the model when to use it, and its input_schema defines the arguments. The full example above defines create_ticket as a custom tool. When the agent calls it, Omnara waits for your system to submit the result. Custom tools walks through that workflow.

MCP servers

mcp connects the agent to Model Context Protocol servers. Each entry sets the server URL, authentication, and permissions. auth.secret_id points to the secret required by the selected authentication type. MCP servers explains the full setup.

Machines

machine_sources provides execution environments for tools such as run_command. Use a machine you connected yourself or let Omnara create one from a pool:

machine_sources:
  - machine_name: build-server-1     # a specific BYO machine…
    cwd: /srv/repo
    env_overlay:
      CI: "true"
    secret_env_overlay:
      GITHUB_TOKEN: sec_7jehcyd5n6a2bfgik7mv4qtrwz
  - machine_pool_name: default-pool  # …or capacity from a pool
    machine_memory_mb: 4096
    max_machines: 3

env_overlay sets environment variables. secret_env_overlay references secrets, whose values are resolved when they are injected. Both apply to every process the agent runs on the machine; for pool sources they also apply to the machine environment at provisioning, so the pool’s startup script sees them. Pool sources can also set machine size and limits; supported fields vary by provider. See Machine pools and the config schema. Environment names beginning with OMNARA_ are reserved case-insensitively and cannot be set through agent or machine configuration. Agent processes receive OMNARA_HOME from the daemon as the location for Omnara-managed files.

Skills

skills attaches reusable instructions and files that the agent can load with the skill tool. The project must own or hold a grant for each referenced skill.

Create a config

API
Dashboard

The examples assume the client, $ORG/orgID, and $PROJ/projectID setup from the quickstart.POST /agent-configs returns 201 for a new config or 200 with the existing config when the same definition was already created. The CLI has no separate config step: pass the config to the command that uses it — --file takes a .yaml, .yml, or .json file, --source takes inline YAML or JSON, and --config references an existing acfg_… ID.

omnara agents launch --file agent.yaml --message "Get started."
omnara profiles create --name "Support triage" --file agent.yaml

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

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' },
})
console.log(config.data.id)

The response includes the config ID and final model settings after config overrides and project limits are applied. The CLI uploads the config first, reusing the existing ID when the same definition was already created. Validation errors identify the field that needs to be fixed.

Full schema and playground: Create agent config · Get agent config.

Profiles

A profile gives a config a stable name, such as Support triage. Launching from that profile uses the config it currently points to. Updating a profile points it to a new immutable config. Future launches use the new config; existing agents keep the config they already use. Previous versions remain available in the profile’s history.

Create a profile

API
Dashboard

Point a name at an existing config:

omnara profiles create --name "Support triage" --config acfg_mv4qtrwz3jehcyd5n6a2bfgik7

curl "$OMNARA_API/orgs/$ORG/projects/$PROJ/agent-profiles" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support triage",
    "config": "acfg_mv4qtrwz3jehcyd5n6a2bfgik7"
  }'

const profile = await sdk.createAgentProfile({
  client,
  path: { orgID, projectID },
  body: {
    name: 'Support triage',
    config: 'acfg_mv4qtrwz3jehcyd5n6a2bfgik7',
  },
})

The response starts with current_generation: 1; the generation increases each time the profile moves to a new config. With the CLI, pass --file agent.yaml instead of --config to create the config and the profile in one step.

Full schema and playground: Create agent profile.

Advance a profile to a new config

API
Dashboard

With the REST API and the SDK, create the new config first, then update the profile, sending expected_current_config_id so the request fails with 409 if someone changed the profile after you read it. One CLI command does all of that — it creates the new config, reads the profile’s current config, and points the profile at the new one:

omnara profiles update aprf_3jehcyd5n6a2bfgik7mv4qtrwz --file agent.yaml

curl "$OMNARA_API/orgs/$ORG/projects/$PROJ/agent-profiles/aprf_3jehcyd5n6a2bfgik7mv4qtrwz/config" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": "acfg_n6a2bfgik7mv4qtrwz3jehcyd5",
    "expected_current_config_id": "acfg_mv4qtrwz3jehcyd5n6a2bfgik7"
  }'

await sdk.updateAgentProfile({
  client,
  path: { orgID, projectID, agentProfileID: 'aprf_3jehcyd5n6a2bfgik7mv4qtrwz' },
  body: {
    config: 'acfg_n6a2bfgik7mv4qtrwz3jehcyd5',
    expected_current_config_id: 'acfg_mv4qtrwz3jehcyd5n6a2bfgik7',
  },
})

With the CLI, pass --expected-current-config-id acfg_… to pin the expected version yourself.

Full schema and playground: Update agent profile.

Use or delete a profile

To launch from a profile, select it under New agent, pass --profile to omnara agents launch, or pass profile and config to the API. See Launch an agent. Deleting a profile removes the profile and its version history, but agents launched from it keep running. In the dashboard, open the profile’s row menu and click Delete, or run omnara profiles delete {agent-profile-id}. An active integration that uses the profile must be removed first. See Delete agent profile.

Agents

Launch agents from the config you just created

Tools & permissions

Control which tools agents can use and which calls need approval

Get started

Agents

Inputs & events

Tools

Machines

Organization

Integrations

Examples

Configs & profiles

Instruction and identity

Model

Tools

Built-in tools

Custom tools

MCP servers

Machines

Skills

Create a config

Profiles

Create a profile

Advance a profile to a new config

Use or delete a profile

Next

Agents

Tools & permissions

​Instruction and identity

​Model

​Tools

​Built-in tools

​Custom tools

​MCP servers

​Machines

​Skills

​Create a config

​Profiles

​Create a profile

​Advance a profile to a new config

​Use or delete a profile

​Next

Agents

Tools & permissions

Instruction and identity

Model

Tools

Built-in tools

Custom tools

MCP servers

Machines

Skills

Create a config

Profiles

Create a profile

Advance a profile to a new config

Use or delete a profile

Next