Servers

A server is a managed Linux machine where MultiAgent deploys agents and tools. Everything is managed over SSH: MultiAgent runs commands, transfers files and reads container statuses, requiring nothing on the server beyond the base system.

Adding a Server

The “Add Server” button opens the form: name, host, SSH port, user, and authentication — a password or a PEM private key. For connections through a bastion host there is a proxy jump: a separate host, port, user and credentials for the hop.

After saving, the connection status is available: not checked, OK, or an error. The “Check connection” button tests exactly one thing — SSH reachability: whether a session on the server can be opened. Whether the server is ready for deployments is shown by the checks checklist: it names everything that is missing and offers a fix.

Onboarding Checks

The “Server checks” card on the server page opens a checklist: every check is its own row with a green check mark (done), a yellow warning, a red cross (error) or a gray “skipped” mark, and at the bottom a summary — “All checks passed” or “{n} of {m} checks need attention”.

Checklist rows are named after the service’s role, not the product name:

• SSH connection — whether the connection is reachable;
• Docker — installed and running, and whether daemon.json is correct;
• Host folders — the folders for agents, data, home files, projects, tools and temporary files;
• Agent user (agent, 999:999) — whether the account exists with the right uid/gid;
• Nginx — the web server for routing;
• SSL certificate — issued and not expiring (when a secure connection is terminated by an upstream proxy, the check will offer to set the server’s public address);
• Home page — the app card board at the server’s root (checked after Nginx and skipped when there is no Nginx);
• Central login (Authelia) — the mandatory single sign-on service;
• Database (Postgres) — the shared Postgres instance for agents: installed and running;
• Git service (Forgejo) — the built-in Git server;
• Backup service (rsyncd) — the backup container.

When a check shows a “Click here to install it” link (or “create” / “request”) — that is a one-click fix: it starts the same one-step install as the matching tab (Docker, folders, agent user, Nginx, a Let’s Encrypt certificate, Postgres, Forgejo, backups, home page, central login). After a successful fix the checks re-run automatically and the row turns green. A check whose prerequisites are missing (for example, no Docker or Nginx) is marked “skipped” — it does not count and offers no fix link. The central login button never touches the certificate or the HTTPS port — only the service itself.

Some rows wait for your input or a simple action. The “SSL certificate” row with no certificates will offer to set the server’s public address of the form https://your-domain/{slug} when a secure connection is terminated by an upstream proxy — or to request a Let’s Encrypt certificate. A Postgres instance that is installed but stopped is fixed with a start button, not a reinstall: the data is not touched.

What MultiAgent can check and fix:

• SSL certificate — no certificate → a warning with a link offering two paths: set the server’s public address when TLS is terminated by the upstream proxy, or request a Let’s Encrypt certificate (when the host looks like a domain; otherwise it advises making a self-signed one); expiring within 30 days or expired → a warning with no action — enough to renew on the Nginx tab; while no HTTPS port is set, certificates are saved but not served;
• Central login — a mandatory service: not installed → a warning with an install link; installed but not running → a warning and a redeploy;
• Forgejo — an external instance (an address not of our shape) is checked by credentials and offers no install; for the built-in install the address is shown automatically — the public subfolder /forgejo/; an empty card is filled in automatically (login agents, auto-creation of repositories, a generated password); the “Company” field sets the organization where agent repositories are created and from which they are visible;
• Backup service — the check passes only when the container is running and serves all seven modules.
• Postgres — an installed but stopped instance is a warning with a start button (not “not installed”); after starting, the check itself makes sure the saved credentials work.

Installing Docker

If Docker is missing on the server, MultiAgent installs it itself — one button, with the commands streaming into the interface. In the same place you can edit /etc/docker/daemon.json (registry mirrors or logging, for example) — MultiAgent applies the file and restarts the daemon.

For images from a private registry, the server has a Registry Auth setting: the registry user and token MultiAgent uses when pulling agent and tool images.

Server Folders

MultiAgent keeps agent files in several server folders — all configurable, with these defaults:

• Agents folder — /root/agents/docker: one subfolder per agent with its compose.yml;
• Data folder — /root/agents/data: agent data, one subfolder each, mounted into the container at /data;
• Home folder — /root/agents/home: the agent’s home directory inside the container, /home/agent;
• Projects folder — /root/agents/projects: the agents’ git repositories, mounted at /project;
• Tools folder — /root/agents/tools: files of services deployed from the tools library;
• Temp folder — /root/agents/tmp: the agent’s scratch folder inside the container (/tmp/agent) — model caches and anything recreatable land here; it is deliberately excluded from backups.

