OS AI Agent

Intelligent system administration, software engineering, and network management — all in one terminal agent.

Copyright © 2026 OLOJEDE Samuel. All rights reserved. PRIVATE SOFTWARE.

Overview

OS AI Agent is a terminal-based AI assistant that operates across four specialized modes. It connects to 30+ LLM providers, manages SSH devices, executes local and remote commands, and provides a rich interactive terminal experience.

Modes

| Mode | Purpose | |------|---------| | GENERAL | System administration, file operations, command execution, web tools, and file generation (PDF, DOCX, PPTX, XLSX via Python venv — isolated and safe) | | CODING | Software engineering with full Git integration and code editing | | NETWORK | Remote network device management via SSH (Cisco, MikroTik, pfSense, Juniper) | | SSH | Live remote execution on a single Linux or Windows machine |

Execution sub-modes: PLAN (read-only, no modifications) and EXEC (full execution).

Screenshots

Welcome screen with logo and available commands

Interactive agent session in the terminal

Slash command menu for mode switching and actions

Quick Start

# Global installation
npm install -g osai-agent

# Register and log in (server-managed mode)
osai-agent register
osai-agent login
osai-agent run

# Run locally with your own LLM API key
osai-agent run --local

# Software engineering mode
osai-agent run --coding

# Connect to a remote device
osai-agent connect

File Generation

The GENERAL mode can generate PDF, DOCX, PPTX, and XLSX files on demand. Simply describe the document you need:

osai-agent run
# Then ask: "Generate a PDF invoice" or "Create a PowerPoint presentation"
# or: "Export this data as an Excel spreadsheet"

Python 3 is required. The agent automatically creates an isolated virtual environment (venv) so all dependencies are installed safely without affecting your system Python.

From source

git clone <repository-url>
cd osai-agent
npm install
node src/index.js run --local

CLI Reference

Run & Connect

osai-agent run                         Start in GENERAL mode (server)
osai-agent run --local                 Start locally (BYOK)
osai-agent run --coding                Start in CODING mode
osai-agent run --local --coding        CODING mode locally
osai-agent run <session-id>            Resume a past session
osai-agent connect                     Connect to an SSH-managed device

Authentication

osai-agent register                    Create an account
osai-agent login                       Authenticate with the server
osai-agent logout                      Clear authentication

Device Management

osai-agent devices list                List managed devices
osai-agent devices list --local        List local devices
osai-agent devices add                 Add a device (interactive wizard)
osai-agent devices add --local         Add a device locally
osai-agent devices remove <id>         Remove a device

LLM Provider Management

osai-agent provider list               List all available providers
osai-agent provider set <type>         Configure a provider (--key, --model, --url)
osai-agent provider models <type>      List models for a provider
osai-agent provider show               Show current provider configuration
osai-agent provider reset              Reset to default provider
osai-agent provider add custom         Add a custom OpenAI-compatible provider
osai-agent provider configured         List configured providers
osai-agent provider switch <type>      Switch to a configured provider

Sessions

osai-agent session list                List saved sessions
osai-agent session load <id>           Resume a session
osai-agent session export <id>         Export session (markdown / JSON)
osai-agent session delete <id>         Delete a session

MCP

osai-agent mcp list                    List configured MCP servers
osai-agent mcp add <name>              Register an MCP server
osai-agent mcp remove <name>           Remove an MCP server
osai-agent mcp reload                  Reload MCP configurations
osai-agent mcp test <name>             Test connection to an MCP server

Search Configuration

osai-agent search set serpapi --key <k>   Set SerpAPI key
osai-agent search set tavily --key <k>    Set Tavily key
osai-agent search list                    List configured search providers

DuckDuckGo is always available with no API key required.

Pro Access

osai-agent pro --key <code>             Activate a pro access code

Upgrade to Pro for higher daily limits (500 msgs/day, 30 req/min, 5 connections). Bring your own API key (BYOK) for unlimited usage on any plan.

Other Commands

osai-agent config                       Show current configuration
osai-agent config set-os <os>           Override OS detection
osai-agent skills                       Manage installed skills
osai-agent account delete               Permanently delete your account and all data
osai-agent stop-subagent                Stop a running sub-agent
osai-agent --version                    Show version
osai-agent --help                       Show help

LLM Providers

OS AI Agent supports 30+ LLM providers with a Bring Your Own Key (BYOK) model.

