Model providers

Omnara works with the model providers you choose. Before an agent can use a model, your organization connects the provider, configures the model, and grants it to the project: The organization owns the credentials and model settings. Projects receive access through grants, and agent configs reference the provider and model by name. The dashboard guides you through this chain. The CLI and API expose the same resources for automation; CLI examples assume you have run omnara login and omnara config select.

Connect a provider

API
Dashboard

The examples assume the client, $ORG/orgID, and $PROJ/projectID setup from the quickstart.Store the API key as a secret, then create a provider that references it. The preset supplies the endpoint, API format, and authentication settings:

npx omnara secrets create \
  --owner-kind org \
  --name openai-api-key \
  --material-kind generic \
  --material-value "sk-..."

curl "$OMNARA_API/orgs/$ORG/secrets" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": { "kind": "org" },
    "name": "openai-api-key",
    "material": { "kind": "generic", "value": "sk-..." }
  }'

const secret = await sdk.createSecret({
  client,
  path: { orgID },
  body: {
    owner: { kind: 'org' },
    name: 'openai-api-key',
    material: { kind: 'generic', value: 'sk-...' },
  },
})

Keep the returned id, then:

npx omnara model-providers create \
  --name openai-prod \
  --preset openai \
  --credential-secret-id sec_hcyd5n6a2bfgik7mv4qtrwz3je \
  --json

curl "$OMNARA_API/orgs/$ORG/model-provider-configs" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openai-prod",
    "preset": "openai",
    "credential_secret_id": "sec_hcyd5n6a2bfgik7mv4qtrwz3je"
  }'

const provider = await sdk.createModelProviderConfig({
  client,
  path: { orgID },
  body: {
    name: 'openai-prod',
    preset: 'openai',
    credential_secret_id: secret.data.id,
  },
})

{
  "config": {
    "id": "mpc_bfgik7mv4qtrwz3jehcyd5n6a2",
    "name": "openai-prod",
    "api_format": "openai-responses",
    "base_url": "https://api.openai.com/v1",
    "endpoint_path": "/responses",
    "credential_secret_id": "sec_hcyd5n6a2bfgik7mv4qtrwz3je",
    "...": "..."
  },
  "model_catalog": {
    "status": "ok",
    "models": [
      { "slug": "gpt-6-sol", "display_name": "GPT-6 Sol" }
    ]
  }
}

Presets are available for openai, anthropic, and openrouter. For a proxy, local vLLM server, or another compatible endpoint, set the API format, base URL, endpoint path, and authentication method yourself.Omnara fetches the provider’s model catalog when it creates the provider, and on demand with omnara model-providers catalog {model-provider-config-id}, GET …/model-provider-configs/{id}/model-catalog, or sdk.getModelCatalog. The catalog probe can fail without failing the request, which allows private or air-gapped endpoints. Check model_catalog.status; you can configure models manually if needed.A provider cannot be deleted while it still has configured models.

Open the provider dialog

With All projects selected in the project switcher, open Models and click New provider. Pick a provider and name the connection — this name (e.g. openai-prod) is what agent configs reference as model.provider_config.

Create the credential inline

In the API key field, click New secret, name it, paste the provider’s API key, and click Create secret. It’s stored as an organization secret (sec_…); the provider only ever holds the reference.

Add provider

Click Add provider. Omnara creates the provider and tries to discover its models. If discovery fails, the provider is still created and you can add models manually.

Provider timeouts apply to each attempt, including reasoning and response streaming:

request_timeout_ms sets the total deadline, defaulting to 3600000 (60 minutes).
idle_timeout_ms limits the wait for response headers or more response data, defaulting to 300000 (5 minutes). Heartbeats count as activity. Increase it for endpoints that can remain silent for longer periods.

Edit these settings in the provider dialog or through the API. Existing total deadlines are retained on upgrade. Use headers to send extra HTTP headers with every request to the provider, and secret_headers to take a header’s value from a secret; put keys and tokens in secret_headers. Set both in the provider dialog or through the API. If a referenced secret is deleted, requests omit that header.

Configure models

A configured model (mdl_…) gives a provider model a name and runtime settings. Agent configs use name; Omnara sends provider_model_slug to the provider. Keeping them separate lets you manage provider details centrally.

API
Dashboard

