Documentation

Introduction

AgentOS is a production-ready runtime for autonomous AI agents. It provides built-in memory management, safe tool sandboxing, and multi-provider LLM support.

Key Features

• Multi-provider LLM support (OpenAI, Claude, Gemini, etc.)
• Interactive chat mode with rich terminal UI
• Security-first design with command filtering
• Process management with SQLite backend
• Optional Docker isolation for safe execution
• Comprehensive logging and monitoring

Installation

AgentOS can be installed on Linux and Windows systems. Choose your platform below:

Linux

# Clone the repository
git clone https://github.com/agents-os/agentos.git
cd agentos

# Run the installer
python3 install_linux.py

Windows

# Clone the repository
git clone https://github.com/agents-os/agentos.git
cd agentos

# Run the installer
python install_windows.py

Requirements

• Python: 3.8 or higher
• Git: For cloning the repository
• Docker: Optional, for isolated execution

Quick Start

Get your first agent running in under 5 minutes.

Step 1: Create an Agent Manifest

Create a file named agent.yaml with the following content:

name: my_assistant
model_provider: github
model_version: openai/gpt-4o-mini
isolated: false

DESTRUCTIVE_COMMANDS:
  - rm
  - sudo
  - rmdir

Step 2: Run Your Agent

agentos run agent.yaml --task "create a Python hello world script"

Step 3: Monitor Your Agent

agentos ps

Configuration

AgentOS uses environment variables for API keys and global settings.

Environment Variables

Create a .env file in your project directory:

# API Keys
GIT_HUB_TOKEN=your_github_token
OPENAI_API_KEY=your_openai_key
CLAUDE_API_KEY=your_claude_key
GEMINI_API_KEY=your_gemini_key
COHERE_API_KEY=your_cohere_key

Logging

Logs are stored in ~/.agentos/logs/:

• agentos.log - Main system log
• <agent_name>_<id>.log - Per-agent execution logs

Database

Agent registry is stored in ~/.agentos/runtime.db (SQLite).

Agents

Agents are the core building blocks of AgentOS. Each agent is defined by a manifest file and can perform autonomous tasks.

Agent Lifecycle

Agent States

Manifests

Agent manifests are YAML files that define an agent's configuration.

Required Fields

Optional Fields

Complete Example

name: research_assistant
model_provider: claude
model_version: claude-3-5-sonnet
isolated: true

DESTRUCTIVE_COMMANDS:
  - rm
  - rmdir
  - sudo
  - dd
  - mkfs
  - format
  - kill

LLM Providers

AgentOS supports multiple LLM providers out of the box.

Security

AgentOS is designed with security as a first-class concern.

Command Filtering

Dangerous commands are blocked by default:

Input Validation

The following are sanitized to prevent command injection:

• Shell metacharacters: ; && || |
• Command substitution: ` $()
• Variable expansion: $VAR

Resource Limits

agentos run

Run an agent with a specified task.

Usage

agentos run <manifest> --task "<task>" [options]

Options

Examples

# Basic usage
agentos run agent.yaml --task "create a REST API"

# With timeout
agentos run agent.yaml --task "analyze data" --timeout 600

# Verbose mode
agentos run agent.yaml --task "debug code" --verbose

agentos chat

Start an interactive chat session with an LLM.

Usage

agentos chat [options]

Options

In-Chat Commands

Examples

# Default chat
agentos chat

# Use Claude
agentos chat --provider claude

# Local Ollama (no API key needed)
agentos chat --provider ollama

# Custom settings
agentos chat --provider openai --model gpt-4 --temperature 0.3

agentos ps

List all agents and their status.

Usage

agentos ps

Output Example

NAME              STATUS      STARTED              TASK
my_assistant      running     2026-01-16 10:30:00  create a Python script
research_agent    completed   2026-01-16 09:15:00  analyze market data
code_helper       failed      2026-01-16 08:00:00  debug application

agentos logs

View logs for a specific agent.

Usage

agentos logs <agent_name> [options]

Options

agentos stop

Stop a running agent.

Usage

agentos stop <agent_name>

Docker Isolation

Enable Docker sandboxing for maximum security.

Requirements

• Docker daemon must be running
• User must have Docker permissions

Enable Isolation

Set isolated: true in your agent manifest:

name: secure_agent
model_provider: github
model_version: openai/gpt-4o-mini
isolated: true

API Reference

For programmatic access, see the Python API documentation.

Troubleshooting