A factory is the place where your agents are assembled and run: it has its own deployment slug, a shared container network, folders, a Postgres database, a Git server, an Nginx web server with the routes, a home page, a login and backups. The factory itself is deployed on a machine — a server: its connection is configured separately and can serve several factories at once. That is why several independent factories live happily on one machine — their networks, folders and services never cross.
Adding a Factory
The “Add factory” button opens a form: the server (an existing one from the list, or “New server…” — then the machine is added along the way), the name and the deployment slug. Everything else is configured later on the factory page, on the “General” tab.
The slug is a short name (agents by default) that separates this factory from the others on the same machine. The whole deployment is assembled from it: the docker network’s name ({slug}), the container-name prefix ({slug}-…, for example agents-nginx) and the folder roots (/root/{slug}/…). Two factories on one machine cannot be given the same slug — saving is rejected with a hint. The slug is changed on the “General” tab and affects only new deployments: running containers keep their old names, and nothing moves on the disk.
Here you can also assign the factory to a fleet right away — that is optional. The assignment puts all the agents and apps of the factory into the fleet, and the ones created later join by themselves. Details are on the Management page.
The Factory Card
At the top of the page sits the factory card with its name, the machine address and the connection-state badge. To the left of the badge go the live load figures: the CPU load, the memory used and the disk space taken by all of this factory’s containers. The numbers refresh by themselves every five seconds, and hovering over the occupied space shows how much data the containers have read and written. While the first measurement is running, a loading icon stands where the numbers would be; if a poll fails, the last known numbers stay in place — the numbers do not disappear. Next to the figures is the “Hardware stats” icon: it opens the machine’s own page with its cores, memory, disks, load and charts.
The same card holds a row of actions. “Check and fix” opens the readiness checklist (about it below), “Manage” is shown when the factory has a MultiAgent of its own deployed, and opens it in a new tab without a password. “Copy login”, “Copy password” and “Login link” are visible only while the central login is installed — those are the same credentials for signing in to the factory. The “Files” button with its caption opens access to the factory’s folders, and deleting the factory sits at the far right of the row.
“Login link” puts a one-time link on the clipboard that takes a person to the factory panel without a password. Every click issues a new link, while earlier ones keep working until they expire — you can calmly send the link to several people. If the home page is not installed yet, the button says honestly that it must first be installed on the “Home page” tab; if the central login is missing or protection is off, it reminds you that the link needs the central login behind a working HTTPS gate.
There is no separate card with the list of agents on the page any more — an extra copy of what the navigation tree already shows. The rows are created from the factory row’s menu, and “Import agents” has moved into the operations row of the “Status” tab — right next to “Add key”.
The General Tab
The “General” tab is the factory’s passport: everything MultiAgent builds the factory’s deployment and public links from is set here.
- Name — how the factory is called in the interface;
- Icon — by default the factory carries its own MultiAgent mark (a flag on a stand in the brand gradient). Your own icon is picked by clicking the avatar in the header or the button on this tab: the shared icon gallery with search opens, holding the “Default icon” row that brings the MultiAgent mark back. The chosen icon is drawn in the brand gradient everywhere: in the navigation tree, in the factories list, in the header and on the home page;
- Slug — the same field set at creation: it defines the network, the container-name prefix and the folders;
- Server — which machine the factory lives on. Changing the server moves the connection: all operations and links switch to the new machine;
- Brand — it decides which agent images are chosen and the home page’s language. Already-deployed agents keep their image;
- Public address and agents address template — how the factory’s public links are built (more in the “Agents URL Template” section);
- Licence — which licence this factory’s agents receive: the chosen licence is assigned automatically to every agent and app deployed or recreated here. The same list can keep “None” or issue a new licence;
- Fleet — the card header shows, next to the name, the chips of the fleets the factory belongs to and the “+ Fleet” button with check marks for a quick pick. Checking this factory in a fleet’s dialog puts all of its agents into the fleet — including the ones that appear later. Unchecking takes out those who got there through the factory, while agents added by hand stay: a fleet keeps two separate lists — factories and agents.
The Row Menu
A right-click on the factory row in the navigation tree (or the three-dot button) opens the actions menu. Besides “Open” and “Add agent”, it carries:
- “Deploy” — raises at once all the factory’s rows that have no container yet: first the agents, then the apps, one by one. The item is visible only while such rows exist, and it starts the work in the task queue: its log opens in the “Tasks” section, where the work can also be stopped (a row that has already begun deploying is seen through to the end);
- “Recreate smoothly” and “Recreate forcefully” — for all deployed rows. The smooth recreation waits for quiet in the chats, the forced one interrupts active chats and at the end removes the unneeded Docker images by itself — there is no separate “Docker cleanup” click to make;
- “Update smoothly” and “Update forcefully” — the same thing, only lighter: files and settings are not re-rendered, only the new image is pulled and the container is recreated when the image has actually changed. A factory-wide update works as one batch and does not clean up images after itself;
- “Copy factory” — puts the whole factory on the clipboard as one definition: its fields, icons, folders, compose templates, service passwords and keys, the server connection and all of its agents and apps;
- “Copy agents” and “Paste agents” — carry whole row definitions through the clipboard: this is how you build the same factory somewhere else;
- “Move agents” — moves the factory’s whole population to another factory;
- “Erase agents” — removes all the factory’s rows. The factory itself, its Nginx, Postgres and tools stay in place.
The root “Factories” row of the tree carries the same two recreates and two updates in its menu, plus “Add factory” and “Paste factory”. Recreates and updates run over every factory visible in the tree: with a fleet picked in the header, the work covers only its agents.
Copying and Pasting a Factory
“Copy factory” and “Paste Factory” are the fastest way to build the same factory on another machine or for another client. The whole factory is copied as it is: its fields, folders, compose templates, Nginx ports, shared variables, the Postgres, Forgejo, backup and login cards, and all of its agents and apps. Passwords and keys land in the copy in plain text — treat the clipboard as carefully as you treat passwords.
Pasting asks for a confirmation and shows in advance what you get: the factory’s name and how many agents it will hold. The slug is checked on the target server — a taken one gets a number appended. The server is matched by its own details: two factories copied from one machine stay on one server record instead of creating two. All rows are created undeployed — the containers need starting from their pages, just as after a normal create.
Onboarding Checks
The “Check and fix” action 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 machine is reachable;
- Docker — installed and running, and whether
daemon.jsonis 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 the secure connection is provided by an upstream proxy, the check suggests setting the factory’s public address);
- Home page — the card board at the factory’s root (checked right 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 the agents: installed and running;
- Git service (Forgejo) — the built-in Git server;
- Backup service (rsyncd) — the container for backups.
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 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’s 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 suggests setting the factory’s public address of the form https://your-domain/{slug} when the secure connection is provided by an upstream proxy — or requesting a Let’s Encrypt certificate for the same address. 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 factory’s public address when TLS is terminated by an upstream proxy, or order a Let’s Encrypt certificate (the domain is taken from the machine’s address when it is a domain and not an IP, otherwise from the factory name when it looks like a domain; if neither fits — the advice is a self-signed one); expiring within 30 days or already expired — a warning without an action, renewing it on the Nginx tab is enough; while the HTTPS port is not 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 redeployment;
- Forgejo — an external instance (an address of a different shape) is checked by its credentials and is offered no install; for the built-in installation the address is derived by itself — the public
/forgejo/subfolder; an empty card is filled in automatically (theagentslogin, automatic repository creation, a generated password); the “Company” field sets the organization the agent repositories are created in and seen from; - Backup service — the check passes only when the container is running and serving all seven modules.
- Postgres — an installed but stopped instance is a warning with a start button (not “not installed”); after the start the check makes sure on its own that the saved credentials fit.
Installing Docker
If Docker is missing on the machine, MultiAgent installs it itself — with one button, streaming the command output into the interface. The output shows every line of the command in full, together with the errors: a machine without curl gets the script downloaded through wget, and a failed install ends with the real reason and the installer’s exit code, not a “docker: command not found” message. The same place lets you 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 factory has a Registry Auth setting: the registry user and token MultiAgent uses when pulling agent and tool images.
Factory Folders
MultiAgent keeps agent files in several folders on the machine — all configurable, with these defaults built from the slug:
- Agents folder —
/root/agents/docker: one subfolder per agent with itscompose.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) — temporary model files and anything recreatable land here; it is deliberately excluded from backups.
All the defaults are assembled from the deployment slug: agents is replaced by the slug itself. The slug is set when the factory is added and changed on the “General” tab; it also gives the shared docker network its name and the container names their prefix. A slug change affects only new deployments: running containers keep their old names, and nothing moves on the disk.
The single folder structure simplifies backups: all data of all agents of the factory lives in one directory tree. Factories you created earlier keep their stored paths — MultiAgent moves nothing on the machine.
Ports Are Closed by Default
A new agent, app or tool comes up with a private port: it does not answer from the outside and is reachable only through that factory’s nginx — via its subfolder — and from the machine itself. That is how deployments on one computer stay invisible to each other: even when several factories of MultiAgent live on one machine, one’s ports are open neither to the others nor to the internet.
To open a port to the world, flip its “Public port” switch — the Ports tab of an agent or an app, the port row of a tool. Two ports are always public and have no switch: nginx’s own HTTP/HTTPS — the front door to all the factory’s apps — and the backup service port, through which other machines pull backups from the factory. The shared Postgres, on the contrary, is always closed.
A link to an app with a private port points at its address through nginx, not at the direct http://{host}:{port}: the browser could not reach the direct one anyway. MultiAgent itself manages such apps over its own secure channel to the machine, so closed ports never get in the way of chats or checks.
Shared Factory Environment
When the same environment variable must be set for every deployment on a factory (a time zone or the log verbosity, for example), you set it once in the factory’s settings — it lands in the configuration of every agent and app on that factory. A value set on a specific agent always wins over the shared one: that is how you make an exception for a single deployment. The list rows are sorted by the variable’s name, so the one you need is easy to find. Details on the Agents page.
Variables the Agent Sets Itself
The same shared list can be changed by the agent itself — right from a chat. Its interface has a “Container” card with a “Global Variables” button: type in the key and the value (or ask the agent to do it), press “Save and Restart” — and half a minute later the variable works for every agent and app of the factory. No signing into MultiAgent, no editing configuration, no SSH onto the server.
- The agent does not edit itself — it only files a request into its own
globalfolder, and MultiAgent picks it up and applies it. One dialog in a chat therefore gives the agent no rights over the whole infrastructure; - Merging goes by key — the shared list is never wiped: new keys are added, matching ones are replaced, and a line with an empty value removes the key;
- Values are taken as they are — no
$VARIABLEexpansion and no quote stripping; - The agent’s own wins over the shared — a variable of a specific agent or app is never overridden by the factory’s;
- A change recreates the factory’s agents and apps — a short downtime, so it is best to enter everything you need in one go. Writing the same value again does nothing;
- If the factory is not managed from outside, the dialog warns honestly: “This deployment is not managed externally — nobody will pick up the requests written here”.
The point: a new service’s key is added once and becomes shared immediately — no walking dozens of agents by hand and no remembering where which key is written.
Shared Postgres
Instead of a separate database per agent, you can raise a shared Postgres on the factory: MultiAgent deploys the docker-compose container (port 5432 by default), stores the password and checks the connection. If the port is taken by someone else’s service at that moment, the install takes the next free one by itself and repeats the deployment — up to two retries, no manual reinstall needed. 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 factory — your own Git server (internal port 3200). It is reachable at the /forgejo/ subfolder on the factory’s public address, and MultiAgent derives and stores that 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.
Forgejo ties itself to the central login: there is no separate switch. As soon as the login is installed, protection is working and Forgejo is running, its login page gets a sign-in-through-central-login button, and the administrator’s login and password follow the central-login credentials — the Forgejo tab has a “Sync authorization” button for that. The login and password fields on this tab are therefore read-only: they are edited on the “Authorization” tab. The Forgejo interface speaks the brand’s language — English on an English brand.
Backups
Onboarding installs an rsyncd container on the factory with seven read-only modules covering all the factory’s 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. The Postgres and Forgejo dumps are produced on the machine itself (external containers drop them into the backup folders). Backups are pulled from the factory by your computers 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 download commands for all seven modules are collected in the “Backup” tab of the factory page — they run unchanged. There are three clients: a script for Linux, an archive for Windows (rsync itself is already inside) and a file for a Docker host: it is enough to drop it into an empty folder and run docker compose up -d — from then on the copies are taken by themselves, at the start and then every day on a built-in schedule, with the log written next to the copies. In all three, the address, port, user and password are already filled in, and the download files are named after the factory — backup-<name>.zip, backup-<name>.sh and backup-<name>.yml — so copies of several factories on one machine do not get mixed up.
When there are several factories, there is no need to walk them one by one: the “Backup” page in the Assets section hands out the same client for the whole fleet scope chosen in the header at once. One run walks every factory in the scope and puts each into its own folder (~/backups/<name>, c:\backup\agents\<name> or ./backups/<name>), and a factory without a server address is honestly named as skipped.
The “Test connection” check looks at everything at once: is the container running, does it serve all seven modules (whatever is missing is named), does the published port match the saved one, and does the port accept a connection from the outside. Everything found is listed in one list, and beside it stands a “Reinstall rsync” button — it reinstalls the service from scratch and returns it to a working state.
Nginx Routing and Certificates
MultiAgent itself never routes requests: every factory runs its own Nginx container (named {slug}-nginx, agents-nginx by default), installed and updated from the Nginx tab of the factory page. It is the Debian build of nginx (nginx:1.31), not Alpine: it runs on old kernels where the Alpine build fails to start. 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
authroute (read-only, with no protection toggle); - One namespace — a first-level slug of
[a-z0-9-]+per factory for all kinds; MultiAgent’s system paths (api,agents,factories,servers,management,dataand 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). The domain for a Let’s Encrypt certificate is taken from the machine’s address when it is a domain and not an IP; if the address is an IP or has no dot, the factory’s name is taken (when it looks like a domain). Certificates and keys are stored only on the machine — 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 the local secure mode all HTTP (including the route subfolders) is redirected to HTTPS automatically, except the ACME check path; when the factory sits behind an upstream reverse proxy that terminates TLS, the HTTP listener keeps serving the routes as usual. Immediately to the right of the Nginx tab sits the Authorization tab — the central login install (see below).
The Factory Home Page
At the factory’s root you can raise a home page — a card board from which every app on the factory opens. It is a static board: MultiAgent assembles its file itself and uploads it to the machine, and nginx serves it at the root. No separate container is needed for it — 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. At the top the board carries its own mark and the “Agent Factory” heading, the cards highlight on hover, and the browser tab’s icon is the MultiAgent mark.
MultiAgent maintains the cards from its database: one card per agent, product and tool with an address — with the projects’ real logos, and agent and app cards show badges of their extra links in the corner (the “Links” tab). Common actions are not cards but a row of icon buttons in the top-right corner: “Git” (while Forgejo runs on the factory), “QR login” (when the central login is on) and always the rightmost “Logout”; “Logout” ends the central-login session, signs out of all agents and products (their tokens are deleted) and of the page itself. The buttons in the corner do not count as apps and are not among the cards. QR login and the logout page are described below. 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 labels on the page follow the factory brand’s language: on an English brand the page is served in English. There is no separate language choice on the tab any more — the language follows the brand, and with it change the heading, the buttons and the site link at the bottom of the page.
Details on the Factory Home Page page.
Central Login (the “Authorization” Tab)
So that a visitor signs in once and gets access to any protected app on the factory, you can install the central login on the factory — it is the “Authorization” tab (Authelia), sitting right of the Nginx tab. The login is a service container {slug}-auth (agents-auth by default) 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 sign-in on the login page opens every protected app of the factory — no repeated logins. The login session lives 90 days and is not interrupted by a profile update; devices already signed in survive a code revocation. Signing everyone out by force is applying the settings on this same tab.
The protection works only over a secure connection (HTTPS): either a local certificate and HTTPS port from the Nginx tab, or the factory’s public address (or an address template of the form https://{base}/{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 (when the port is open), 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 “Apply configuration” button on that tab does more than apply the settings — it also ends every open session: each browser has to sign in again with the current password. A protected app’s manifest file (manifest.json) stays available without a login — the browser requests it separately from the page, and without that the page would show an error.
The auth slug is reserved on every factory — you cannot create an agent, tool or route with that name. Forgejo connects to the central login by itself, as soon as the login is installed, protection is working and Forgejo is running: its login page gets a sign-in-through-central-login button, and the first such sign-in creates the account from the central-login identity. The administrator’s login and password follow the central login — the Forgejo tab has a “Sync authorization” button for that. When the conditions go away, the login button disappears by itself. 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
Where the public links to a factory’s apps point is decided in order. First — the “Public address” field on the General tab: when it is filled, all links are built from it, and the machine’s real address stays internal — it is what MultiAgent uses for SSH and tunnels. This is the case when the public domain and the machine itself are different things: say, the factory sits in a closed network and an external reverse proxy opens it to the world.
When the public address is empty, the public base becomes the base of the agents’ address template of the form {base}/{slug} — as before. When the template is not set either, links are built from the machine’s address: http(s)://{host}[:{nginx port}]/{slug}/. Why keep a separate field, then? The template with the {slug}, {host} and {port} placeholders primarily tells MultiAgent how it itself reaches the APIs of that factory’s agents. If you put the public domain into the template, management traffic takes the same path — out through the external proxy and back; the separate field keeps the two jobs apart. Direct access at http(s)://{host}[:{port}] remains the fallback path. Changing the public address, the template or the factory name rebuilds the nginx routes at once and syncs the central-login configuration with the new address.
https://apps.example.com/{slug}
Files
Every factory has built-in access to files (the “Files” item in the sidebar): 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 factory without leaving MultiAgent.
The separate “Files” page shows two panels — each with its own factory 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 factory or at two different ones: MultiAgent itself transfers the files between them over its own saved accesses — nothing to configure. 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 machine, 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 Factory to a Client
When a factory belongs to a client, you can hand the management over: the client’s own MultiAgent is deployed on it, 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 factory page, and a preview shows in advance what moves and what stays with you. Running apps are not touched: nothing is stopped and nothing is reinstalled.
After the handover, routing is managed by the client’s instance, and you keep the server — the physical machine: 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 Factory Handover page.