npx omnara models create mpc_bfgik7mv4qtrwz3jehcyd5n6a2 \
  --name "gpt-6-sol" \
  --provider-model-slug gpt-6-sol \
  --context-window-tokens 1050000 \
  --max-output-tokens 128000 \
  --supports-reasoning \
  --default-reasoning-effort medium \
  --default-cache-retention short \
  --json

curl "$OMNARA_API/orgs/$ORG/model-provider-configs/mpc_bfgik7mv4qtrwz3jehcyd5n6a2/models" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "gpt-6-sol",
    "provider_model_slug": "gpt-6-sol",
    "context_window_tokens": 1050000,
    "max_output_tokens": 128000,
    "supports_reasoning": true,
    "default_reasoning_effort": "medium",
    "default_cache_retention": "short"
  }'

const model = await sdk.createConfiguredModel({
  client,
  path: { orgID, modelProviderConfigID: 'mpc_bfgik7mv4qtrwz3jehcyd5n6a2' },
  body: {
    name: 'gpt-6-sol',
    provider_model_slug: 'gpt-6-sol',
    context_window_tokens: 1050000,
    max_output_tokens: 128000,
    supports_reasoning: true,
    default_reasoning_effort: 'medium',
    default_cache_retention: 'short',
  },
})

{
  "id": "mdl_fgik7mv4qtrwz3jehcyd5n6a2b",
  "name": "gpt-6-sol",
  "provider_model_slug": "gpt-6-sol",
  "context_window_tokens": 1050000,
  "supports_reasoning": true,
  "default_reasoning_effort": "medium",
  "current_revision_id": "mrev_gik7mv4qtrwz3jehcyd5n6a2bf",
  "...": "..."
}

Token settings have separate roles:

context_window_tokens is the shared input and output window.
max_output_tokens is the model’s output capacity. It is optional; selecting a discovered model can prefill it.
default_max_output_tokens is an optional output allowance for each request. When omitted, Omnara uses the known output capacity.

Omnara fits the request allowance to the remaining context. If both output settings are omitted, Messages uses 64,000 tokens; Chat Completions and Responses use the provider default. Set an explicit capacity or allowance for Messages endpoints that support less. Agents automatically continue after an output-limit cutoff. Changing a model’s runtime settings creates a new revision (mrev_…). Agents resolve the current revision before each model call, so the new settings apply to later calls from existing agents too.

Grant models to projects

A project needs a model grant (pmog_…) before its configs can use the model.

API
Dashboard

npx omnara grant models add --configured-model-id mdl_fgik7mv4qtrwz3jehcyd5n6a2b --json

curl "$OMNARA_API/orgs/$ORG/projects/$PROJ/model-grants" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"configured_model_id": "mdl_fgik7mv4qtrwz3jehcyd5n6a2b"}'

await sdk.createProjectModelGrant({
  client,
  path: { orgID, projectID },
  body: { configured_model_id: 'mdl_fgik7mv4qtrwz3jehcyd5n6a2b' },
})

{
  "grant": {
    "id": "pmog_ik7mv4qtrwz3jehcyd5n6a2bfg",
    "configured_model_id": "mdl_fgik7mv4qtrwz3jehcyd5n6a2b",
    "...": "..."
  }
}

A grant can apply stricter settings for one project, such as lower token limits, disabled reasoning, or fewer input and output types — set them when creating the grant (for example, with the CLI’s --max-output-tokens or --no-supports-reasoning flags). Settings you omit inherit from the configured model. omnara grant models list shows a project’s grants and omnara grant models delete {model-grant-id} revokes one.Revoking a grant prevents the project from creating new configs with that model. It does not change agents that already use it.

Use it from a config

With the chain complete, this config can now be created in the project:

model:
  provider_config: openai-prod
  name: gpt-6-sol

When you create the config, Omnara checks the provider, model, and project grant. If something is missing, the validation error tells you what to fix.

Full schema and playground: Create model provider config · Create configured model · Project model grants.

Get started

Examples

Agents

Inputs & events

Tools

Machines

Organization

Integrations

Model providers

Connect a provider

Configure models

Grant models to projects

Use it from a config

​Connect a provider

​Configure models

​Grant models to projects

​Use it from a config

Connect a provider

Configure models

Grant models to projects

Use it from a config