The single folder structure simplifies backups: all data of all agents on the server lives in one directory tree. Servers you created earlier keep their old paths — MultiAgent moves nothing on the host.

Shared Server Environment Variables

When the same environment variable must be set for every deployment on a server (a time zone or log verbosity, for example), you set it once in the server’s settings — it lands in the configuration of every agent and app on that server. A value set on a specific agent always wins over the shared one: that is how you make an exception for a single deployment. Details on the Agents page.

Shared Postgres

Instead of a separate SQLite database per agent, you can run one shared Postgres on the server: MultiAgent deploys the docker-compose container (port 5432 by default), saves the password and checks the connection. For agents with Postgres enabled, the AGENT_DATABASE connection string is injected into their environment automatically.

The Forgejo Git Server

MultiAgent deploys Forgejo on the server — your own Git server (internal port 3200). It is reachable at the /forgejo/ subfolder on the server’s domain, and MultiAgent shows the address by itself — no need to type it in. For every agent you can link an existing repository or create a new one; MultiAgent issues and stores the SSH keys for access. If you set an organization in the “Company” field, all new agent repositories are created inside it (created automatically when missing), and repository lists show its contents. Details in the Agents section.

Backups

Onboarding installs an rsyncd container on the server with seven read-only modules covering all server folders: docker, home, data, projects, tools, plus two dump modules — postgres and forgejo. The tools module takes what no other module serves: nginx certificates, central-login state and tool compose files; its own postgres/backup and forgejo/backup subfolders are excluded from the upload — those dumps are served by their own modules, so a full download does not copy them twice. Postgres and Forgejo dumps are produced on the server itself (third-party containers drop them into the backup folders). Backups are pulled from the server by your client machines over rsync — for example, a nightly job on the machine with the backup storage:

rsync -avz rsync://backup@server-host:873/data/ /backups/server-host/data/

Ready-to-run commands for downloading all seven modules (Linux and Windows) are collected in the Backup tab of the server page — run them as they are. The server can only pass the backup check when the container is running and serving all seven modules; if one is missing, the check points at a reinstall.

Nginx Routing and Certificates

MultiAgent itself never routes requests: every server runs its own Nginx container (agents-nginx, image nginx:alpine), installed and updated from the Nginx tab of the server page. The routing configuration is a projection of the database: it is rebuilt and applied automatically on every change (create an agent, product or tool — it immediately gets its own subfolder). Applying happens without dropping connections: the configuration is validated and reloaded inside the already running web server, so open pages and live chats do not break.

• Five kinds of routes — agents and products (read-only), tools with a web interface (read-only), extra links of agents and products (read-only: a subfolder with a port from the “Links” tab), custom routes to any http(s) address (the only manually managed kind: edit, disable, delete) and, when the central login is installed, its derived auth route (read-only, with no protection toggle);
• One namespace — a first-level slug of [a-z0-9-]+ per server for all kinds; MultiAgent’s system paths (api, agents, servers, data and others) are reserved;
• Internal container network — apps are addressed by container names on the shared docker network; a crashed service returns 502 only on its own subfolder, the other routes keep working.

Certificates — three kinds from the same tab: self-signed (becomes the fallback certificate), your own PEM pair, and Let’s Encrypt (ACME through Nginx itself, staging and production CAs, one request at a time). Certificates and keys are stored only on the server — the database keeps just metadata. Expiry is tracked on every configuration update (renewal 30 days before expiration). The HTTPS port is optional: while it is empty, certificates are saved but not served and only HTTP is published. A Let’s Encrypt request with an empty port enables it by itself (443), so the issued certificate is served immediately; a port you have chosen, or an explicitly disabled HTTPS, is never overridden. In local secure mode all HTTP (including route subfolders) is automatically redirected to HTTPS, except the ACME validation path; when the server sits behind an upstream reverse proxy that terminates TLS, the HTTP listener keeps serving routes as usual. Immediately to the right of the Nginx tab sits the Authorization tab — the central login install (see below).

Server Home Page

At the server’s root you can publish a home page — a card board from which every app on the server opens. It is a static board: MultiAgent builds the file itself and uploads it to the server, and nginx serves it at the root. No separate container is needed — the installed Nginx is enough; the page has no login of its own, and when the central login is on, it closes together with the other apps.

