Deployment

Run Studio locally or behind a reverse proxy.

Deployment

Near's default is local agx serve. Treat remote/HA as an extra path, not the product default. There is no agenticx.server:app module — the FastAPI app is create_studio_app() in agenticx.studio.server.

Diagram: clients hit agx serve; optional Nginx; state stays in ~/.agenticx.

Local API server

bash

1agx serve --host 127.0.0.1 --port 8000
2# Desktop-managed starts also write ~/.agenticx/serve.port and serve.token

Flag	Default	Notes
`--host`	`0.0.0.0`	Prefer `127.0.0.1` on a laptop
`--port`	`8000`	Near may pick a random port and persist it
`--token`	empty	Sets `AGX_DESKTOP_TOKEN`
`--reload`	false	Dev only

agx studio is the terminal REPL, not this HTTP process.

Docker (example)

Compose files exist under deploy/ (docker-compose.minimal.yml, docker-compose.core.yml, docker-compose.yml). Use them when you deliberately want Postgres / Redis next to Studio. They are not required for Near on a laptop.

dockerfile

1FROM python:3.11-slim
2WORKDIR /app
3RUN pip install agenticx
4EXPOSE 8000
5CMD ["agx", "serve", "--host", "0.0.0.0", "--port", "8000"]

bash

1docker compose -f deploy/docker-compose.minimal.yml up

Reverse proxy

SSE needs HTTP/1.1 and an upgraded connection. Point the proxy at the actual Studio port (see ~/.agenticx/serve.port).

nginx

1location / {
2    proxy_pass http://127.0.0.1:8000;
3    proxy_http_version 1.1;
4    proxy_set_header Upgrade $http_upgrade;
5    proxy_set_header Connection "upgrade";
6    proxy_set_header Host $host;
7    proxy_buffering off;
8}

Probe

bash

1curl --noproxy '*' http://127.0.0.1:8000/api/health
2# {"status":"ok"}

Provider health is GET /api/health/providers and requires the desktop token when one is set.

What this page is not

Enterprise Go Gateway (separate process, OpenAI-compatible relay)
A cluster Agent Runtime (planned)
uvicorn agenticx.server:app --workers N (that module does not exist)

See Studio, Configuration, CLI.