Configuration reference

Omnigent configuration controls the CLI, local server, harnesses, and managed sandboxes. These settings are separate from an agent's portable YAML spec and from the REST API.

Configuration scopes

Run omni config list to inspect the effective user and project configuration. Use omni config unset KEY or omni config unset --global KEY to remove a value from the corresponding scope.

Not every key is valid in every scope. Each setting below identifies its scope, type, default, and validation behavior.

Automatic session titles

Use natural-language instructions to control the format of session titles. These requirements apply both to titles generated from the first message in a session and to later agent-initiated renames through the sys_session_rename tool:

omni config set --global \
  'session_title_instructions=Prefix pull request titles with the PR number and use a short snake_case name.'

This setting belongs to the server, not an agent's portable instructions. It must use the global scope for a local server. On a deployed server, set the same key in the YAML passed to omni server --config:

session_title_instructions: |
  Prefix pull request titles with the PR number.
  Use a short snake_case name for other work.

The generator receives the current date as YYYY-MM-DD along with the first message. Default generated titles are limited to 100 characters; output beyond that limit is rejected in favor of the first-message fallback. When custom instructions are set, generated titles may use up to 200 characters and longer output is truncated with an ellipsis. Manually assigned titles also have a 200-character limit.

When an agent renames a session with sys_session_rename, its proposed title is formatted against these same requirements before the rename is applied. If that formatting fails, the existing title is preserved rather than replaced by an unformatted proposal. Without custom instructions, the agent's proposal is used as-is. Manually assigned titles are never reformatted.

The setting applies after the local server restarts, to both new-session titles and agent renames. An empty value removes the additional guidance. A non-string value or a string longer than 4,000 characters is ignored and the default title prompt is used.

Web UI base path

Serves the server and web UI under a path prefix behind a reverse proxy such as code-server's /proxy/<port>/ or an nginx location block. The web UI prefixes its API, SSE, WebSocket, and asset URLs, and the server accepts requests with or without the prefix, so prefix-stripping and non-rewriting proxies both work from one value. The flag is shorthand for the environment variable and wins over an inherited value.

"" and / are treated as unset. A missing leading slash is added and a trailing slash is removed. Values that start with //, contain characters outside letters, digits, and -._~/, include ./.. segments, or whose first segment collides with a reserved API namespace or a top-level web UI route are rejected at startup. For the full list of reserved segments, the auth variables to pair with it, and how the local managed server remembers the prefix, see Serving under a subpath.

Attachment limits

Uploads of ZIP archives, Office documents, and SQLite databases are admitted by filename extension and stored without extraction; the harness reads a local copy outside the working checkout (see Attach archives, Office documents, and databases). These formats require Claude Code (claude-native) or Codex (codex-native) and an execution host/runner that supports their delivery and restoration. The upload, copy, and fork routes apply the following limits to them:

filesystem_attachment_max_bytes: 26214400 # 25 MiB per file
filesystem_attachment_max_files: 10
filesystem_attachment_max_total_bytes: 104857600 # 100 MiB per session
filesystem_attachment_denied_extensions: [".zip", "db"] # leading dot optional

Denied-extension entries are matched case-insensitively, with or without the leading dot. Entries that are not non-empty strings are skipped with a warning; if the value is not a list, the whole setting is ignored. The denylist can only narrow the built-in allowlist, and it does not restrict files the agent creates or downloads through other tools.

These are filename-based admission and storage limits, not content inspection: the server does not identify file formats from their bytes, inspect archive entries, or detect renamed binary content. Images, PDFs, and text/code uploads keep their separate existing limits. The web composer also has a fixed 50 MiB ceiling for these formats, so raising filesystem_attachment_max_bytes above that has no effect for uploads made from the web UI.

Sandbox access. The runner writes attachment copies to ~/.omnigent/attachments/<session-key>/<filename> (or $OMNIGENT_DATA_DIR/attachments/ when overridden) on the execution host, and the harness receives that absolute path. Custom sandbox and provider configurations must let the runner write this cache and the harness's file-reading tools read it; permission to read the working directory does not cover attachments/. If the harness runs in a separate filesystem namespace, expose the session cache at the same absolute path. Scope any added access to the required cache rather than the whole data directory, which also contains credentials.

Request-phase custom policies receive the filename and content type of these attachments with an empty text value; their contents are not scanned as text.

Managed sandboxes

• Kubernetes sandbox configuration
• OS sandbox configuration
• Cloud sandbox configuration

Routing

• Smart Routing configuration