npm package: 4runr-os
Description: 4Runr AI Agent OS - Secure terminal interface for AI agents. v2.9.120: Gateway verify (/health+/ready); gateway status; TUI verified log. ⚠️ Pre-MVP / Development Phase
Author: 4Runr Team
Latest version: 2.9.120

# 4Runr OS

<div align="center">

![4Runr OS](https://img.shields.io/npm/v/4runr-os?style=for-the-badge)
![License](https://img.shields.io/npm/l/4runr-os?style=for-the-badge)
![Node](https://img.shields.io/node/v/4runr-os?style=for-the-badge)

**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](#-installation) • [Features](#-features) • [Documentation](#-documentation) • [Support](#-support)

</div>

---

## ⚠️ 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:

```bash
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](./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

![4Runr OS Boot Screen](https://github.com/KyanBergeron4Runr/4Runr-AI-Agent-OS/raw/master/packages/os-cli/images/screenshot-boot.png)

*Initialization screen showing system startup and readiness status.*

### Main Interface

![4Runr OS Terminal Interface](https://github.com/KyanBergeron4Runr/4Runr-AI-Agent-OS/raw/master/packages/os-cli/images/screenshot.png)

*Full terminal interface showing system status, operations log, resources, and capabilities.*

---

## 🚀 Quick Start

### Installation

```bash
npm install -g 4runr-os
```

### Usage

```bash
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:

```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
```

### Environment Variables

```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
```

### 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](./SETUP.md)** - Detailed setup instructions and troubleshooting
- **[User Privacy](./USER-PRIVACY.md)** - Privacy policy and data handling
- **[Easy Usage](./EASY-USAGE.md)** - Quick reference guide
- **[Contributing](./CONTRIBUTING-CLI.md)** - How to contribute to the project

---

## 🔧 Troubleshooting

### "mk3-tui binary not found"

The package will try to auto-install it. If that fails:

```bash
npm install -g 4runr-os-mk3
```

### "4r: command not found"

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
```

### 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:

```bash
# 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](https://github.com/KyanBergeron4Runr/4Runr-AI-Agent-OS/issues)
- **Documentation**: [Full Documentation](./SETUP.md)
- **Website**: [4Runr.com](https://4runr.com)

---

## 📄 License

MIT License - see [LICENSE](../LICENSE) file for details.

---

## 🙏 Acknowledgments

Built with:
- [Ratatui](https://github.com/ratatui-org/ratatui) - Terminal UI library
- [Rust](https://www.rust-lang.org/) - Systems programming language
- [Node.js](https://nodejs.org/) - JavaScript runtime

---

<div align="center">

**Made with ❤️ by the 4Runr Team**

[⬆ Back to Top](#4runr-os)

</div>