Authentication
API key for authentication. Alternative to --api-key flag or stored credentials.export OMNARA_API_KEY="xxxxxxxxxxxxxxxxxxxx"
omnara
API Configuration
OMNARA_API_URL
string
default:"https://agent.omnara.com"
API server URL. Use for self-hosted instances.export OMNARA_API_URL="https://api.mycompany.com"
omnara
OMNARA_BASE_URL
string
default:"https://agent.omnara.com"
Alias for OMNARA_API_URL. Both work interchangeably.
Session Management
Pre-existing session ID to resume. Alternative to --agent-instance-id flag.export OMNARA_AGENT_INSTANCE_ID="abc-123-def-456"
omnara
Alias for OMNARA_AGENT_INSTANCE_ID. Used by some integrations.
OMNARA_AGENT_DISPLAY_NAME
Display name for the agent in dashboard. Alternative to --name flag.export OMNARA_AGENT_DISPLAY_NAME="Code Review Bot"
omnara
Default agent type name. Used for tracking in dashboard.
Relay Configuration
Disable WebSocket relay streaming. Set to 1 or true.export OMNARA_RELAY_DISABLED=1
omnara # Runs in local-only mode
Custom relay WebSocket URL.Defaults:
- Production:
wss://relay.omnara.com/agent
- Local dev:
ws://localhost:8080/agent
export OMNARA_RELAY_URL="wss://relay.mycompany.com/agent"
omnara
OMNARA_RELAY_WS_SKIP_VERIFY
Skip SSL verification for relay WebSocket. Use for self-signed certificates.export OMNARA_RELAY_WS_SKIP_VERIFY=1
omnara
Agent-Specific
Path to Codex binary. Overrides packaged binary.export OMNARA_CODEX_PATH="/usr/local/bin/codex"
omnara --agent codex
Priority Order
Environment variables are evaluated in this priority:
- Command-line flags (highest priority)
- Environment variables
- Configuration files (
~/.omnara/credentials.json, ~/.omnara/config.json)
- Defaults
Example Priority
# All three methods set the API key:
export OMNARA_API_KEY="env_key" # Priority 2
# credentials.json contains "file_key" # Priority 3
omnara --api-key "flag_key" # Priority 1 (wins)
flag_key is used because command-line flags have highest priority.
Common Patterns
Development Environment
# Development environment
export OMNARA_API_URL="http://localhost:8000"
export OMNARA_RELAY_URL="ws://localhost:8080/agent"
export OMNARA_RELAY_WS_SKIP_VERIFY=1
CI/CD Pipeline
# GitHub Actions, GitLab CI, etc.
export OMNARA_API_KEY="${{ secrets.OMNARA_API_KEY }}"
export OMNARA_AGENT_DISPLAY_NAME="CI Bot - PR #${PR_NUMBER}"
export OMNARA_RELAY_DISABLED=1 # No terminal streaming needed
omnara headless --permission-mode bypassPermissions --prompt "Fix linting errors"
Multi-Agent Setup
# Terminal 1: Code Review Agent
export OMNARA_AGENT_DISPLAY_NAME="Code Reviewer"
omnara --agent codex
# Terminal 2: Testing Agent
export OMNARA_AGENT_DISPLAY_NAME="Test Runner"
omnara --agent claude
Self-Hosted Instance
# Point to self-hosted Omnara
export OMNARA_API_URL="https://omnara.mycompany.com"
export OMNARA_RELAY_URL="wss://relay.mycompany.com/agent"
omnara
Verification
Check which environment variables are set:
# Check all Omnara env vars
env | grep OMNARA
# Check specific var
echo $OMNARA_API_KEY