Start Guide

Getting started with Agency Server

agency-server is the Docker Compose host for the agency-django package. Together with agency-ui (Vue source, published into the package), it runs the full stack.

For multi-repo layout and philosophy, see agency-workspace (submodules under one folder) and Architecture.

Prerequisites

Docker and Docker Compose (on WSL2, set DOCKER_HOST to the Docker Desktop socket if needed — see Workspace)
Git
(Optional) Node ≥ 20.19 for UI source work in agency-ui

Installation

Open the co-dev workspace (siblings):

agency/
  agency-django/
  agency-server/   ← this repo
  agency-ui/

Prefer the umbrella helper from agency-workspace:
```
./dev up
```
Or from agency-server:
```
./dev up
# equivalent: docker compose up   (foreground; add -d if you want detached)
```
Boot scripts run migrate, collectstatic, and seed defaults (superuser, workspace, Ollama / OpenAI / FAL providers, curated ChatGPT models).
Access the application:
- Product SPA: http://localhost/ (login: http://localhost/login/)
- Admin: http://localhost/admin/
- API / OpenAPI: http://localhost/api/
- Docs: http://localhost/static/documentation/

Core concepts

Domain concepts: Agent, Mission, Execution, Thread, Run, Checkpoint, Interruption.

Glossary: Concepts
Tutorials: Tutorials (first Agent, Mission, HITL)
Package README: sibling agency-django/README.md

Services overview

django (WSGI): HTTP / REST / admin / product SPA shell at /
asgi: WebSockets (/channel/)
Celery (work / beat / flower): background transport
nginx: reverse proxy and /static/
PostgreSQL, Redis, plus reference ChromaDB / Ollama

UI development

Edit Vue/TS in agency-ui (npm run dev against the stack). Publish with umbrella ./dev ui or npm run build:django, commit dist in agency-django, then collectstatic.

Canonical checklist: DEVELOPMENT.md (this repo) and sibling agency-ui/DEVELOPMENT.md. UI / WebSocket contracts: Connections, UI.