Proxy Agent is a single container: inside it are both the app and the interface. A PostgreSQL database is required next to it — the request log, the proxy service log and the daily spending totals per key live there. Nothing beyond that is required, so the product can be deployed on your own server in a few minutes.
One container and one database
The container serves both the interface pages and the /api/* addresses programs call. The database is external: it can sit on the same server or on its own. On first start the database creates itself if it does not exist yet — nothing to prepare by hand. That database is the single mandatory setting: without it the app does not start.
The image includes the Xray core — Happ subscription channels run on it. In your own build without the core those channels simply count as unavailable, and the path to your own core is set with the PROXYAGENT_XRAY_PATH variable. The ordinary channels — HTTP proxy, SOCKS5, VPN — do not depend on the core.
The product ships in two builds. In the Russian build (maxpastukhov/proxy-agent, the PROXYAGENT_BRAND=pastukhov variable) the interface opens in Russian by default, until the language is chosen manually; the manual choice always wins. In everything else the builds are identical.
Ports and publishing
- The main port — the interface pages and the model addresses. In the installation examples it is published as
5000:80— 5000 outside, 80 inside. - The proxy service ports — one per channel that you gave a listen port on the “HTTP proxies” page. Until a port is set, nothing listens. Every such port is published with its own line in the startup file — only then is it reachable from outside; the subfolder does not affect these ports.
Hosting in a subfolder
If the product should live not at the domain root but in a first-level subfolder — for example, at your-domain/proxy — there are two ways.
- With an environment variable. Set
PROXYAGENT_BASE_PATH=/proxy— and everything inside works from that folder. Requests arriving at the wrong address are redirected by the product itself, so there is one address instead of two different ones. - With a front proxy. The proxy in front of the app strips the folder itself and passes the product the
X-Forwarded-Prefixheader. The product also stays reachable directly, on its own port at the domain root — a convenient path for diagnostics.
Three addresses in any case always live at the domain root and do not follow the subfolder: /api/ (where programs connect), the health check and the certificate checks. That is by design: clients name the address from the root, and a subfolder must not break it.
HTTPS is configured outside
The container itself speaks only plain HTTP. The secure connection (HTTPS) is configured in front of it — on the front proxy or on the cloud side. That makes certificates easier to rotate, and the product does not need rebuilding.
What matters for the front proxy
The front proxy must pass live connections through (otherwise the chat silently falls back to a less convenient mode), must not buffer the reply, and must not cut long answers short. Practical values: timeouts up to 3600 seconds and a request-size limit of 100 megabytes. Without that, the models’ streaming replies and the chat will break, and large requests will be rejected.
Where the data lives
The data is spread over three places, and they should not be confused.
- Configuration — the files
settings.yml,models.yml,http-providers.yml,keys.ymlandanonymization.ymlin the/project/apps/proxyfolder. Settings, models, channels, access keys and secret-hiding rules live here. It is the single source of truth: the files are edited by hand, from the interface, or through management over the API. Hand edits are picked up in about 300 ms, and a parse error breaks nothing — the last good state stays. Keep the folder under version control: moving it to another server moves the whole configuration. Secret fields can be written as an environment-variable reference like$VARIABLE_NAME. - Working state — the
/apps/proxyvolume: the data protection keys (auth/), the login session signing key (appdata/.jwt-secret), the saved DeepSeek “reasoning” (reasoning_cache.sqlite3), the secret-hiding vault (anonymizer/), the VPN configurations (vpn/) and the working files of Happ subscription channels (happ/). Without the volume you lose the “reasoning” and the secret mappings, and without a persistentJWT_SECRET_KEY— every issued login session. Thehapp/working files restore themselves: the subscription is fetched again on the next use. - Logs and spending — PostgreSQL: the request log, the proxy service log and the daily spending totals per key.
The conclusion is simple: mount both volumes and set the signing key as an environment variable — then recreating the container passes unnoticed.
Backups
A full copy needs three things: a PostgreSQL dump (logs and spending), the configuration folder and the working-state volume. The first two move easily to another server and live in version control; the volume holds the secret mappings, the “reasoning” and the VPN configurations. The working state of Happ subscriptions does not need copying: it restores from the subscription itself.
Next: how access is organized and what is worth doing for security — in the Access & Security section.