orcbot ui - OrcBot

Overview

The orcbot ui command launches an interactive TUI (Text User Interface) dashboard built with inquirer.js. It provides a visual, menu-driven interface for configuring the agent, managing skills, viewing memory, and controlling connections.

Usage

orcbot ui

No arguments or options are required. The command launches an interactive menu system.

Features

When you run orcbot ui, you see the OrcBot banner and main menu:

  ██████╗ ██████╗  ██████╗██████╗  ██████╗ ████████╗
 ██╔═══██╗██╔══██╗██╔════╝██╔══██╗██╔═══██╗╚══██╔══╝
 ██║   ██║██████╔╝██║     ██████╔╝██║   ██║   ██║   
 ██║   ██║██╔══██╗██║     ██╔══██╗██║   ██║   ██║   
 ╚██████╔╝██║  ██║╚██████╗██████╔╝╚██████╔╝   ██║   
  ╚═════╝ ╚═╝  ╚═╝ ╚═════╝╚═════╝  ╚═════╝    ╚═╝   

  Autonomous AI Agent Framework  │  v2.1.0
  by Frederick Abila  │  github.com/fredabila/orcbot
  ──────────────────────────────────────────────────

? Main Menu:
  ➕ Manage AI Models
  🔌 Manage Connections
  🧰 Tools Manager
  🌐 Web Gateway
  ⚙️  Configuration
  📊 View Status
  🧠 Memory Inspector
  🤖 Worker Processes
  ← Exit

Manage AI Models

Configure LLM providers and API keys:

OpenAI: Set openaiApiKey, configure model name
Google Gemini: Set geminiApiKey, configure Gemini model
AWS Bedrock: Configure Bedrock credentials
OpenRouter: Set openrouterApiKey for access to 200+ models
Ollama/Local: Configure local model endpoints

Visual key entry:

Masked input for API keys
Validation for key format
Test connection after setting

Manage Connections

Configure communication channels:

Set bot token (telegramToken)
Enable/disable Telegram channel
Test connection
View bot info (username, ID)

Enable WhatsApp via Baileys
QR code display for phone pairing
Connection status
Session management

Discord

Set bot token
Configure guild/server settings
Channel mappings

Email

IMAP/SMTP configuration
Inbox monitoring settings

Tools Manager

Comprehensive tools management interface:

╔════════════════════════════════════════╗
║ 🧰 TOOL INVENTORY                      ║
╠════════════════════════════════════════╣
║ Installed   25                         ║
║ Active      18                         ║
║ Approved    12                         ║
╚════════════════════════════════════════╝

? Tools Options:
  ➕ Install Tool
  ✅ Approve Tool
  ⚡ Activate / Deactivate Tool
  ▶️  Run Tool Command
  📖 Read Tool README
  🗑️  Uninstall Tool
  ──────────────────────────────────
  ← Back

Install Tool

Install tools from Git repos or local paths:

Git URL (GitHub, GitLab, Bitbucket)
Local directory path
Optional tool name
Optional subdirectory
Allowed commands (comma-separated or * for all)
Description

Example:

? Git URL or local path: https://github.com/user/cool-tool.git
? Optional tool name: cool-tool
? Optional subdir: 
? Allowed commands: start,stop,status
? Optional description: A cool automation tool

Approve Tool

Set allowed commands for installed tools:

Select tool from list
Enter comma-separated command whitelist
Or use * to allow all commands

Safety note: Approving a tool with * allows it to run any command in its directory.

Activate/Deactivate Tool

Toggle tool availability:

Active tools can be invoked by the agent
Inactive tools remain installed but unavailable
Useful for temporarily disabling tools

Run Tool Command

Manually execute tool commands:

? Select tool to run: my-tool
? Command to run: node
? Args: index.js --option=value
? Working dir: ./bin

Runs: node index.js --option=value in ~/.orcbot/plugins/tools/my-tool/bin/ Blocked in safe mode to prevent unauthorized execution.

Read Tool README

Display tool README.md in terminal:

? Select tool: my-tool

