🤖 AI Agents Server

Self-hosted platform for creating, managing, and running autonomous AI agents

Features • Quick Start • Installation • Development • Architecture • API • License

What is AI Agents Server?

AI Agents Server is a fully self-hosted, open-source platform for building and running AI agents powered by local LLMs (via Ollama) or any OpenAI-compatible API. No cloud dependencies, no API costs — your data stays on your machine.

Think of it as your personal AI workforce: create agents with unique personalities, give them skills (tools), assign tasks, and let them work autonomously — complete with long-term memory, thinking protocols, and project management.

Who is this for?

Developers who want to experiment with AI agents locally
Researchers exploring autonomous AI behavior, beliefs, and reasoning
Teams that need a private, self-hosted AI agent management system
Hobbyists who want to run powerful AI agents without cloud subscriptions

Features

🧠 Intelligent Agents

Create agents with custom personalities, system prompts, and generation parameters
Belief System — define core (immutable) and additional (mutable) beliefs for each agent
Aspirations — set dreams, desires, and goals that guide agent behavior
Multi-Model Support — assign different LLM models for different roles (primary, analytical, creative)
Per-agent access controls (filesystem, system)

🔧 Skills System

Extensible tool/skill framework — agents can use skills to interact with the world
Built-in skills: web fetch, file read/write, shell execution, code execution, memory store/search, project file management, text summarization
Create custom skills with Python code and JSON schemas
Agents select and invoke skills autonomously during conversations

🧪 Thinking Protocols

Define step-by-step reasoning workflows for agents
Standard protocols — structured analysis and research flows
Orchestrator protocols — meta-protocols that delegate to child protocols
Loop protocols — autonomous work cycles where agents self-direct
Full thinking log visibility for debugging and research

💬 Chat Interface

VS Code-style resizable chat panel
Persistent chat sessions with full history
Multi-model chat — compare responses from different models side by side
Multi-agent chat — have several agents collaborate in one session
Automatic session titles via LLM
Markdown rendering with syntax highlighting

🚀 Autonomous Execution

Agents can run autonomously — processing tasks, making decisions, writing code
Built-in project system — agents write code to isolated project directories
Task management with scheduling (cron expressions)
Real-time progress via WebSocket

🧬 Long-Term Memory

Vector Memory (ChromaDB) — semantic search across agent memories
Knowledge Graph — typed links between memory records
Memory categories, tags, importance scoring
Deep memory processing — agents analyze and connect their own memories

🏗️ Infrastructure

MongoDB for all data storage (agents, tasks, logs, etc.)
Redis for caching, ChromaDB for vector embeddings
Ollama integration with auto-model sync, health monitoring, and watchdog
Swagger/ReDoc API documentation

🖥️ Admin Dashboard

Modern dark-themed UI (Vue 3 + Vuetify 3)
Dashboard with system overview
Agent management with avatar support
Skill editor with CodeMirror
Model management (Ollama + external APIs)
System logs, file browser, terminal, process monitor
Project browser for agent-generated code

Quick Start

The fastest way to get running (requires Docker and Ollama):

git clone https://github.com/okhmat-anton/ai-agents-server.git
cd ai-agents-server
make install

This will:

Create .env from template
Check/install Ollama
Offer to download a default model (qwen2.5-coder:14b)
Build and start all services

Then open: http://localhost:4200
Login: admin / admin123

Installation

Prerequisites

Requirement	Version	Notes
Docker	20.10+	Install Docker
Docker Compose	v2+	Included with Docker Desktop
Ollama	Latest	Install Ollama
RAM	8 GB+	16 GB+ recommended for 14B models
Disk	10 GB+	Models take 4–9 GB each

💡 Ollama is required for local LLM inference. You can also use any OpenAI-compatible API (GPT-4, Claude, Mistral, etc.) by configuring external model providers in the UI.

macOS

1. Install Docker Desktop

# Download and install from:
# https://www.docker.com/products/docker-desktop/
# Or with Homebrew:
brew install --cask docker

Launch Docker Desktop and wait for it to start.

2. Install Ollama

# Download from https://ollama.com/download/mac
# Or with Homebrew:
brew install ollama

Start Ollama:

ollama serve

Pull a model (in another terminal):

# Recommended for coding tasks (requires ~9 GB RAM):
ollama pull qwen2.5-coder:14b

