Provider guide

How hosting works

The AgentMesh worker runs open-weight models on your machine for customers' deployments. It connects outbound to the control plane over HTTPS and a WebSocket, so you do not open any ports. You earn a share of what customers pay while your node serves their deployments.

• It only uses the CPU, memory, disk and GPU you allocate. Defaults are half your CPU cores and RAM, at most 20 GB of disk, and no GPU.
• It never touches your own Ollama install: not port 11434, not ~/.ollama, not your models. Workloads get their own port, model directory and process.
• It never runs commands from customers. The control plane can only ask it to deploy an approved model with set limits, or to stop one.
• Hardware reports contain CPU model, cores, RAM, free disk, OS, architecture, and GPU model and VRAM. Nothing else is uploaded.

Prerequisites

Create an enrollment token

1. Sign up at provider registration (or sign in).
2. Open Add a machine, optionally name the machine and its region, and press Create token.
3. The token works once and expires after 60 minutes. Create a new one for each machine. The page fills it into the install command for you.

With the API, using your provider sign-in token:

curl -X POST https://agentmesh-riuz.onrender.com/api/v1/nodes/enrollment-tokens \
  -H "Authorization: Bearer $PROVIDER_JWT" -H "Content-Type: application/json" -d '{"name": "my-box"}'

Install from a GitHub release

Each worker release on GitHub Releases is tagged worker-v0.3.0 and contains agentmesh_worker-0.3.0-py3-none-any.whl, install.sh, uninstall.sh and SHA256SUMS. The command below downloads the release into ~/agentmesh-worker-0.3.0, verifies every file against SHA256SUMS (stopping if any does not match), and only then runs the installer. Paste your token in place of <enrollment-token>; it is passed to the installer only, never put in a URL.

VERSION=0.3.0
BASE=https://github.com/meshach5667/AgentMeshh/releases/download/worker-v0.3.0
mkdir -p ~/agentmesh-worker-$VERSION && cd ~/agentmesh-worker-$VERSION
for f in install.sh uninstall.sh agentmesh_worker-$VERSION-py3-none-any.whl SHA256SUMS; do
  curl -fsSLO "$BASE/$f" || break
done
if command -v sha256sum >/dev/null; then sha256sum -c SHA256SUMS; else shasum -a 256 -c SHA256SUMS; fi \
  && chmod +x install.sh uninstall.sh \
  && ./install.sh --wheel ./agentmesh_worker-$VERSION-py3-none-any.whl \
       --control-plane https://agentmesh-riuz.onrender.com --token <enrollment-token> \
       --max-ram-mb 8192 --max-cpu 4 --max-disk-mb 30000

The installer:

1. checks your OS, Python and Ollama;
2. creates a private Python environment in ~/.local/share/agentmesh/venv-agentmesh-worker and installs the wheel (its dependencies come from PyPI);
3. writes ~/.config/agentmesh/agentmesh-worker.env with permissions 0600;
4. enrolls the machine with the one-time token;
5. starts a per-user background service: a systemd user unit on Linux, a launchd agent on macOS.

Useful options

On Linux, each model runs in its own systemd scope with hard memory and CPU limits. On macOS the limits are advisory: the scheduler never reserves more than you allow, but the OS does not enforce it.

Install from source

Use this before the first release is published, or to run unreleased code. It builds the same wheel locally.

git clone https://github.com/meshach5667/AgentMeshh.git && cd AgentMeshh/server
python3 scripts/build_worker_wheel.py
./packaging/install.sh --control-plane https://agentmesh-riuz.onrender.com --token <enrollment-token> \
    --max-ram-mb 8192 --max-cpu 4 --max-disk-mb 30000

Docker worker

The Docker worker runs each deployment in its own container. It needs the Compose file from the repository, so it uses a checkout rather than the release downloads.

