Skip to content

setup.md

Latest commit

 

History

History
147 lines (104 loc) · 4.06 KB

setup.md

File metadata and controls

147 lines (104 loc) · 4.06 KB
Raw

AgentML Setup Guide

Prerequisites

  • Python 3.11+ (3.12 recommended)
  • Node.js 18+
  • Git
  • Ollama (optional) — for fully local inference with no cloud API key. This is the default provider. Install it, then pull a model: ollama pull qwen3:8b. Skip this only if you plan to use Anthropic/OpenAI instead.

Installation

1. Clone the repository

git clone https://github.com/naveenkai/agentml.git
cd agentml

2. Backend setup

cd backend

# Create virtual environment (recommended)
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install IPython kernel (required for Jupyter execution)
python -m ipykernel install --user

3. Frontend setup

# From project root
npm install

4. Configure your LLM provider

AgentML defaults to Ollama for fully local, no-API-key inference. If you installed Ollama and pulled a model (see Prerequisites), you're already done — no configuration needed.

To use a cloud provider instead, set the provider and its key via environment variable (or configure it in the Settings modal after starting the app):

# Anthropic (Claude)
export AGENTML_LLM_PROVIDER=anthropic
export AGENTML_API_KEY=sk-ant-your-key-here

# OpenAI (GPT)
export AGENTML_LLM_PROVIDER=openai
export AGENTML_API_KEY=sk-your-key-here

Provider-specific keys (ANTHROPIC_API_KEY, OPENAI_API_KEY) are also honored and take priority. See backend/.env.example for the full list of variables.

Running

Start the backend

cd backend
python -m uvicorn main:app --reload --port 8002

Start the frontend

# From project root (in a separate terminal)
npm start

The app will be available at http://localhost:3000.

Environment Variables

Variable Description Default
AGENTML_LLM_PROVIDER anthropic, openai, or ollama ollama
AGENTML_API_KEY API key for the active cloud provider (also ANTHROPIC_API_KEY / OPENAI_API_KEY) (none — not needed for Ollama)
AGENTML_OLLAMA_MODEL Ollama model tag qwen3:8b
AGENTML_OLLAMA_BASE_URL Ollama server URL http://localhost:11434
AGENTML_HITL Enable human-in-the-loop approval gates (1/true) false
AGENTML_SESSION_TTL_DAYS Purge session history after N days of inactivity (0 = keep forever) 30
AGENTML_ALLOW_PRIVATE_OLLAMA Allow an Ollama URL on a private/LAN address (SSRF guard opt-out) false
AGENTML_CORS_ORIGINS Comma-separated allowed browser origins http://localhost:3000,http://127.0.0.1:3000
REACT_APP_API_URL Backend API base URL http://localhost:8002
REACT_APP_WS_URL Backend WebSocket URL Derived from API URL

Common Issues

Kernel fails to start

Symptom: "Kernel error" on first code execution.

Fix: Make sure ipykernel is installed in your Python environment:

pip install ipykernel
python -m ipykernel install --user

CORS errors

Symptom: Network errors when frontend calls backend.

Fix: Make sure the frontend origin is included in CORS:

export AGENTML_CORS_ORIGINS=http://localhost:3000

"Invalid API key" error

Symptom: Agent returns auth error.

Fix: Check your API key is correct and matches the provider. OpenAI keys start with sk-, Anthropic keys start with sk-ant-.

Port already in use

Symptom: Address already in use when starting the backend.

Fix: Kill existing processes:

# Find and kill the process using port 8002
lsof -ti:8002 | xargs kill -9

# Or on Windows:
netstat -ano | findstr :8002
taskkill /PID <pid> /F

Database locked errors

The backend uses SQLite in WAL mode with a 10-second busy_timeout, so writers wait for locks rather than failing immediately. If you still see persistent lock errors, make sure only one backend instance is running against the same agentml.db.