════════════════════════════════════════
                 my-tool
════════════════════════════════════════

A powerful automation tool for...

Features:
- Feature 1
- Feature 2

Usage:
  ./bin/mytool command [args]
...

Uninstall Tool

Remove tool completely:

? Select tool to uninstall: old-tool
? Uninstall "old-tool"? No

Confirmation required. Deletes tool directory from ~/.orcbot/plugins/tools/. Blocked in safe mode.

Web Gateway

Manage the web gateway server:

Start gateway
Stop gateway
Configure port (gatewayPort)
Configure host (gatewayHost)
Set API key (gatewayApiKey)
Configure static directory for dashboard
Tailscale setup guide and status checks

Tailscale Integration: The TUI now includes a guided flow for setting up Tailscale private networking:

Check if Tailscale is installed
Check if connected to Tailnet
Recommend security hardening (API key, ACLs)
Display Tailscale IP for remote access

Configuration

Direct config key editing:

View all config values
Edit specific keys
Type inference (boolean, number, string, JSON)
Hot-reload (no restart required)

Example:

? Config key to edit: modelName
? New value for modelName: gpt-4o
✅ Configuration updated: modelName = "gpt-4o"

View Status

Display current agent status:

╔════════════════════════════════════════════════════╗
║ 🤖 AGENT STATUS                                    ║
╠════════════════════════════════════════════════════╣
║ Running         ● ON                               ║
║ Model           gpt-4o                             ║
║ Memory          45 entries                         ║
║ Queue           3 pending                          ║
║ Autonomy        ● ON (30m interval)                ║
║ Safe Mode       ○ OFF                              ║
╚════════════════════════════════════════════════════╝

Includes:

Running status (with PID if daemon)
Current LLM model
Memory statistics
Action queue size
Autonomy settings
Safe mode status
Channel connections

Memory Inspector

Browse and search agent memory:

Short memory: Recent step observations
Episodic memory: LLM-summarized episodes
Long memory: MEMORY.md, LEARNING.md, USER.md, JOURNAL.md
Vector memory: Semantic search across embeddings

Search capabilities:

Keyword search
Semantic similarity search
Filter by memory type
Sort by timestamp
Export to file

Worker Processes

Manage multi-agent orchestration:

╔════════════════════════════════════════════════════╗
║ 🤖 WORKER PROCESSES                                ║
╠════════════════════════════════════════════════════╣
║ researcher-1     ● Running  PID: 12346             ║
║   Task: Analyze competitor pricing                 ║
║                                                     ║
║ scraper-2        ○ Stopped                         ║
║   Task: (none)                                     ║
╚════════════════════════════════════════════════════╝

? Worker Actions:
  ▶️  Start Worker
  ⏸️  Stop Worker
  🔄 Restart Worker
  ➕ Spawn New Worker
  🗑️  Terminate Worker
  ← Back

Worker lifecycle:

Spawn: Create new worker process with role and task
Start: Launch stopped worker
Stop: Gracefully stop running worker
Restart: Stop and start worker
Terminate: Permanently remove worker and its memory

Keyboard Controls

Navigation within the TUI:

Arrow keys: Move selection
Enter: Select menu item
Escape: Go back (in submenus)
Ctrl+C: Exit TUI entirely
Space: Toggle checkboxes (when applicable)

Visual Elements

ASCII art logo with gradient colors:

Bright cyan and magenta gradient
Version number
Author credit
GitHub link

Boxes

Decorated information boxes using pi-tui:

Double-line borders
Optional title
Configurable width and padding
Color-coded borders (cyan, magenta, red)

Status Indicators

● Green dot: Active/On/Running
○ Gray dot: Inactive/Off/Stopped
✅ Green checkmark: Success/Enabled
❌ Red X: Error/Disabled
⚠️ Yellow warning: Caution/Attention needed

Progress Bars

Visual capacity indicators:

████████████░░░░░░░░  60%

Green: Low usage (less than 50%)
Yellow: Medium usage (50-80%)
Red: High usage (greater than 80%)

Sparklines

