The agent

mlab-agent runs on the host that holds the data. It connects out to mlab.sh, runs the tools its policy declares (engram for memory forensics) and serves your workspace's requests. Linux x86_64 for now. Command reference: mlab-agent.

1. Install

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://apt.mlab.sh/mlab.asc -o /etc/apt/keyrings/mlab.asc
echo "deb [signed-by=/etc/apt/keyrings/mlab.asc] https://apt.mlab.sh stable main" | sudo tee /etc/apt/sources.list.d/mlab.list
sudo apt update && sudo apt install mlab-agent engram

sudo curl -fsSL https://pkg.mlab.sh/rpm/mlab.repo -o /etc/yum.repos.d/mlab.repo
sudo dnf install mlab-agent engram

The packages install /usr/bin/mlab-agent and /usr/bin/engram-tool, a mlab-agent system user, the directory /etc/mlab-agent, and a hardened systemd service that starts once the host is enrolled. Packages are signed; any distribution with glibc 2.36 or later works (Debian 12, Ubuntu 22.04, RHEL 9 and newer).

2. Enrol

In the workspace, Agents › Enrol an agent shows a one-time code (valid 15 minutes) and the mlab.sh key fingerprint. On the host, as the mlab-agent user:

sudo -u mlab-agent mlab-agent enroll --server https://mlab.sh \
  --code <code> --expect-fingerprint <fingerprint> --label "$(hostname)"

The agent creates its keys on the host, checks that mlab.sh's key matches the fingerprint (and stops if not), and writes agent.toml and agent.key (owner-only) in /etc/mlab-agent. The agent appears in the Agents tab.

3. Write the policy

The policy (/etc/mlab-agent/policy.toml) is yours: mlab.sh never pushes one. In the Agents tab, Policy opens an editor that builds it with you and checks it against what the agent reports:

• which tools run, with the path and SHA-256 of each binary (the agent refuses a binary whose hash differs);
• which operations each tool may answer;
• the tool's settings (for engram: the dump folders it may read, the largest read, environment variables and secret masking);
• the upload host for results (filled in by mlab.sh);
• a kill switch (enabled = false refuses everything).

Download it, then install it as root so the agent can read it but not change it:

sudo install -o root -g mlab-agent -m 0640 policy.toml /etc/mlab-agent/policy.toml
mlab-agent tools check --config /etc/mlab-agent

tools check starts each declared tool once and tells you whether it gets ready. The agent reads the policy again on every request, so most changes apply at once; a new tool path or hash needs a restart.

4. Run it

sudo systemctl enable --now mlab-agent
journalctl -u mlab-agent -f

Without the package (a binary you copied yourself), the agent can install the same service for you:

mlab-agent --config /path/to/config install     # writes ./svc.sh
sudo ./svc.sh install                           # installs, enables and starts the service

svc.sh also takes uninstall, start, stop, restart and status. The service runs as the user who called sudo (or --user), who must own agent.key.

Click Test in the Agents tab: mlab.sh sends a signed request through the agent and checks the signed answer.

Updating

The Tools tab shows the version each agent runs and whether a newer one is published, with the update command:

sudo apt update && sudo apt install --only-upgrade mlab-agent engram

An agent update restarts the service. A tool update changes the tool's SHA-256, which the policy pins: the agent refuses the new binary until the policy carries the new hash. Get it with mlab-agent tools hash /usr/bin/engram-tool (or from the Policy editor, which flags the drift), update the policy, then sudo systemctl restart mlab-agent.

Troubleshooting