Install on a server

Lumate on a Linux server for the whole office: one command installs it, it updates itself from OXS Cloud (or from an offline bundle), backs itself up every day, and goes back by itself when an update does not start. For Lumate on one Windows PC instead, see Lumate Local.

What you need#

The installer puts Docker Engine on the server when it is missing (from Docker's own repository, after asking).

Install#

On the server, as root:

curl -fsSL https://api.lumate.io/install.sh -o install.sh
sudo bash install.sh --key axk_yourlicencekey

To check the installer first (optional), run the steps below between these two lines.

Checking the installer (optional)#

install.sh is signed with Lumate's release key, and OXS Cloud publishes only a signed one. To check the downloaded file yourself before running it, on the server:

curl -fsSLO https://api.lumate.io/install.sh.sig
printf -- '-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA+bzBByJhjJ0huDTd2QQWNGRgQF52lo8TKCODtRzV4yo=\n-----END PUBLIC KEY-----\n' > agentx-release.pem
{ printf 'agentx-install-script-v1\0'; cat install.sh; } > install.signed
openssl pkeyutl -verify -pubin -inkey agentx-release.pem -rawin -in install.signed -sigfile install.sh.sig

It prints Signature Verified Successfully. Anything else means the file is not the one OXS signed: do not run it. The installer then checks every release it downloads against the same key.

What the installer asks#

It asks for the address people open Lumate at. Answer with a public domain name (for example agentx.yourcompany.com, whose DNS points at the server) for a Let's Encrypt certificate, or press Enter to use the office network (the server's name and IP). The same choices as options, for an unattended install:

What it does:

1. Checks the machine (the Linux, CPUs, memory, disk, ports 80/443, the way to OXS Cloud).
2. Fetches the release of your channel and checks it was signed with Lumate's release key. Then it checks the download's SHA-256.
3. Loads the images.
4. Writes /opt/agentx, with secrets made on the server (.env, readable by root only).
5. Starts Lumate and waits until it answers.

At the end it prints the setup link, which carries the setup token, and the token itself (for a lost link). Open the link and make the first account with your email; then choose who sets up the company (you, or a manager you send a link to). Given --key, the install is activated at its start: no OXS account is asked. See First setup.

On the office network: trusting the certificate#

With --lan (or Enter at the question), Lumate makes the office's own certificate authority. The installer prints its SHA-256 fingerprint, and Settings → General shows it under the version. On each PC that opens Lumate:

1. Copy /opt/agentx/ca.crt from the server.
2. Compare its fingerprint with the one shown. On Windows: certutil -hashfile ca.crt SHA256.
3. Trust it for the current user: double-click it → Install Certificate → Current User → Trusted Root Certification Authorities.

Lumate Desk pins the server's certificate when it pairs, so it needs nothing more. The server's certificate lasts 825 days and is made again by itself a month before it ends; after that, pair Desk again once.

What runs#

/opt/agentx/compose.yml runs five services, each from the same version. All of them use the server's own network; only Caddy listens beyond the server.

Claude Code signs in one of two ways, and every agent uses it:

• The company's Claude account, signed in on the server: on the server, run sudo agentx claude-login. It shows a link: open it on any device, sign in with the company's Claude account, approve, and type the code it gives back into the server's terminal. The sign-in is kept in the runner and renews itself; sudo agentx claude-status shows it, sudo agentx claude-logout ends it. Add --console to sign in with an Anthropic Console account (billed per use) instead of a Claude plan.
• An Anthropic API key (recommended for businesses: commercial terms) or a Claude sign-in token, in Settings → Runners → Claude for the runners. Owners and admins set it there; it is kept sealed and never shown back, and it comes first when both are set.

Settings → Runners shows, for each runner, whether its Claude Code is signed in.

The desk phone (an IP phone on the office's PBX)#

Lumate registers with the PBX as one extension (SIP over UDP 5060, audio as RTP) from the machine it runs on. Three ways to reach the office's PBX:

Through a linked PC the PC↔server round trip adds to each direction's audio (Settings → Linked PCs shows it); the PC's jitter buffer is the same as on a desk phone in the office.

The agentx command#

On the server, as root:

Updates#

Settings → Updates (the person who set up Lumate) shows:

• the version;
• the channel (stable or beta);
• automatic installs in the maintenance window (default 02:00–05:00, the company's time);
• what is offered, with its notes, and Update now.

Lumate looks every hour, downloads the update and checks it. It never installs during a call; the AI dialer pauses meanwhile.

An update:

1. backs up the data first;
2. switches every service to the new version;
3. waits for it to answer.

If the new version does not start, Lumate goes back by itself, files and data, usually within a minute. That version is then not installed again by itself; Update now can try it again. Settings → Updates then offers Go back to the version before, kept on the server. When that version cannot read today's data, it takes the data from the backup made before the update (a backup of today's is made first).

Without internet: offline bundles#

A server that cannot reach OXS Cloud is installed and updated from an offline bundle, AgentX-Server-<version>-offline.tar, from OXS. It holds the images, their signed manifest and the installer. Use it in one of three ways:

• install with sudo bash install.sh --offline AgentX-Server-<version>-offline.tar;
• update with agentx update --bundle AgentX-Server-<version>-offline.tar;
• upload it in Settings → Updates → Offline bundle.

Only a bundle signed with Lumate's release key is taken.

Backups#

Settings → Backups (the person who set up Lumate):

• What is kept: a backup every day at its hour (7 kept), one before every update (3 kept), and Back up now (10 kept). Each can be downloaded.
• What a backup holds: the database and the shared files. It never holds the server's secrets, so also keep /opt/agentx/.env in a safe place. Without its SECRETS_KEY, the secrets stored in Lumate cannot be read.
• Copy to a bucket: each backup can also go to an S3-compatible bucket (AWS S3, Backblaze B2, Wasabi, MinIO…). Give the address, region, bucket, folder and an access key; the secret is kept sealed and never shown back.
• Restoring: only on the server, with agentx restore.

Troubleshooting#