OpenAI-compatible: OpenAI, Anthropic (via fetch), Groq, Mistral, DeepSeek, xAI (Grok), Cohere, Perplexity, Together, Fireworks, Cerebras, OpenRouter, Ollama, LM Studio, vLLM, Cloudflare, Hugging Face, NVIDIA, GitHub Models, SiliconFlow, Hyperbolic, Novita, DeepInfra, Replicate, Codestral, Qwen, Azure, Bedrock, Vertex AI, Moonshot, Zhipu, Yi, Baidu, and any custom OpenAI-compatible endpoint.

Native SDK: Anthropic (direct streaming), Google Gemini.

Keyless (local models): Ollama, LM Studio, vLLM — no API key required.

Usage: Configure with osai-agent provider set <type> --key <key>.

Device Management

Connect to and manage remote devices via SSH with encrypted credential storage.

Supported device types: Cisco IOS, IOS-XE, NX-OS, ASA, MikroTik RouterOS, pfSense, Juniper JunOS, Linux, Windows Server.

osai-agent devices add

The agent auto-detects the appropriate mode (SSH or NETWORK) based on device type.

MCP Protocol Support

OS AI Agent can both consume external MCP servers and expose its own tools as an MCP server.

Client (consuming MCP servers)

Register an MCP server and call its tools during an agent session:

osai-agent mcp add my-server --command "node" --args "./server.js"

Server (exposing tools)

Run the OS AI Agent MCP server for any MCP-compatible client:

{
  "mcpServers": {
    "osai-agent": {
      "command": "node",
      "args": ["path/to/osai-agent-server/src/mcp/index.js"]
    }
  }
}

Web Search

| Provider | API Key Required | |----------|-----------------| | DuckDuckGo | No | | SerpAPI | Yes (osai-agent search set serpapi --key <key>) | | Tavily | Yes (osai-agent search set tavily --key <key>) |

Keyboard Shortcuts

| Key | Action | |-----|--------| | Enter | Submit input | | Escape | Cancel current task / close modal | | Tab | Toggle between PLAN and EXEC modes | | Ctrl+C | Auto-save session and exit | | PageUp | Pause auto-scroll | | PageDown / End | Resume auto-scroll | | Up / Down | Navigate frozen transcript |

Slash Commands

Available within a running session by typing / and pressing Enter:

| Command | Action | |---------|--------| | /clear | Clear the transcript | | /help or /? | Show help | | /new | Start a fresh session | | /save | Manually save the session | | /history | Browse session history | | /status | Show session statistics | | /context | Show context window usage | | /mode | Open mode selection picker | | /provider | Open LLM provider picker | | /devices | List configured devices | | /todos | Show task list | | /plan | Switch to PLAN mode (read-only) | | /exec | Switch to EXEC mode | | /logout | Log out of the server | | /exit | Exit without saving |

Configuration

Environment variables (CLI)

| Variable | Default | Description | |----------|---------|-------------| | OSAI_MAX_ITERATIONS | 100 | Max agent loop iterations | | OSAI_AUTO_CONTINUE | 10 | Max auto-continues on incomplete signal | | OSAI_COMMAND_TIMEOUT | 30000 | Command execution timeout (ms) | | OSAI_UI_ANIMATIONS | 1 | Set to 0 to disable UI animations | | AES_SECRET | — | Override encryption key (local mode) |

Server setup

The backend server provides authentication, device storage, and LLM proxying:

cd osai-agent-server
cp .env.example .env
# Edit .env with your MongoDB, Redis, and JWT configuration
npm start

Required server environment:

| Variable | Description | |----------|-------------| | MONGODB_URI | MongoDB connection string | | JWT_SECRET | JWT signing secret | | AES_SECRET | Encryption key for stored credentials | | AGENT_WORKER_URL | LLM worker endpoint | | AGENT_SECRET | Shared worker secret | | UPSTASH_REDIS_REST_URL | Redis URL for caching and rate limiting | | UPSTASH_REDIS_REST_TOKEN | Redis authentication token |

Deployment

The server requires Node.js 18+ and can be deployed on any VM or container platform:

• Free tier: Oracle Cloud Always Free, MongoDB Atlas M0, Upstash Redis Free
• Production: Any VPS (Hetzner, DigitalOcean) with MongoDB Atlas M2+ and Upstash Pro

The CLI agent is installed via npm and connects to the server over HTTP and WebSocket.

License

PRIVATE SOFTWARE — Copyright © 2026 OLOJEDE Samuel. All rights reserved.

This software and its source code are proprietary and confidential. Unauthorized copying, distribution, modification, or use is strictly prohibited without prior written permission from the copyright holder.