Mini charts for trends:

▁▂▃▄▅▆▇█

Used for token usage, latency trends, etc.

Configuration via TUI

The TUI modifies ~/.orcbot/orcbot.config.yaml directly:

# Modified by TUI
openaiApiKey: sk-...
telegramToken: 123456:ABC...
gatewayPort: 3100
modelName: gpt-4o
autonomyEnabled: true

Changes are hot-reloaded (no restart required) via ConfigManager.

Safe Mode Protection

Certain TUI actions are blocked when safeMode: true:

Tool installation
Tool execution (Run Tool Command)
Tool uninstallation
Skill creation
Config changes to security-critical keys

Blocked action message:

🔒 Safe mode is enabled. Tool installation is disabled.

Examples

Set Up Telegram Bot

Run orcbot ui
Select “Manage Connections”
Select “Telegram”
Enter bot token (from @BotFather)
Enable Telegram
Test connection
View bot info

Install and Approve Tool

Run orcbot ui
Select “Tools Manager”
Select “Install Tool”
Enter Git URL: https://github.com/user/tool.git
Enter tool name: my-tool
Enter allowed commands: start,stop
Wait for installation
Select “Approve Tool”
Select my-tool
Confirm allowed commands

Check Worker Status

Run orcbot ui
Select “Worker Processes”
View active workers with PIDs
Select worker action (start/stop/restart)

Configure Gateway with Tailscale

Run orcbot ui
Select “Web Gateway”
Select “Tailscale Setup & Status Guide”
Follow guided checks
Install Tailscale if needed
Connect to Tailnet
Note Tailscale IP for remote access
Set gatewayApiKey for auth
Start gateway

Troubleshooting

TUI Won’t Launch: If orcbot ui crashes immediately:

# Check Node version (requires Node 16+)
node --version

# Reinstall dependencies
npm install

# Try running with debug output
DEBUG=* orcbot ui

Colors Not Displaying: If colors appear broken:

# Check terminal support
echo $TERM

# Try forcing color support
FORCE_COLOR=1 orcbot ui

# Or use a modern terminal (iTerm2, Windows Terminal, etc.)

Menu Not Responding: If arrow keys don’t work:

Ensure terminal is in raw mode (not running inside screen or tmux without proper config)
Try a different terminal emulator
Check for conflicting keyboard shortcuts

orcbot run - Start agent (controlled via TUI)
orcbot daemon - Daemon management (status shown in TUI)
orcbot push - Queue tasks (visible in TUI status)
orcbot gateway - Gateway server (managed via TUI)

​Overview

​Usage

​Features

​Main Menu

​Menu Options

​Manage AI Models

​Manage Connections

​Telegram

​WhatsApp

​Discord

​Email

​Tools Manager

​Install Tool

​Approve Tool

​Activate/Deactivate Tool

​Run Tool Command

​Read Tool README

​Uninstall Tool

​Web Gateway

​Configuration

​View Status

​Memory Inspector

​Worker Processes

​Keyboard Controls

​Visual Elements

​Banner

​Boxes

​Status Indicators

​Progress Bars

​Sparklines

​Configuration via TUI

​Safe Mode Protection

​Examples

​Set Up Telegram Bot

​Install and Approve Tool

​Check Worker Status

​Configure Gateway with Tailscale

​Troubleshooting

​Related Commands

​See Also

Overview

Usage

Features

Main Menu

Menu Options

Manage AI Models

Manage Connections

Telegram

WhatsApp

Discord

Email

Tools Manager

Install Tool

Approve Tool

Activate/Deactivate Tool

Run Tool Command

Read Tool README

Uninstall Tool

Web Gateway

Configuration

View Status

Memory Inspector

Worker Processes

Keyboard Controls

Visual Elements

Banner

Boxes

Status Indicators

Progress Bars

Sparklines

Configuration via TUI

Safe Mode Protection

Examples

Set Up Telegram Bot

Install and Approve Tool

Check Worker Status

Configure Gateway with Tailscale

Troubleshooting

Related Commands

See Also