> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcbot.buzzchat.site/llms.txt
> Use this file to discover all available pages before exploring further.
# orcbot ui
> Interactive terminal UI dashboard for managing OrcBot agent, skills, memory, and connections
## 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
```bash theme={null}
orcbot ui
```
No arguments or options are required. The command launches an interactive menu system.
## Features
### Main Menu
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
```
## Menu Options
### 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
### Banner
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:
```yaml theme={null}
# 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:
```bash theme={null}
# 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:
```bash theme={null}
# 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
## Related Commands
* [`orcbot run`](/api/cli/run) - Start agent (controlled via TUI)
* [`orcbot daemon`](/api/cli/daemon) - Daemon management (status shown in TUI)
* [`orcbot push`](/api/cli/push) - Queue tasks (visible in TUI status)
* [`orcbot gateway`](/api/cli/gateway) - Gateway server (managed via TUI)
## See Also
* [Interactive Setup Wizard](https://fredabila.github.io/orcbot/docs/) - Initial configuration via `orcbot setup`
* [Config Management](https://fredabila.github.io/orcbot/docs/) - Programmatic config access
* [Skills Documentation](https://fredabila.github.io/orcbot/docs/) - Available agent capabilities