Skip to main content

​
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:

​
Telegram

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

​
WhatsApp

  • 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:
  1. Check if Tailscale is installed
  2. Check if connected to Tailnet
  3. Recommend security hardening (API key, ACLs)
  4. 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

  1. Run orcbot ui
  2. Select “Manage Connections”
  3. Select “Telegram”
  4. Enter bot token (from @BotFather)
  5. Enable Telegram
  6. Test connection
  7. View bot info

​
Install and Approve Tool

  1. Run orcbot ui
  2. Select “Tools Manager”
  3. Select “Install Tool”
  4. Enter Git URL: https://github.com/user/tool.git
  5. Enter tool name: my-tool
  6. Enter allowed commands: start,stop
  7. Wait for installation
  8. Select “Approve Tool”
  9. Select my-tool
  10. Confirm allowed commands

​
Check Worker Status

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

​
Configure Gateway with Tailscale

  1. Run orcbot ui
  2. Select “Web Gateway”
  3. Select “Tailscale Setup & Status Guide”
  4. Follow guided checks
  5. Install Tailscale if needed
  6. Connect to Tailnet
  7. Note Tailscale IP for remote access
  8. Set gatewayApiKey for auth
  9. 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

​
See Also