Skip to main content

​
Usage

omnara [OPTIONS]
Starts an AI coding agent with full terminal integration and dashboard sync. Everything you do in the terminal is streamed to your web and mobile dashboard in real-time.

​
Options

​
--agent
string
default:"claude"
Choose which agent to use: claude, codex, or amp
​
--name
string
Custom display name for the dashboard
​
--api-key
string
API key for authentication (can also use OMNARA_API_KEY environment variable)
​
--no-relay
boolean
Disable WebSocket streaming (local-only session without dashboard sync)
​
--agent-instance-id
string
Resume an existing session by providing its instance ID
​
--base-url
string
default:"https://agent.omnara.com"
Omnara API server URL (for self-hosted instances)

​
Examples

# Start Claude Code (default agent)
omnara

​
How It Works

  1. Authentication: On first run, opens browser for authentication. API key saved to ~/.omnara/credentials.json
  2. Agent Launch: Starts the selected agent (Claude Code, Codex, or Amp) with environment configuration
  3. Terminal Integration: Captures all terminal I/O using a PTY (pseudo-terminal)
  4. WebSocket Streaming: Streams terminal content to relay server for real-time dashboard sync
  5. Two-way Communication: Messages from dashboard are sent back to the agent

​
Supported Agents

  • Claude Code
  • Codex
  • Amp
Anthropic’s Claude Code CLI with full integration:
  • Permission prompt forwarding to dashboard
  • Git diff tracking
  • Session log parsing
  • JSONL message streaming

​
Configuration

Set a default agent to avoid specifying --agent every time: 
omnara --set-default codex
This saves your preference to ~/.omnara/config.json.

Agent Configuration

Learn more about agent configuration

​
Troubleshooting

Try re-authenticating:
omnara --reauth
Ensure the agent CLI is installed:
  • Claude Code: claude --version
  • Codex: Packaged with Omnara
  • Amp: amp --version
Check WebSocket connection:
  • Verify --no-relay is not set
  • Check firewall/proxy settings
  • Try --relay-url wss://relay.omnara.com/agent

omnara headless

Run without terminal UI

omnara serve

Remote triggering via webhook