4Runr AI Agent OS - Secure terminal interface for AI agents. v2.2.0 includes encryption, SSRF protection, and integrity verification. Built with Rust + Ratatui. ⚠️ Pre-MVP / Development Phase
npm install 4runr-os~/.4runr/
bash
npm install -g 4runr-os
`
$3
`bash
4r
`
That's it! The terminal interface launches automatically.
---
✨ Features
$3
- Terminal Interface (TUI) - Rust + Ratatui high-performance native terminal UI
- Gateway Component - Built-in component for AI agent credentials and authentication
- Orchestration Layer - Node.js backend managing system operations and structure
- Real-time Updates - Live monitoring of agent runs, system resources, and network status
- Beautiful Design - Clean, professional interface with 4Runr brand colors
- Cross-platform - Works on Windows, macOS, and Linux
$3
- Shield System - PII detection, injection blocking, hallucination checks
- Sentinel Monitoring - Real-time safety monitoring and alerting
- Policy Enforcement - Configurable safety policies and controls
- Audit Logging - Complete audit trail of all operations
$3
- System Status - CPU, memory, network monitoring
- Agent Operations - Live log streaming and status updates
- Gateway Component Health - Internal gateway component status and metrics
- External Gateway Connections - Status of connections to external tools and services
- Resource Tracking - Active runs, connections, and capabilities
$3
- Automatic Updates - Checks for and installs new versions automatically
- Configurable - Enable/disable auto-updates via config command
- Zero Downtime - Updates happen seamlessly in the background
$3
- Zero Configuration - Works out of the box
- Pre-built Binaries - No Rust or build tools required
- Fast Startup - Optimized for quick launch times
- Comprehensive Logging - Detailed logs for debugging
---
📋 Commands
$3
| Command | Description |
|---------|-------------|
| 4r | Launch the 4Runr OS terminal interface (recommended) |
| 4runr | Alias for 4r |
| 4runr-os | Alias for 4r |
| 4runr-setup | Run initial setup wizard |
$3
Once the TUI is running, you can use these commands:
- help - Show all available commands
- config - Manage configuration settings
- status - Show system status
- agents - List available agents
- runs - View agent run history
- exit or Ctrl+C - Exit the terminal
---
⚙️ Configuration
$3
Control automatic updates from within the OS:
`bash
4r
Then in the terminal:
config auto-update disable # Disable automatic updates
config auto-update enable # Enable automatic updates
config auto-update status # Check current setting
`
$3
`bash
Disable auto-update (still checks for updates)
NO_AUTO_UPDATE=1 4r
Disable update check entirely
NO_UPDATE_CHECK=1 4r
Set gateway URL (REQUIRED - no default for security)
You must provide your own gateway URL - the package does not include any default server
GATEWAY_URL=http://your-gateway:3001 4r
Or connect via command
4r gateway connect http://your-gateway:3001
`
$3
Settings are saved in ~/.4runr/config.json and persist across sessions.
---
📦 Requirements
- Node.js 18.0.0 or higher
- npm (comes with Node.js)
No Rust or build tools needed! Pre-built binaries are included for:
- Windows (x64)
- macOS (x64, ARM64)
- Linux (x64, ARM64)
---
🏗️ Architecture
4Runr OS is a complete operating system that includes:
- Terminal Interface (TUI): Rust + Ratatui frontend - the user interface
- Gateway Component: Handles AI agent credentials and authentication (part of the OS)
- Orchestration Layer: Node.js backend managing system operations
- External Gateway Connections: Links to external tools and services (not local)
- Underlying Structure: Core OS components for monitoring, safety, and resource management
- Communication: HTTP/SSE for real-time updates between components
- Safety Systems: Built-in Shield and Sentinel systems
`
┌─────────────────────────────────────┐
│ 4Runr OS │
│ ┌───────────────────────────────┐ │
│ │ Terminal Interface (TUI) │ │ ← User Interface (Rust + Ratatui)
│ │ (Rust + Ratatui) │ │
│ └───────────┬───────────────────┘ │
│ │ │
│ ┌───────────▼───────────────────┐ │
│ │ Orchestration Layer │ │ ← System Management (Node.js)
│ │ (Node.js) │ │
│ └───────────┬───────────────────┘ │
│ │ │
│ ┌───────────▼───────────────────┐ │
│ │ Gateway Component │ │ ← AI Agent Credentials (OS Component)
│ │ (AI Agent Auth) │ │
│ └───────────┬───────────────────┘ │
│ │ │
│ ┌───────────▼───────────────────┐ │
│ │ External Gateway Connections │ │ ← External Tools & Services
│ │ (Non-local) │ │
│ └───────────────────────────────┘ │
└─────────────────────────────────────┘
`
Key Point: The gateway is a component of the OS (for AI agent credentials), separate from the gateway connections to external tools. The OS includes the TUI, gateway component, orchestration, and underlying structure - not just the interface.
---
📚 Documentation
- Setup Guide - Detailed setup instructions and troubleshooting
- User Privacy - Privacy policy and data handling
- Easy Usage - Quick reference guide
- Contributing - How to contribute to the project
---
🔧 Troubleshooting
$3
The package will try to auto-install it. If that fails:
`bash
npm install -g 4runr-os-mk3
`
$3
Make sure npm global bin is in your PATH:
`bash
Check PATH
echo $PATH | grep npm
Add to PATH if needed (add to ~/.bashrc or ~/.zshrc)
export PATH=$PATH:$(npm config get prefix)/bin
`
$3
The TUI requires a minimum terminal size of 80x24. Resize your terminal window.
$3
IMPORTANT: The package does NOT include any default gateway URL for security. You must configure your own:
`bash
Set gateway URL (required)
export GATEWAY_URL=http://your-gateway:3001
Test gateway connection
curl http://your-gateway:3001/health
Then run
4r
``