Run a server gateway
Deploy the web panel, gateway, and PostgreSQL as an independent installation.
A server gateway keeps agents available independently of the desktop app. Use it for messaging channels, always-on schedules, or one agent installation accessed from several devices. The desktop's local gateway does not require this setup.
Requirements
For the repository's commands, install Git, make, Node.js 24+, pnpm 11, Docker, and Docker Compose. make setup calls the Node setup script through pnpm; Docker alone is not enough for that command.
The published Compose stack includes:
web:ghcr.io/lucasaarch/jian-web.gateway:ghcr.io/lucasaarch/jian-gateway.postgres: PostgreSQL 17 with a persistent database volume.
Use matching gateway and web image versions. Model providers and integrations remain separate services that you connect after installation.
Start the stack
git clone https://github.com/lucasaarch/jian.git
cd jian
make setup
make up
make psmake setup generates credentials and encryption configuration in .env, with mode 0600, without printing secrets. make up starts the published images and waits for their health checks. It does not build the desktop application.
The panel is available at http://127.0.0.1:4310 on the server by default. Sign in using the host token stored as JIAN_API_TOKEN in that installation's .env. Read it privately; do not paste the file into a support issue.
To inspect it through SSH from another computer, a local tunnel can forward the published web port:
ssh -L 4310:127.0.0.1:4310 mira@server.example.comThen visit http://127.0.0.1:4310 on the computer running the tunnel. This is useful for initial administration; standalone Remote workers need an HTTPS gateway address.
Understand the published port
host 127.0.0.1:4310 → web:3000 → gateway:4310 → postgres:5432Only web publishes a host port. PostgreSQL and the gateway communicate over the Compose network. JIAN_BIND_ADDRESS and JIAN_BIND_PORT change the published web binding; they are distinct from the gateway's internal HOST and PORT.
Do not route the public site directly to PostgreSQL or mistake the internal gateway port for the panel. /ui/ on a raw gateway is a notice that the panel moved.
Put the panel behind HTTPS
Configure your reverse proxy for a public address such as https://jian.example.com, forwarding to the web service's published port. The same address serves the panel, /v1, /health, and /openapi.json.
Preserve streaming responses: avoid buffering event streams and allow long-lived requests. Configure forwarded client/scheme information consistently with the gateway's trusted-proxy policy. See configuration for JIAN_TRUSTED_PROXIES and the optional explicit JIAN_PUBLIC_URL.
The default bind is loopback. If your reverse proxy runs in another container, give it a deliberate network path to web; blindly changing the bind to all interfaces is not necessary for every deployment.
Verify the layers
curl --fail http://127.0.0.1:4310/web/health
curl --fail http://127.0.0.1:4310/health
curl --fail http://127.0.0.1:4310/openapi.json -o jian-openapi.json/web/health checks the web service. /health is forwarded to the gateway and reports its mode and, for published builds, version. Neither probe proves that a provider credential works or that a channel can deliver a message.
After signing in, connect a provider, select model defaults, create an agent, and send a small request. Then connect the desktop using Remote gateways, or install Jian Remote on machines it should operate.
Daily operation
make ps
make logsmake down stops the stack while retaining named volumes. Deleting volumes is a separate destructive operation; do not use volume removal as a routine restart.
Before upgrades, follow Backups and upgrades. For multiple gateway processes, JIAN_ROLE exposes API/worker roles, but the default all topology is the complete starting deployment. Splitting roles requires deliberate shared storage and workspace design; changing the variable alone does not build a highly available installation.