git clone https://github.com/meshach5667/AgentMeshh.git && cd AgentMeshh
export AGENTMESH_CONTROL_PLANE_URL=https://agentmesh-riuz.onrender.com
export AGENTMESH_ENROLLMENT_TOKEN=<enrollment-token>
export DOCKER_GID=$(getent group docker | cut -d: -f3)
export AGENTMESH_MAX_RAM_MB=8192 AGENTMESH_MAX_CPU_CORES=4 AGENTMESH_MAX_DISK_MB=30000
docker compose -f docker-compose.worker.yml up -d

Each workload container runs with:

• memory and swap limits, a CPU quota and a PID limit;
• all Linux capabilities dropped, no-new-privileges, and a read-only root filesystem;
• no host bind mounts, only the agentmesh-models volume;
• a private network with no internet access once the model is downloaded;
• a GPU only if the deployment needs one and you set AGENTMESH_ALLOW_GPU=true.

Known gaps: the Docker worker has not yet been run against a real Docker daemon, and it does not detect GPUs inside its container, so it currently advertises no GPU. View logs with docker compose -f docker-compose.worker.yml logs -f worker.

Check the worker

The machine appears under My Nodes a few seconds after it enrolls. On the machine (installable agent), the worker command lives in its private environment:

export AGENTMESH_CONFIG_FILE=~/.config/agentmesh/agentmesh-worker.env
~/.local/share/agentmesh/venv-agentmesh-worker/bin/agentmesh-worker status     # enrollment, connection, workloads
~/.local/share/agentmesh/venv-agentmesh-worker/bin/agentmesh-worker doctor     # checks this machine's setup

systemctl --user status agentmesh-worker
journalctl --user -u agentmesh-worker -f

launchctl print gui/$(id -u)/io.agentmesh.agentmesh-worker
tail -f ~/.local/share/agentmesh/agentmesh-worker/logs/agentmesh-worker.log

doctor checks the platform, Python, config, control plane, credential, Ollama, resource limits, disk, memory, GPUs and schedule, and prints a fix for each problem. doctor --deep also starts a throwaway Ollama instance.

Manage machines

A node is shown as Accepting work, Paused, Unavailable (paused, draining or outside its schedule on the machine), Offline (no heartbeats) or Revoked. The node page shows each runtime the worker reported, whether its limits are enforced or advisory, how much of your allocation is reserved, and the last reported load.

Community models (opt-in)

Customers can import public GGUF models from Hugging Face for their own deployments. No operator reviews these, so AgentMesh only places them on nodes whose provider turns on Accept community models on the node page. It is off by default, and operators cannot turn it on for you.

• They run only with llama.cpp. The worker downloads one GGUF file from Hugging Face at a pinned commit and refuses it unless its SHA-256 matches.
• Gated, private and non-commercially licensed models, and code-carrying formats such as pickles, are refused before they reach you.
• What the model generates is not reviewed.
• Turning it off stops new placements. Community deployments already running keep running until they stop or move.

Earnings and payouts

• You are credited your share (after the platform fee) of each charge for deployments your nodes served. Earnings & Payouts lists the credits.
• Add a bank account there. Paystack verifies it, and only its last four digits are stored. Then request a payout.
• The amount is held from your balance at once. An operator approves the payout and Paystack transfers it. A failed or rejected payout returns the money.
• Served Usage shows the requests your nodes answered.

Troubleshooting

Start with agentmesh-worker doctor (see Check the worker).

Uninstall

cd ~/agentmesh-worker-0.3.0 && ./uninstall.sh            # add --purge-models to delete downloaded models

This stops the service and every managed workload, and deletes the credential, config, private environment and (with --purge-models) downloaded models. Your own Ollama is left untouched. For the Docker worker run docker compose -f docker-compose.worker.yml down -v. Then revoke the node in the dashboard.

How worker releases are made

Releases are built by GitHub Actions when a maintainer pushes a tag worker-v<version> matching WORKER_VERSION in server/node_agent/config.py. The workflow builds the wheel reproducibly, checks it installs, writes SHA256SUMS, and attaches the assets to the release. See Publishing worker releases.

Signed self-updates are separate: operators sign release manifests with an offline Ed25519 key, and workers installed with --update-public-key accept only releases signed by it, so even a compromised control plane cannot push code to your machine. That key is never stored in GitHub Actions.