Skip to main content

​
Usage

omnara terminal [OPTIONS] [AGENT_FLAGS]
Starts an AI coding agent with WebSocket relay streaming enabled. Agent Flag Pass-through: Any flags specific to your chosen agent (Claude Code, Codex, Amp) are automatically passed to the underlying agent CLI. This allows you to use native agent features while maintaining Omnara integration.

​
Options

All options from the default command are supported:
​
--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
​
--agent-instance-id
string
Resume an existing session
​
--relay-url
string
Custom relay WebSocket URLDefaults:
  • Production: wss://relay.omnara.com/agent
  • Local dev: ws://localhost:8080/agent
​
--base-url
string
default:"https://agent.omnara.com"
Omnara API server URL
Agent Flag Compatibility: All agent-specific CLI flags are passed through to the underlying agent:
  • Claude Code: --continue, --permission-mode, --allowed-tools, --dangerously-skip-permissions, etc.
  • Codex: Any Codex-specific flags
  • Amp: Any Amp-specific flags
This preserves full agent functionality while adding Omnara’s dashboard integration.

​
Examples

# Start with relay streaming (explicit)
omnara terminal
Examples of agent flags:
  • Claude Code: --continue, --permission-mode, --allowed-tools, --disallowed-tools, --dangerously-skip-permissions
  • Codex: Any Codex-specific configuration flags
  • Amp: Any Amp-specific configuration flags
All agent flags are automatically passed through to maintain full native functionality.

​
What is WebSocket Relay?

The relay system streams your terminal I/O in real-time to the Omnara dashboard, enabling:
  • Live Terminal Viewing: See exactly what’s happening in the terminal from web/mobile
  • Remote Input: Type messages from the dashboard that appear in the terminal
  • Session Sharing: Share terminal sessions with teammates
  • Multi-device Access: Monitor from phone, control from laptop

​
How It Works

1

Agent Registration

CLI registers the agent instance with Omnara API
2

WebSocket Connection

Connects to relay server at configured URL with API key authentication
3

PTY Creation

Creates a pseudo-terminal (PTY) and launches the agent
4

Bidirectional Streaming

Streams terminal I/O over WebSocket:
  • Terminal → Dashboard: Real-time output display
  • Dashboard → Terminal: User input from web/mobile
5

Session Persistence

Terminal history buffered and replayed when viewing from new devices

​
Relay vs Local-Only

  • With Relay (terminal)
  • Without Relay (--no-relay)
omnara terminal
# or simply: omnara
Features:
  • ✓ Real-time terminal streaming
  • ✓ Dashboard shows live terminal output
  • ✓ Input from web/mobile
  • ✓ Session sharing
  • ✓ Multi-device monitoring
  • ✓ Message API active

​
Terminal Frame Protocol

The relay uses a binary frame protocol for efficient streaming:
Frame TypeIDPurpose
OUTPUT0Terminal output to dashboard
INPUT1User input from dashboard
RESIZE2Window resize events
METADATA3Agent metadata (type, name)
Frame Structure: 
[Type: 1 byte][Length: 4 bytes][Payload: variable]
This protocol ensures efficient, low-latency terminal streaming.

​
Special Features

​
History Replay

When you open the dashboard:
  • Buffered terminal history is replayed
  • Special handling for Codex (strips clear screen sequences)
  • Seamless catch-up to current state

​
Resize Handling

Terminal resizes are handled intelligently:
  • Debouncing: Waits 500ms before applying resize
  • Gradual Resizing: Step-by-step changes for large differences
  • Cursor Tracking: Detects and adjusts cursor position reports
Prevents display corruption in TUI applications.

​
Reconnection

If the WebSocket connection drops:
  • Automatic reconnection every 5 seconds
  • Session persists across reconnections
  • No data loss during disconnection

​
Relay Server Architecture

The relay server (relay.omnara.com):
  • Runs independently from API server
  • Handles WebSocket connections
  • Buffers terminal history
  • Routes messages between terminal and dashboard clients
  • Supports multiple simultaneous viewers

​
Security

​
Authentication

WebSocket connections authenticated via:
  • X-API-Key header
  • Authorization: Bearer {token} header
  • WebSocket subprotocol: omnara-key.{key} or omnara-supabase.{token}

​
Encryption

  • Production: WSS (WebSocket Secure) over TLS
  • All terminal data encrypted in transit
  • No terminal data stored long-term (only buffered in memory)

​
Access Control

  • Only authenticated users can view their own sessions
  • Session ownership validated on join
  • No cross-user session access

​
Use Cases

Remote Monitoring

Monitor agent progress from your phone while away from desk

Pair Programming

Share terminal session with teammate for collaboration

Debugging

Review terminal history to debug agent behavior

Multi-device Workflow

Start on laptop, monitor from phone, resume on desktop

​
Troubleshooting

Check:
  • Network/firewall allows WebSocket connections
  • API key is valid: omnara --auth
  • Relay URL is correct
Test manually:
# Try with custom relay URL
omnara terminal --relay-url wss://relay.omnara.com/agent
Causes:
  • Using --no-relay flag
  • WebSocket connection dropped
  • Dashboard not refreshed
Fix:
  1. Ensure not using --no-relay
  2. Check logs: ~/.omnara/<agent>_wrapper/<session-id>.log
  3. Refresh dashboard
Causes:
  • One-way connection only
  • Agent has exited or crashed
  • Relay server issues
Fix:
  • Check agent is still running in terminal
  • Try restarting the session
  • Check relay server status

omnara (default)

Same functionality, shorter command

omnara headless

Background mode without terminal