/ QUICK-START-GUIDE.md
QUICK-START-GUIDE.md
1 # Ag3ntum Quick Start Guide 2 3 Deploy Ag3ntum on your server - three ways to get started. 4 5 ## Table of Contents 6 7 - [Quick Install (Recommended)](#quick-install-recommended) 8 - [Manual Installation](#manual-installation) 9 - [Configuration Guide](#configuration-guide) 10 - [Troubleshooting](#troubleshooting) 11 12 --- 13 14 ## Quick Install (Recommended) 15 16 Deploy Ag3ntum with a single command: 17 18 ```bash 19 curl -fsSL https://raw.githubusercontent.com/extractumio/ag3ntum/main/install.sh | bash 20 ``` 21 22 The installer will: 23 1. Check prerequisites (Docker, Git) 24 2. Clone the repository 25 3. Prompt for configuration (API key, admin credentials) 26 4. Build and start containers 27 5. Create your admin account 28 29 **Requirements:** 30 - Docker 20.10+ with Docker Compose v2 31 - Git 32 - 2GB RAM (4GB recommended) 33 - [Anthropic API key](https://console.anthropic.com/settings/keys) 34 35 **Supported Platforms:** 36 - macOS (Intel & Apple Silicon) 37 - Ubuntu 20.04+, Debian 11+ 38 - Windows (via WSL2 or Git Bash) 39 40 ### What the Installer Does 41 42 ``` 43 ┌──────────────────┐ 44 │ Check Docker, │ 45 │ Git, Compose │ 46 └────────┬─────────┘ 47 ↓ 48 ┌──────────────────┐ 49 │ Clone Ag3ntum │ 50 │ Repository │ 51 └────────┬─────────┘ 52 ↓ 53 ┌──────────────────┐ 54 │ Interactive │ 55 │ Configuration │ 56 │ - API Key │ 57 │ - Admin creds │ 58 │ - Server host │ 59 └────────┬─────────┘ 60 ↓ 61 ┌──────────────────┐ 62 │ Generate Config │ 63 │ - secrets.yaml │ 64 │ - api.yaml │ 65 │ - agent.yaml │ 66 └────────┬─────────┘ 67 ↓ 68 ┌──────────────────┐ 69 │ Docker Build │ 70 │ (5-10 minutes) │ 71 └────────┬─────────┘ 72 ↓ 73 ┌──────────────────┐ 74 │ Create Admin │ 75 │ User │ 76 └────────┬─────────┘ 77 ↓ 78 ┌──────────────────┐ 79 │ Ready! │ 80 │ http://...:50080│ 81 └──────────────────┘ 82 ``` 83 84 --- 85 86 ## Manual Installation 87 88 If you prefer step-by-step control, follow these instructions. 89 90 ### Prerequisites 91 92 Install these before proceeding: 93 94 | Requirement | Minimum Version | Install Guide | 95 |-------------|-----------------|---------------| 96 | Docker | 20.10+ | [docs.docker.com](https://docs.docker.com/get-docker/) | 97 | Docker Compose | v2.0+ | Included with Docker Desktop | 98 | Git | Any recent | [git-scm.com](https://git-scm.com/downloads) | 99 100 **Check your versions:** 101 ```bash 102 docker --version # Should show 20.10 or higher 103 docker compose version # Should show v2.x 104 git --version 105 ``` 106 107 ### Step 1: Clone the Repository 108 109 ```bash 110 git clone https://github.com/extractumio/ag3ntum.git 111 cd ag3ntum 112 ``` 113 114 ### Step 2: Create Configuration Files 115 116 Copy the example configuration files: 117 118 ```bash 119 # Required configuration files 120 cp config/secrets.yaml.example config/secrets.yaml 121 cp config/api.yaml.example config/api.yaml 122 cp config/agent.yaml.example config/agent.yaml 123 ``` 124 125 ### Step 3: Configure Your API Key 126 127 Edit `config/secrets.yaml` with your Anthropic API key: 128 129 ```yaml 130 # config/secrets.yaml 131 anthropic_api_key: sk-ant-api03-YOUR_KEY_HERE 132 ``` 133 134 Get your API key at [console.anthropic.com](https://console.anthropic.com/settings/keys). 135 136 **Important:** Set proper permissions on this file: 137 ```bash 138 chmod 600 config/secrets.yaml 139 ``` 140 141 ### Step 4: Configure Server Settings (Optional) 142 143 For remote access, edit `config/api.yaml`: 144 145 ```yaml 146 # config/api.yaml 147 server: 148 hostname: "your-server-ip-or-domain" # Change from "localhost" 149 protocol: "http" # Use "https" with reverse proxy 150 ``` 151 152 ### Step 5: Build and Start 153 154 ```bash 155 ./run.sh rebuild --no-cache 156 ``` 157 158 First build takes 5-10 minutes. Subsequent builds are faster. 159 160 ### Step 6: Create Admin User 161 162 ```bash 163 ./run.sh create-user \ 164 --username=admin \ 165 --email=admin@example.com \ 166 --password=YOUR_SECURE_PASSWORD \ 167 --admin 168 ``` 169 170 ### Step 7: Access the Web UI 171 172 Open in your browser: 173 - **Web UI:** http://localhost:50080 174 175 Login with the email and password you created. 176 177 --- 178 179 ## Configuration Guide 180 181 Customize Ag3ntum by editing files in the `config/` directory. 182 183 ### Configuration Files Overview 184 185 | File | Purpose | When to Modify | 186 |------|---------|----------------| 187 | `secrets.yaml` | API keys, credentials | API key setup | 188 | `api.yaml` | Server, ports, security | Remote access, HTTPS | 189 | `agent.yaml` | Claude model, limits | Model selection, timeouts | 190 | `external-mounts.yaml` | File sharing | Mount host directories | 191 192 ### Changing Ports 193 194 Edit `config/api.yaml`: 195 196 ```yaml 197 api: 198 external_port: 40080 # Change API port 199 200 web: 201 external_port: 50080 # Change Web UI port 202 ``` 203 204 Then restart: 205 ```bash 206 ./run.sh restart 207 ``` 208 209 ### Configuring for Remote Access 210 211 1. Set your public hostname or IP: 212 ```yaml 213 server: 214 hostname: "199.195.48.1" # Your VPS IP 215 # or 216 hostname: "ag3ntum.example.com" # Your domain 217 ``` 218 219 2. Open firewall ports: 220 ```bash 221 # Ubuntu (ufw) 222 sudo ufw allow 50080/tcp 223 sudo ufw allow 40080/tcp # Optional: for direct API access 224 ``` 225 226 3. Restart: 227 ```bash 228 ./run.sh restart 229 ``` 230 231 ### Setting Up HTTPS 232 233 Use a reverse proxy (nginx, traefik) for TLS termination: 234 235 1. Configure your reverse proxy to forward to: 236 - Web UI: `http://127.0.0.1:50080` 237 - API: `http://127.0.0.1:40080` 238 239 2. Update `config/api.yaml`: 240 ```yaml 241 server: 242 hostname: "ag3ntum.example.com" 243 protocol: "https" 244 trusted_proxies: 245 - "127.0.0.1" 246 ``` 247 248 Example nginx configuration: 249 250 ```nginx 251 server { 252 listen 443 ssl http2; 253 server_name ag3ntum.example.com; 254 255 ssl_certificate /etc/letsencrypt/live/ag3ntum.example.com/fullchain.pem; 256 ssl_certificate_key /etc/letsencrypt/live/ag3ntum.example.com/privkey.pem; 257 258 # Web UI 259 location / { 260 proxy_pass http://127.0.0.1:50080; 261 proxy_http_version 1.1; 262 proxy_set_header Upgrade $http_upgrade; 263 proxy_set_header Connection "upgrade"; 264 proxy_set_header Host $host; 265 proxy_set_header X-Real-IP $remote_addr; 266 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 267 proxy_set_header X-Forwarded-Proto $scheme; 268 } 269 270 # API (SSE support requires longer timeouts) 271 location /api/ { 272 proxy_pass http://127.0.0.1:40080; 273 proxy_http_version 1.1; 274 proxy_set_header Host $host; 275 proxy_set_header X-Real-IP $remote_addr; 276 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 277 proxy_set_header X-Forwarded-Proto $scheme; 278 proxy_read_timeout 3600s; # For SSE streaming 279 } 280 } 281 ``` 282 283 ### Changing the Claude Model 284 285 Edit `config/agent.yaml`: 286 287 ```yaml 288 agent: 289 default_model: claude-sonnet-4-5-20250929 # Change model 290 thinking_tokens: 8000 # Adjust thinking budget 291 max_turns: 100 # Max conversation turns 292 timeout_seconds: 1800 # Execution timeout (30 min) 293 ``` 294 295 **Available models:** 296 | Model | Speed | Cost | Best For | 297 |-------|-------|------|----------| 298 | `claude-haiku-4-5-20251001` | Fastest | Lowest | Quick tasks | 299 | `claude-sonnet-4-5-20250929` | Balanced | Medium | General use | 300 | `claude-opus-4-5-20251101` | Slowest | Highest | Complex tasks | 301 302 Add `:mode=thinking` suffix for extended thinking mode (e.g., `claude-sonnet-4-5-20250929:mode=thinking`). 303 304 ### Mounting External Directories 305 306 Allow the agent to access host directories by creating `config/external-mounts.yaml`: 307 308 ```bash 309 cp config/external-mounts.yaml.example config/external-mounts.yaml 310 ``` 311 312 Edit the file: 313 314 ```yaml 315 global: 316 # Read-only mounts (agent cannot modify) 317 ro: 318 - name: datasets 319 host_path: /data/ml-datasets 320 description: "ML training data" 321 322 # Read-write mounts (agent can modify) 323 rw: 324 - name: output 325 host_path: /data/output 326 description: "Agent output directory" 327 ``` 328 329 Then rebuild: 330 ```bash 331 ./run.sh rebuild 332 ``` 333 334 The agent can access these at: 335 - Read-only: `./external/ro/datasets/` 336 - Read-write: `./external/rw/output/` 337 338 ### Security Settings 339 340 `config/api.yaml` security section: 341 342 ```yaml 343 security: 344 # Security headers (X-Content-Type-Options, X-Frame-Options, etc.) 345 enable_security_headers: true # Recommended for production 346 347 # Block requests with unexpected Host headers 348 validate_host_header: true # Recommended for production 349 350 # Content Security Policy 351 # "strict" - Restrictive (recommended) 352 # "relaxed" - Allows inline scripts (development) 353 # "disabled" - No CSP 354 content_security_policy: "strict" 355 356 # Additional allowed hostnames (besides server.hostname) 357 additional_allowed_hosts: [] 358 ``` 359 360 ### Environment Variables 361 362 Override settings with environment variables: 363 364 | Variable | Default | Description | 365 |----------|---------|-------------| 366 | `AG3NTUM_API_PORT` | 40080 | API port on host | 367 | `AG3NTUM_WEB_PORT` | 50080 | Web UI port on host | 368 | `AG3NTUM_IMAGE_TAG` | latest | Docker image tag | 369 | `AG3NTUM_UID_MODE` | isolated | UID security mode | 370 371 --- 372 373 ## Troubleshooting 374 375 ### Build Fails with NumPy Error 376 377 **Error:** `RuntimeError: NumPy was built with baseline optimizations` 378 379 This happens on VPS with older CPUs (no SSE4.2). The Dockerfile handles this automatically. Rebuild on the target server: 380 ```bash 381 ./run.sh rebuild --no-cache 382 ``` 383 384 ### Permission Denied 385 386 **Error:** `EACCES: permission denied` or `Permission denied: '/logs/backend.log'` 387 388 Fix directory ownership: 389 ```bash 390 ./run.sh rebuild --no-cache 391 # Or manually: 392 sudo chown -R 45045:45045 logs data users 393 ``` 394 395 ### Cannot Access Web UI 396 397 1. Check containers are running: 398 ```bash 399 docker compose ps 400 ``` 401 402 2. Check logs: 403 ```bash 404 docker compose logs ag3ntum-web 405 ``` 406 407 3. Check firewall (Ubuntu): 408 ```bash 409 sudo ufw status 410 ``` 411 412 4. Verify port is correct: 413 ```bash 414 grep external_port config/api.yaml 415 ``` 416 417 ### Login Fails 418 419 - Use your **email** (not username) to login 420 - Check API logs: `docker compose logs ag3ntum-api` 421 - Verify user was created: check output of create-user command 422 423 ### Docker Daemon Not Running 424 425 **Error:** `Cannot connect to the Docker daemon` 426 427 Start Docker: 428 - **macOS:** Open Docker Desktop application 429 - **Linux:** `sudo systemctl start docker` 430 431 ### Port Already in Use 432 433 **Error:** `Bind for 0.0.0.0:50080 failed: port is already allocated` 434 435 Find what's using the port: 436 ```bash 437 lsof -i :50080 438 ``` 439 440 Either stop that process or change your port in `config/api.yaml`. 441 442 ### Installer Stuck on Clone 443 444 If cloning takes too long: 445 ```bash 446 # Clone manually with verbose output 447 git clone https://github.com/extractumio/ag3ntum.git 448 cd ag3ntum 449 ./install.sh # Will detect existing repo 450 ``` 451 452 --- 453 454 ## Useful Commands 455 456 | Command | Description | 457 |---------|-------------| 458 | `./run.sh build` | Build and start containers | 459 | `./run.sh restart` | Restart (reload code changes) | 460 | `./run.sh cleanup` | Stop and remove containers | 461 | `./run.sh rebuild --no-cache` | Full clean rebuild | 462 | `./run.sh shell` | Shell into API container | 463 | `./run.sh create-user` | Create a new user | 464 | `./run.sh test` | Run test suite | 465 | `docker compose logs -f` | View real-time logs | 466 | `docker compose ps` | Check container status | 467 468 --- 469 470 ## Next Steps 471 472 - **Mount external files:** See [Mounting External Directories](#mounting-external-directories) 473 - **Set up HTTPS:** See [Setting Up HTTPS](#setting-up-https) 474 - **Create more users:** `./run.sh create-user --help` 475 - **Full documentation:** [README.md](README.md) 476 477 --- 478 479 **Questions?** [info@extractum.io](mailto:info@extractum.io)