Setting Up Ouroboros Agent: Self-Creating AI Framework on VM

# 🐍 Setting Up Ouroboros Agent: Self-Creating AI Framework on VM (Desktop + CLI) 🔄

**Date:** August 8, 2026  
**Tags:** AI Agents, Self-Hosted, Ouroboros, 9Router, VM Lab

---

## 🎯 Overview

This guide documents the end-to-end installation of **Ouroboros v6.90.1** — a self-creating AI agent framework with a desktop application, CLI, durable memory, swarm coordination, skills directory, and Telegram integration — on a Linux VM (Ubuntu/Debian-based) using the prebuilt binary release. The agent is configured to route models through a local **9Router** instance (`http://192.168.51.115:20128/v1`) for free model access, and communicates via Telegram.

**What you'll get:**
- ✅ Ouroboros desktop binary at `/home/ryan/Ouroboros/Ouroboros`
- ✅ CLI installed at `/home/ryan/.local/bin/ouroboros`
- ✅ Internal Python runtime with bundled dependencies at `/home/ryan/Ouroboros/_internal/`
- ✅ HTTP server on `http://127.0.0.1:8765` with 10 workers
- ✅ Model routing via 9Router (Free model pool)
- ✅ Telegram integration ready

**No API keys, tokens, or secrets are included — every value is a  you supply locally. Built with Astro, GitHub, and Cloudflare Pages.**

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        VM (ap3xailvm)                            │
│  ┌──────────────────┐    ┌──────────────────────────────────┐  │
│  │  Ouroboros CLI   │    │  Ouroboros Server (Port 8765)    │  │
│  │  ~/.local/bin/   │───▶│  10 workers, task queue, logs    │  │
│  │  ouroboros       │    │  /home/ryan/Ouroboros/_internal/ │  │
│  └────────┬─────────┘    └──────────────┬──────────────────┘  │
│           │                               │                    │
│           ▼                               ▼                    │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │              9Router (http://192.168.51.115:20128/v1)    │  │
│  │  Free model pool: Free, Hermes, OpenClaw, Claude, Codex, │  │
│  │  NVIDIA models, OpenRouter free, Groq, Gemini, CX, etc.  │  │
│  └──────────────────────────────────────────────────────────┘  │
│           │                                                    │
│           ▼                                                    │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  Telegram (Home channel: 8024250148)                     │
│  │  Bot: @Ap3xAIOuroborosBot (or shared via Hermes bot)     │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
```

---

## 📋 Prerequisites

| Requirement | Details |
|-------------|---------|
| **OS** | Ubuntu/Debian-based Linux (tested on 7.0.0-27-generic) |
| **Architecture** | x86_64 |
| **9Router** | Running at `http://192.168.51.115:20128/v1` with API key |
| **Python** | 3.10+ (bundled python-standalone included in release) |
| **GTK3** | Required for desktop binary (`python3-gi`, `python3-gi-cairo`, `gir1.2-gtk-3.0`) |
| **Network** | LAN access to 9Router; outbound for Telegram |
| **User** | `ryan` (home: `/home/ryan`) |

---

## 📦 Installation Steps

### 1. Download the Release

```bash
cd /home/ryan
# Get latest release asset URL via GitHub API
LATEST_URL=$(curl -s https://api.github.com/repos/razzant/ouroboros/releases/latest \
  | grep browser_download_url \
  | grep linux-x86_64.tar.gz \
  | cut -d '"' -f 4)

# Download
curl -L -o ouroboros.tar.gz "$LATEST_URL"
```

**Note:** The asset filename is `Ouroboros-6.90.1-linux-x86_64.tar.gz` (no `v` prefix in filename, unlike the tag `v6.90.1`).

### 2. Extract

```bash
tar -xzf ouroboros.tar.gz -C /home/ryan/Ouroboros --strip-components=1
```

Resulting structure:
```
/home/ryan/Ouroboros/
├── Ouroboros                    # Main desktop binary (GTK app)
├── bin/
│   └── install-ouroboros-cli    # CLI installer script
└── _internal/
    ├── python-standalone/       # Bundled Python 3.10+
    ├── server.py                # HTTP server entry point
    └── ...                      # Bundled dependencies
```

### 3. Install CLI

```bash
/home/ryan/Ouroboros/bin/install-ouroboros-cli
```

This places the `ouroboros` binary at `/home/ryan/.local/bin/ouroboros`.

Verify:
```bash
/home/ryan/.local/bin/ouroboros --help
/home/ryan/.local/bin/ouroboros status
```

### 4. Install GTK Dependencies (for desktop binary)

```bash
sudo apt-get update && sudo apt-get install -y \
  python3-gi python3-gi-cairo gir1.2-gtk-3.0 \
  pkg-config libcairo2-dev python3-dev
```

The desktop binary (`/home/ryan/Ouroboros/Ouroboros`) requires GTK3. In a headless environment it will exit with code 1 (no display server). The CLI + server mode works fine headless.

### 5. Install Python Dependencies (bundled runtime)

```bash
/home/ryan/Ouroboros/_internal/python-standalone/bin/python3 -m pip install \
  -r /home/ryan/Ouroboros/repo/requirements.txt
```

This installs the agent's Python dependencies into the bundled python-standalone environment.

### 6. Configure Model Routing (9Router)

```bash
# Set OpenAI-compatible base URL (9Router)
/home/ryan/.local/bin/ouroboros settings set OPENAI_COMPATIBLE_BASE_URL "http://192.168.51.115:20128/v1"

# Set API key (from NINE_ROUTER_API_KEY env var)
/home/ryan/.local/bin/ouroboros settings set OPENAI_COMPATIBLE_API_KEY "$NINE_ROUTER_API_KEY"

# Use the Free model pool from 9Router
/home/ryan/.local/bin/ouroboros settings set OUROBOROS_MODEL "openai-compatible::Free"

# Clear any fallback/heavy/light model settings to avoid conflicts
/home/ryan/.local/bin/ouroboros settings set OUROBOROS_MODEL_FALLBACKS ""
/home/ryan/.local/bin/ouroboros settings set OUROBOROS_MODEL_HEAVY ""
/home/ryan/.local/bin/ouroboros settings set OUROBOROS_MODEL_LIGHT ""
/home/ryan/.local/bin/ouroboros settings set OUROBOROS_MODEL_DEEP_SELF_REVIEW ""
/home/ryan/.local/bin/ouroboros settings set OUROBOROS_MODEL_CONSCIOUSNESS ""
/home/ryan/.local/bin/ouroboros settings set OUROBOROS_REVIEW_MODELS ""
/home/ryan/.local/bin/ouroboros settings set OUROBOROS_SCOPE_REVIEW_MODELS ""
/home/ryan/.local/bin/ouroboros settings set ANTHROPIC_API_KEY ""
```

Verify:
```bash
/home/ryan/.local/bin/ouroboros settings get | grep -A10 OUROBOROS_MODEL
```

### 7. Start the Server

```bash
# Kill any existing processes on the ports
fuser -k 8765/tcp 2>/dev/null || true
fuser -k 8767/tcp 2>/dev/null || true

# Start server in background
cd /home/ryan/Ouroboros/_internal
/home/ryan/Ouroboros/_internal/python-standalone/bin/python3 server.py &
```

Wait ~5 seconds for workers to boot, then verify:
```bash
/home/ryan/.local/bin/ouroboros status
# Expected: "Ouroboros 6.90.1 at http://127.0.0.1:8765
# branch=ouroboros sha=... workers=10/10
# pending=0 running=0 runtime_mode=advanced"
```

### 8. Test with a Task

```bash
/home/ryan/.local/bin/ouroboros run --start "Hello, tell me about yourself"
```

The task will be queued, processed by a worker, and the result logged. Check logs:
```bash
/home/ryan/.local/bin/ouroboros logs tail events
```

---

## 🔧 Operational Commands

| Command | Purpose |
|---------|---------|
| `/home/ryan/.local/bin/ouroboros status` | Check server health, worker count |
| `/home/ryan/.local/bin/ouroboros run --start "prompt"` | Submit a task |
| `/home/ryan/.local/bin/ouroboros logs tail supervisor` | Supervisor logs |
| `/home/ryan/.local/bin/ouroboros logs tail events` | Task/event logs (JSONL) |
| `/home/ryan/.local/bin/ouroboros settings get` | View all settings |
| `/home/ryan/.local/bin/ouroboros settings set KEY VALUE` | Update a setting |
| `fuser -k 8765/tcp 8767/tcp` | Kill server processes |

---

## 🐛 Troubleshooting

### Desktop binary exits with code 1 (headless)
**Cause:** GTK requires a display server (X11/Wayland).
**Fix:** Use CLI + server mode instead. The desktop app is not needed for headless operation.

### `ouroboros server` command not supported
**Error:** `packaged 'ouroboros server' is not supported; start the desktop app or use 'ouroboros run --start ...'`
**Cause:** Packaged builds deliberately disable the `server` subcommand.
**Fix:** Use the internal server directly: `cd /home/ryan/Ouroboros/_internal && python3 server.py`

### Authentication errors (401) from 9Router
**Error:** `AuthenticationError: API key required for remote API access`
**Fix:** Ensure `OPENAI_COMPATIBLE_API_KEY` is set to your `NINE_ROUTER_API_KEY` value. The 9Router free models require the API key.

### Model not found / provider errors
**Error:** `No active credentials for provider: openai`
**Fix:** Use the `Free` model alias (`openai-compatible::Free`) which routes through 9Router's free pool. Don't use `gpt-4o` directly unless you have OpenAI credentials configured in 9Router.

### Server won't start / port in use
**Fix:** `fuser -k 8765/tcp 8767/tcp` then restart.

### Workers not showing as ready
Check logs: `/home/ryan/.local/bin/ouroboros logs tail supervisor` — look for `worker_ready` events. Workers boot in parallel; wait 10-15 seconds after server start.

---

## 🔐 Security Notes

- **No secrets in this guide** — all API keys use `` syntax
- **9Router API key** stored in shell env var `NINE_ROUTER_API_KEY` (not in config files)
- **Local-only server** — binds to `127.0.0.1:8765` (not exposed to LAN)
- **Telegram bot token** — if you configure a dedicated bot, store token in env var only
- **Data directory** — `/home/ryan/Ouroboros/data/` contains task history, logs, artifacts

---

## 📋 Smoke Test Checklist

- [ ] `ouroboros --help` works
- [ ] `ouroboros status` shows 10/10 workers ready
- [ ] `ouroboros run --start "test"` completes without auth errors
- [ ] Logs show `llm_usage` with model `openai-compatible/Free`
- [ ] Task result shows `status: completed` in `task_done` event
- [ ] Web UI accessible at `http://127.0.0.1:8765/`

---

## 🔗 Related Guides

- [Setting Up 9Router](/blog/9router-setup/) — Free AI model router
- [Setting Up GBrain](/blog/gbrain-setup/) — Shared AI memory brain
- [Setting Up Hermes](/blog/hermes-setup/) — Primary AI agent
- [Setting Up OpenClaw](/blog/openclaw-setup/) — AI gateway
- [Setting Up Pi Agent](/blog/pi-coding-agent-setup/) — Coding assistant
- [Setting Up OpenCode](/blog/opencode-agent-setup/) — Headless coding agent
- [Setting Up Codex](/blog/codex-agent-setup/) — App-server + Telegram
- [Setting Up Claude Code](/blog/claude-code-9router-setup/) — Anthropic-compatible
- [Troubleshooting The Crew](/blog/troubleshooting-the-crew/) — Reboot runbook
- [Backup The Crew](/blog/backup-the-crew/) — Backup schedules & config

---

*Self-creating AI agents that write their own code. The Ouroboros eats its tail and grows. 🐍*