Server v2
Requirements
Python 3.12+, MySQL, and Node.js 22.12+. Complete the source setup first. Redis is not a Server v2 startup dependency.
Start
Run from the checkout root with the Python environment active:
python -m pip install -e '.[server-v2]'
cp app/v2/server/.env.example app/v2/server/.env
Set SAGE_SERVER_MYSQL_URL, your own SAGE_SERVER_JWT_SECRET (at least 32 bytes), and initial administrator credentials in app/v2/server/.env.
cd app/v2/server/web
npm install
npm run build
cd ../../..
python -m app.v2.server
Open http://127.0.0.1:8090. Configure a model and an Agent after login. /studio manages Agent packages; /docs exposes the running server’s OpenAPI.
For frontend development use npm run dev in app/v2/server/web; Vite proxies to port 8090. Process environment variables override the component .env file.
Startup idempotently upgrades legacy tables: it adds missing threads.agent_id and expands Skill descriptions to LONGTEXT. The database account needs ALTER privileges for these upgrades. Reimport original Skill files to repair descriptions previously truncated in the catalog.
Storage and deployment boundary
- MySQL stores users, catalogs, thread indexes, Agent package inventory, and runtime Sessions.
- AG-UI replay reads canonical RuntimeEvents from Sage Sessions, not a separate Redis event log.
- Workspace files live under the configured data root’s tenant directories.
- Run one worker. The built-in SessionStore rejects a second writer; the Scheduler and JobRuntime do not supply multi-host durability.
deploy/ contains several stacks. Inspect the image and module used by a Compose environment before treating it as a Server v2 deployment.