4Runr OS

Complete operating system for AI agents - includes terminal interface (TUI), gateway component for AI agent credentials, underlying orchestration structure, and connections to external tools.

Installation • Features • Documentation • Support

⚠️ Work in Progress

This package is currently in active development and is NOT in MVP (Minimum Viable Product) state.

• Features are being actively developed and may change
• Some functionality may be incomplete or experimental
• Breaking changes may occur between versions
• Not recommended for production use at this time

Status: Pre-MVP / Development Phase

Monorepo development

If you are working inside the 4Runr-AI-Agent-OS repo: Gateway and MK3 TUI source live under apps/gateway and apps/mk3-tui. The copies under packages/os-cli/apps/gateway and packages/os-cli/mk3-tui are for the npm package. After editing the apps, run:

cd packages/os-cli
npm run sync:vendored

See docs/CANONICAL-SOURCES.md (repo root) for the full rule.

🔒 Security Notice

Version 2.2.0+ includes comprehensive security protections:

✅ Fixed (v2.2.0):

• Command injection protection
• SSRF (Server-Side Request Forgery) protection
• Encrypted storage (AES-256-GCM) for all sensitive data
• JSON schema validation
• Package integrity verification

✅ Fixed (v2.1.56):

• Arbitrary code execution (tool testing disabled)
• Path traversal attacks (username validation)
• Insecure file permissions

Still pre-MVP - Use with caution:

• ⚠️ Do not use in production environments
• ⚠️ Do not run with administrator/root privileges
• ⚠️ Do not connect to untrusted gateways

What's protected:

• ✅ Configuration files encrypted in ~/.4runr/
• ✅ Session tokens encrypted
• ✅ Private IP addresses blocked
• ✅ Package updates verified for integrity

See SECURITY-FIXES-2.2.0.md for complete details.

📸 Screenshots

Note: Screenshots are hosted on GitHub. If images don't display, they may need to be pushed to the repository.

Boot Screen

Initialization screen showing system startup and readiness status.

Main Interface

Full terminal interface showing system status, operations log, resources, and capabilities.

🚀 Quick Start

Installation

npm install -g 4runr-os

Usage

4r

That's it! The terminal interface launches automatically.

✨ Features

🎨 Complete Operating System

• 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

🔒 Enterprise Safety Features

• 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

📊 Real-time Monitoring

• 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

🔄 Auto-Update System

• 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

🛠️ Developer Experience

• 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

Global Commands

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

In-Terminal Commands

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

Auto-Update Settings

Control automatic updates from within the OS:

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

Environment Variables

# 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

Configuration File

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

"mk3-tui binary not found"

The package will try to auto-install it. If that fails:

npm install -g 4runr-os-mk3

"4r: command not found"

Make sure npm global bin is in your PATH:

# Check PATH
echo $PATH | grep npm

# Add to PATH if needed (add to ~/.bashrc or ~/.zshrc)
export PATH=$PATH:$(npm config get prefix)/bin

Terminal too small

The TUI requires a minimum terminal size of 80x24. Resize your terminal window.

Connection issues

IMPORTANT: The package does NOT include any default gateway URL for security. You must configure your own:

# Set gateway URL (required)
export GATEWAY_URL=http://your-gateway:3001

# Test gateway connection
curl http://your-gateway:3001/health

# Then run
4r

Security Note: No server URLs, IP addresses, or credentials are included in the package. Users must configure their own gateway connection.

🤝 Support

• Issues: GitHub Issues
• Documentation: Full Documentation
• Website: 4Runr.com

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built with:

• Ratatui - Terminal UI library
• Rust - Systems programming language
• Node.js - JavaScript runtime

Made with ❤️ by the 4Runr Team

⬆ Back to Top