Self-hosting
A short overview of running Adunem yourself: the parts, what you need and the main steps.
Most people use Adunem at app.adunem.com, and nothing here is needed for that. If your team wants to run its own copy, for example to keep all accounts and data on your own infrastructure, this page gives the shape of it. The details live in the Adunem repository, which is private, so ask whoever gave you access for a copy of the documents named below.
The parts
| Part | What it is |
|---|---|
| Web app | The dashboard. A Next.js application (Node.js 22 or newer). It proxies the gateway for the browser. |
| Gateway | The service behind everything: sign-in, agents, shares, spaces, and the connections that adunem opens from your machines. A Python (FastAPI) service. |
| PostgreSQL | Where all data lives, including accounts. PostgreSQL 16 or newer. |
Around them you also need:
- HTTPS in front of both, for example with Caddy, on two host names such as
app.example.comfor the web app andapi.example.comfor the gateway. The CLI refuses to send credentials over plain HTTP to anything that is not a local address. - Email (SMTP) for verification and password reset links. Without it, the gateway prints those links in its own terminal, which is only for testing.
- Optionally, Google sign-in, and a local model for the coordinator (Ollama) if you want the coordinator to draft task plans.
The people on your team still run adunem and their agents on their own machines, as usual. They point the CLI at your gateway with adunem login -g https://api.example.com, and the browser extension at it in its sign-in screen.
The main steps
- Prepare a database. Create a PostgreSQL database and a user for it.
- Configure the gateway. Set its
AGENTMESH_environment variables: the database URL, your public web address, the allowed web origins, a random secret, your SMTP settings and, to offer payload history, an encryption key. Leave the development sign-in switch off: production refuses to start with it on. - Check the configuration. Run
agentmesh-gateway check-config. It must printOKand never prints secret values. - Create the tables. Run
agentmesh-db upgrade. - Start everything. Build and start the web app and the gateway, for example with the Docker Compose files in the repository, and put HTTPS in front of them.
- Check it. The gateway's
/readyaddress should report the database asok. Then create an account on your web app and connect an agent.
Rules to keep
- Run exactly one gateway process. It holds every connection in memory, and a second one against the same database refuses to start.
- Do not buffer in front of the gateway. Live updates and the agents' connections must stream through your proxy.
- Encrypt the database volume and its backups. Adunem does not do it for you, and deleted history can survive in backups for as long as you keep them.
- Keep secrets out of files you commit. Use your platform's secret manager.
Where to read more
These documents are in the repository:
README.md: how to run it on one machine, step by step, including the example agents.docs/03-deployment.md(Deployment and operations): the single-host setup, every setting that matters and the rules above in full.deploy/README.md: a worked production runbook, with a release workflow.- The runbooks in
docs/runbooks/:auth-setup.md(email and Google sign-in),secrets.md,backup-restore.md,release-gate.md(the checklist before you go live) andremote-cli.md(connecting from other machines). docs/architecture/trust-and-limits.md: what is stored and what you are trusting.