Remote server behind a reverse proxy

1. How it works

The local server runs on the remote computer as a service, listening only on 127.0.0.1. In front of it, on the same computer, a reverse proxy (for example, Caddy) is the only way in from outside: it encrypts the connection with HTTPS and requires its own key. It recognizes ZeroChat's requests and passes them to the local server; everything else can still go to other services, such as the model server.

There are two independent barriers:

• The proxy key decides who reaches the computer. Without it, the proxy lets nothing through.
• The system account decides who uses ZeroChat. The local server does not trust the proxy: every request needs the daily token, and getting it requires signing in with the user name and password of the account running zerochat.

Compared with the SSH tunnel, there is no SSH client or open session to keep, and it works the same from a phone, a tablet or another computer.

2. Prepare the remote computer

The local server as a service

Start zerochat with your user, from the project directory, without opening the browser and without stopping when the tab closes:

zerochat --no-browser --keep-server

• Listens only on the computer itself: do not use --host with a public address; the proxy is the only way in from outside.
• The account matters: the account that starts zerochat is the one that signs in from the browser, and its permissions are the tools' permissions.
• No heartbeat: with --keep-server the page sends no periodic heartbeats; it rereads the server state when you return to the tab.

The reverse proxy

The proxy has to do three things:

1. Serve HTTPS with a certificate the browser accepts, because the interface loads from GitHub Pages over HTTPS and the browser blocks unencrypted connections to other computers.
2. Check its key and pass ZeroChat's requests to the local server on the same computer.
3. Allow the CORS preflight checks the browser makes before each request, which do not carry the key.

The local server does not need the proxy key: it is best if the proxy does not forward it.

3. Connect from the browser

1. Open ZeroChat and open the Connection panel (the plug icon next to the settings wheel in the sidebar).
2. Turn off Local connection and enter the proxy address as the local server URL: only the protocol, name and port, for example https://my-server:12345.
3. Turn on Use proxy, enter its key and press Connect.
4. Sign in with the user name and password of the account running zerochat on the remote computer.

• What is stored: the URL and the proxy key stay in the browser configuration; the daily token in its session cookie. The password is never stored.
• The key only goes to its destination: it is sent only to the configured URL. If you open a local zerochat in the same browser, that connection does not receive it.
• Global setting: the connection is not part of the profiles; profiles still choose the model, their MCP services and their browser.

4. Sign-in and security

• Daily token: it expires at midnight even with the server running. The page then asks for the user name and password again; the server and its commands carry on.
• Limited attempts: after 5 failed attempts in a row, zerochat rejects the next ones for 15 minutes without checking them.
• System account lockout: if the computer locks the account after several failures (for example, with pam_faillock), set that limit above zerochat's. Otherwise, a few failed attempts from the web could also lock the local login.
• Signed tools: each tool call is signed for that session and expires within seconds, even if someone sees the request go by.

5. Common situations