Skip to main content

​
Quick Install

The fastest way to install AgentOS is using the installation script: 
curl -fsSL https://raw.githubusercontent.com/iii-hq/agentos/main/scripts/install.sh | sh
This script automatically:
  • Detects your operating system and architecture
  • Installs iii-engine v0.3+ (required dependency)
  • Downloads and installs the agentos binary to ~/.local/bin
  • Configures your PATH

​
Requirements

Before installing AgentOS, ensure you have the following dependencies:

iii-engine

v0.3 or higher (installed automatically)

Rust

1.75 or higher (for development)

Node.js

20 or higher (for development)

Python

3.11 or higher (optional, for embeddings)
The quick install script only requires curl. Development dependencies (Rust, Node.js, Python) are only needed if you plan to build from source or contribute to the project.

​
Installation Options

​
Custom Version

Install a specific version of AgentOS: 
AGENTOS_VERSION=v0.1.0 curl -fsSL https://raw.githubusercontent.com/iii-hq/agentos/main/scripts/install.sh | sh

​
Custom Install Directory

Change the installation directory (default is ~/.local/bin): 
BIN_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/iii-hq/agentos/main/scripts/install.sh | sh

​
Combined Options

You can combine multiple options: 
AGENTOS_VERSION=v0.1.0 BIN_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/iii-hq/agentos/main/scripts/install.sh | sh

​
Platform Support

The installation script automatically detects your platform:
Operating SystemArchitectures
Linuxx86_64, aarch64, armv7
macOS (Darwin)x86_64, aarch64 (Apple Silicon)
Windowsx86_64, aarch64
If you encounter an “Unsupported OS” or “Unsupported architecture” error, you’ll need to build from source or check the releases page for available binaries.

​
Development Setup

For development, you’ll need to install the full toolchain:
1

Install Rust

Install Rust 1.75 or higher:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
2

Install Node.js

Install Node.js 20 or higher using nvm or your package manager:
nvm install 20
nvm use 20
3

Install Python (Optional)

Install Python 3.11 or higher for the embedding worker:
# macOS
brew install [email protected]

# Ubuntu/Debian
sudo apt install python3.11
4

Clone the repository

git clone https://github.com/iii-hq/agentos.git
cd agentos
5

Install dependencies

# Install Node.js dependencies
npm install

# Install Python dependencies (optional)
pip install -r workers/embedding/requirements.txt
6

Build the project

# Build Rust crates
cargo build --release --workspace

​
Verifying Installation

After installation, verify that AgentOS is correctly installed: 
agentos --version
You should see output similar to: 
agentos 0.1.0
Verify iii-engine is also installed: 
iii --version

​
PATH Configuration

If the installation script couldn’t automatically add ~/.local/bin to your PATH, you’ll need to do it manually: 
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

​
Troubleshooting

​
iii-engine Not Found

If you see “iii-engine not found” errors, install it manually: 
curl -fsSL https://install.iii.dev/iii/main/install.sh | sh

​
Permission Denied

If you get permission errors when installing to /usr/local/bin, either:
  1. Use sudo (not recommended for the quick install script)
  2. Install to a user directory: 
    BIN_DIR=$HOME/.local/bin curl -fsSL ... | sh

​
Binary Not Found After Installation

If the binary is installed but not found:
  1. Restart your terminal
  2. Verify your PATH includes the installation directory
  3. Manually source your shell configuration: 
    source ~/.bashrc  # or ~/.zshrc

​
Next Steps

Once AgentOS is installed, proceed to the Quickstart guide to initialize your first project and start chatting with agents.

Build docs developers (and LLMs) love

Get started for freeTalk to us