# Lighter alternative (~4 GB RAM):
ollama pull qwen2.5-coder:7b

# Or any model you prefer:
ollama pull llama3.1:8b

3. Clone and Run

git clone https://github.com/okhmat-anton/ai-agents-server.git
cd ai-agents-server
make install

4. Open the App

Frontend: http://localhost:4200
Backend API: http://localhost:4700
API Docs: http://localhost:4700/docs
Login: admin / admin123

Linux (Ubuntu / Debian)

1. Install Docker

# Install Docker Engine
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

# Verify
docker --version
docker compose version

2. Install Ollama

curl -fsSL https://ollama.com/install.sh | sh

Start Ollama:

ollama serve &

Pull a model:

ollama pull qwen2.5-coder:14b
# Or a lighter model:
ollama pull qwen2.5-coder:7b

3. Clone and Run

git clone https://github.com/okhmat-anton/ai-agents-server.git
cd ai-agents-server
make install

4. Open the App

Frontend: http://localhost:4200
Backend API: http://localhost:4700
API Docs: http://localhost:4700/docs
Login: admin / admin123

Note for Linux: If Ollama is running on the same host, the default OLLAMA_BASE_URL=http://host.docker.internal:11434 in .env should work with Docker Desktop. On plain Docker Engine, you may need to change it to http://172.17.0.1:11434 or your host IP.

Windows

1. Install Docker Desktop

Download and install Docker Desktop for Windows from:
https://www.docker.com/products/docker-desktop/

Enable WSL 2 backend during installation (recommended)
Launch Docker Desktop and wait for it to start

2. Install Ollama

Download and install from: https://ollama.com/download/windows

After installation, Ollama runs as a system service. Open PowerShell:

# Verify Ollama is running
ollama list

# Pull a model
ollama pull qwen2.5-coder:14b
# Or lighter:
ollama pull qwen2.5-coder:7b

3. Install Git (if not already installed)

# Download from https://git-scm.com/download/win
# Or with winget:
winget install Git.Git

4. Install Make (optional but recommended)

# Option A: Install via Chocolatey
choco install make

# Option B: Install via winget
winget install GnuWin32.Make

If you don't have make, see the Manual Setup section below.

5. Clone and Run

Open Git Bash or WSL terminal:

git clone https://github.com/okhmat-anton/ai-agents-server.git
cd ai-agents-server
make install

6. Open the App

Frontend: http://localhost:4200
Backend API: http://localhost:4700
API Docs: http://localhost:4700/docs
Login: admin / admin123

Manual Setup (without Make)

If you can't use make, run these commands manually:

# 1. Copy environment file
cp .env.example .env

# 2. Review and edit .env if needed
#    (default values work for local development)

# 3. Make sure Ollama is running
ollama serve

# 4. Pull a model
ollama pull qwen2.5-coder:14b

# 5. Start all services with Docker Compose
docker compose up -d --build

# 6. Open http://localhost:4200

Configuration

All configuration is managed via the .env file in the project root.

Variable	Default	Description
`BACKEND_PORT`	`4700`	Backend API port
`FRONTEND_PORT`	`4200`	Frontend UI port
`REDIS_PORT`	`4379`	Redis port
`CHROMADB_PORT`	`4800`	ChromaDB vector database port
`MONGO_PORT`	`4717`	MongoDB port
`REDIS_PASSWORD`	`redis_secret_2026`	Redis password
`MONGO_USER`	`agents`	MongoDB username
`MONGO_PASSWORD`	`mongo_secret_2026`	MongoDB password
`MONGO_DB`	`ai_agents`	MongoDB database name
`JWT_SECRET_KEY`	`super-secret-jwt-key-...`	Change in production!
`DEFAULT_ADMIN_USERNAME`	`admin`	Default admin login
`DEFAULT_ADMIN_PASSWORD`	`admin123`	Change in production!
`OLLAMA_BASE_URL`	`http://host.docker.internal:11434`	Ollama API URL

⚠️ Production: Always change JWT_SECRET_KEY, DEFAULT_ADMIN_PASSWORD, REDIS_PASSWORD, and MONGO_PASSWORD before deploying.

Development

Dev Mode (Hot Reload)

For active development, run infrastructure in Docker and backend/frontend locally with hot reload:

make run-dev

This starts:

Redis, ChromaDB — in Docker containers
Backend — locally with uvicorn --reload (Python 3.11)
Frontend — locally with vite hot module replacement