MultiAgent maintains the cards from its database: one card per agent, product and tool with its address — with the projects’ real logos, and agent and app cards show badges of their extra links in the corner (the “Links” tab). When Forgejo is installed on the server, a Git card appears on the board, and the last card is always “Sign out”: it ends the central-login session, signs out of all agents and products (their tokens are deleted) and of the page itself. The board refreshes itself on every change — deploy an agent or a tool and its card appears; the tab offers a manual apply too. The page’s label language is chosen in the tab: English or Russian, defaulting to the language of MultiAgent itself.

Details on the Server Home Page page.

Central Login (the “Authorization” Tab)

So that a visitor signs in once and gets access to any protected app on the server, you can install the central login on the server — it is the “Authorization” tab (Authelia), sitting right of the Nginx tab. The login is a service container agents-auth with the fixed slug auth and portal address /auth/; it publishes no port of its own, so Nginx is installed first. The login is agents, the password is generated automatically and visible in the tab; the install never touches the certificate or the HTTPS port.

When the central login is active, agents and products are locked “behind the central login” by default, and tools with a web interface and custom routes — at your choice (a toggle). One login on the login page opens every protected app on the server — no repeated sign-ins.

The protection works only over a secure connection (HTTPS): either a local certificate and HTTPS port from the Nginx tab, or an address template of the form https://{serverHost}/{slug} when TLS is terminated by the upstream reverse proxy (then no certificate of your own is needed). Otherwise the installed login stays inactive. Reaching an app directly at host:port, bypassing nginx, is not locked — the app keeps its own login. Service machine paths /{slug}/api/… and /{slug}/svelteChatHub also stay open (they have their own JWT or API-key authorization). Apps receive identity headers and the X-SSO-Token secret (checked against SSO_PROXY_TOKEN in the agent’s environment), so they cannot be forged from outside.

The auth slug is reserved on every server — you cannot create an agent, tool or route with that name. Forgejo can be connected to the central login (a toggle on the Forgejo tab): its login page gets a sign-in-through-central-login button, and new users register automatically from the central-login identity; it disconnects the same way. Deleting the central login reopens the protected routes, and its data and secrets are kept — a reinstall reuses them. More about routes and protection in the Nginx Routing section.

The Agents URL Template

Agents are addressed through a URL template with the {slug}, {host} and {port} placeholders. When the template has the form {base}/{slug}, its base becomes the server’s public base — and every app’s public address is shown as {base}/{slug}/ (the scheme comes from the template, so a server behind an external proxy gets https links without a certificate of its own). Direct access at http(s)://{host}[:{port}] remains the fallback path. Changing the URL template or the server name starts a background rebuild of the nginx routes and also syncs the central-login configuration with the new address.

https://apps.example.com/{slug}

File Manager

Every server has a built-in file manager: browse the directory tree, read and edit files, upload and download, rename in place, and count size and tokens of text files. It lets you fix a config or look at logs on the server without leaving MultiAgent.

The separate “File Manager” page shows two panels — each with its own server and its own folder. Tick files and folders in the left panel and press “Copy” — they move to the right panel’s folder. The panels can look at one server or at two different ones: MultiAgent itself transfers the files between servers over its own saved accesses — nothing to configure between servers. The transfer runs in the background, the progress percentage is visible right in the button, and the process can be canceled; files with the same name are replaced, folders with matching names merge. While the copy runs, the right panel refreshes itself, so arriving files appear in place.

Next to it is the “Terminal” button: it opens a command line in the folder you are currently in. Commands run on the server, output streams to the screen line by line, and command history and interrupt work as usual. Handy for a quick look at a service’s state or sorting out file permissions.

Handing a Server to a Client

When a server belongs to a client, you can hand management over: the client’s own MultiAgent is deployed on the server, and the records move to it — agents, apps, tools, routes and access keys. The handover is a one-time operation: it starts from the “Handover” tab on the server page, and a preview shows in advance what moves and what stays with you. Running apps are not touched: nothing stops or reinstalls.

After the handover, routing is managed by the client’s instance, while the server itself stays with you: SSH access, checks, folders and Docker cleanup. You can peek into the client’s instance with the “Manage” button in the page header — the sign-in happens by itself, no password needed. Details on the Server Handover page.

← Back to documentation