Manual Dev Setup

# Start infrastructure
docker compose up -d redis chromadb

# Backend (requires Python 3.11)
cd backend
python3.11 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt
PYTHONPATH=. OLLAMA_BASE_URL=http://localhost:11434 CHROMADB_URL=http://localhost:4800 \
  uvicorn app.main:app --host 0.0.0.0 --port 4700 --reload

# Frontend (in another terminal)
cd frontend
npm install
VITE_BACKEND_URL=http://localhost:4700 npm run dev -- --host 0.0.0.0 --port 4200

Common Commands

Command	Description
`make install`	First-time setup (env, Docker, Ollama, models)
`make run`	Production: start all services via Docker
`make run-dev`	Dev mode: infra in Docker, backend+frontend local
`make stop`	Stop Docker services
`make stop-dev`	Kill local dev processes (ports 4700, 4200)
`make restart`	Restart Docker services
`make update`	Pull latest code, install deps, rebuild
`make logs`	Follow backend logs
`make test`	Run backend tests
`make lint`	Run linter (ruff)
`make clean`	Stop and remove all volumes (⚠️ deletes data)

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Frontend                             │
│                  Vue 3 + Vuetify 3 + Pinia                  │
│                   http://localhost:4200                      │
└────────────────────────┬────────────────────────────────────┘
                         │ REST API + WebSocket
┌────────────────────────▼────────────────────────────────────┐
│                        Backend                              │
│                  FastAPI + MongoDB                          │
│                   http://localhost:4700                      │
│                                                             │
│  ┌─────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────┐  │
│  │  Auth   │  │  Agents  │  │  Skills  │  │    Chat     │  │
│  │ Service │  │  Engine  │  │  Runner  │  │   Engine    │  │
│  └─────────┘  └──────────┘  └──────────┘  └─────────────┘  │
│  ┌─────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────┐  │
│  │  Tasks  │  │  Memory  │  │ Thinking │  │ Autonomous  │  │
│  │ Scheduler│ │  Service │  │ Protocols│  │   Runner    │  │
│  └─────────┘  └──────────┘  └──────────┘  └─────────────┘  │
└───┬──────────────┬──────────────┬───────────────┬───────────┘
    │              │              │               │
┌───▼───┐   ┌─────▼─────┐  ┌────▼────┐  ┌───▼────┐  ┌──────▼──────┐
            │  MongoDB  │  │  Redis  │  │ChromaDB│  │   Ollama    │
│        │  │   :4717   │  │  :4379  │  │ :4800  │  │  :11434     │
            │ Documents │  │  Cache  │  │Vectors │  │  Local LLM  │
└────────┘  └───────────┘  └─────────┘  └────────┘  └─────────────┘

Tech Stack

Layer	Technology
Frontend	Vue 3.5, Vuetify 3.7, Pinia 2.3, Vue Router 4, Vite 6, CodeMirror 6
Backend	Python 3.11, FastAPI 0.115, Pydantic 2.10, Motor 3.6
Database	MongoDB 7
Cache	Redis 7
Vector DB	ChromaDB
LLM	Ollama (local) + any OpenAI-compatible API
Container	Docker Compose

API

Full interactive API documentation is available at:

Swagger UI: http://localhost:4700/docs
ReDoc: http://localhost:4700/redoc

Key API Endpoints

Endpoint	Description
`POST /api/auth/login`	Authenticate and get JWT tokens
`GET /api/agents`	List all agents
`POST /api/agents`	Create a new agent
`POST /api/agents/{id}/execute`	Execute agent
`GET /api/agents/{id}/memory`	Agent memory records
`GET /api/chat/sessions`	Chat sessions
`POST /api/chat/sessions/{id}/messages`	Send a message
`GET /api/skills`	List available skills
`GET /api/tasks`	List tasks
`GET /api/ollama/status`	Ollama health status
`GET /api/ollama/models`	Available models
`GET /api/system/info`	System information

All endpoints (except auth) require Authorization: Bearer <token> header.

Troubleshooting

Ollama connection issues

If agents can't connect to Ollama, check the OLLAMA_BASE_URL in .env:

# macOS / Windows (Docker Desktop):
OLLAMA_BASE_URL=http://host.docker.internal:11434

# Linux (Docker Engine without Docker Desktop):
OLLAMA_BASE_URL=http://172.17.0.1:11434
# Or use your host machine's IP address

Python version

The backend requires Python 3.11. Python 3.14 is not supported (pydantic-core build fails).

Backend can't find modules

When running the backend locally (outside Docker), PYTHONPATH=. is required:

cd backend
PYTHONPATH=. .venv/bin/uvicorn app.main:app --port 4700

Database reset

To completely reset all data:

make clean    # Removes all Docker volumes
make run      # Recreate fresh

Port conflicts

If default ports are in use, change them in .env:

BACKEND_PORT=4701
FRONTEND_PORT=4201

Project Structure

ai-agents-server/
├── backend/                    # Python FastAPI backend
│   ├── app/
│   │   ├── api/               # Route handlers (one file per domain)
│   │   ├── core/              # Auth dependencies, security
│   │   ├── llm/               # LLM provider abstraction (Ollama, OpenAI)
│   │   ├── mongodb/           # MongoDB Pydantic models and services
│   │   ├── schemas/           # Pydantic request/response schemas
│   │   ├── services/          # Business logic layer
│   │   ├── config.py          # Settings (reads .env)
│   │   ├── database.py        # MongoDB, Redis initialization
│   │   └── main.py            # FastAPI app & lifespan
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/                   # Vue 3 SPA
│   ├── src/
│   │   ├── api/               # Axios instance + interceptors
│   │   ├── components/        # Reusable components (ChatPanel, etc.)
│   │   ├── layouts/           # App layout (sidebar + chat panel)
│   │   ├── views/             # Page components
│   │   ├── stores/            # Pinia state management
│   │   ├── router/            # Vue Router config
│   │   └── plugins/           # Vuetify setup
│   ├── package.json
│   └── Dockerfile
├── data/                       # Runtime data (agents, skills, projects)
│   ├── agents/                # Agent configs, beliefs, aspirations
│   ├── skills/                # Custom skill code
│   └── projects/              # Agent-generated project code
├── docker-compose.yml
├── Makefile
├── .env.example               # Environment template
└── README.md

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.

_{Built with ❤️ using FastAPI, Vue 3, Ollama, and MongoDB}

Name		Name	Last commit message	Last commit date
Latest commit History 199 Commits
.vscode		.vscode
addons		addons
addons_private @ d79e879		addons_private @ d79e879
backend		backend
frontend		frontend
skills		skills
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CodeReview.md		CodeReview.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
agent_usage_ideas.md		agent_usage_ideas.md
ais34_completion.md		ais34_completion.md
ais35_requirements.md		ais35_requirements.md
check_chat.py		check_chat.py
check_copy.py		check_copy.py
check_logs.py		check_logs.py
debug_chat.py		debug_chat.py
docker-compose.yml		docker-compose.yml
friend.md		friend.md
home_auctions.md		home_auctions.md
idea.txt		idea.txt
nohup.out		nohup.out
post_comment.py		post_comment.py
server.log		server.log
skills_we_need.md		skills_we_need.md
system_plan.md		system_plan.md
technical_requirements.txt		technical_requirements.txt
test_fixes.py		test_fixes.py
test_kieai_stt.py		test_kieai_stt.py

Folders and files

Latest commit

History

Repository files navigation

🤖 AI Agents Server

What is AI Agents Server?

Who is this for?

Features

🧠 Intelligent Agents

🔧 Skills System

🧪 Thinking Protocols

💬 Chat Interface

🚀 Autonomous Execution

🧬 Long-Term Memory

🏗️ Infrastructure

🖥️ Admin Dashboard

Quick Start

Installation

Prerequisites

macOS

1. Install Docker Desktop

2. Install Ollama

3. Clone and Run

4. Open the App

Linux (Ubuntu / Debian)

1. Install Docker

2. Install Ollama

3. Clone and Run

4. Open the App

Windows

1. Install Docker Desktop

2. Install Ollama

3. Install Git (if not already installed)

4. Install Make (optional but recommended)

5. Clone and Run

6. Open the App

Manual Setup (without Make)

Configuration

Development

Dev Mode (Hot Reload)

Manual Dev Setup

Common Commands

Architecture

Tech Stack

API

Key API Endpoints

Troubleshooting

Ollama connection issues

Python version

Backend can't find modules

Database reset

Port conflicts

Project Structure

Contributing

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages