Docs/Install the home agent/Install

Install the home agent

The agent runs the fetch and structure pipeline on your hardware so the cloud only sees billing. Below is the production compose snippet — about three minutes if you've used Docker before.

updated 2026-05-28read time · 6 min

Before you start

You need a machine that runs Docker — a NAS, mini-PC, or homelab box works. The agent uses about 400 MB of RAM at idle and bursts to roughly 1.5 GB during a transcribe. No GPU required; if you have one, transcription runs faster.

Note

The agent does not need to be reachable from the internet. It opens an outbound websocket to agents.saveplate.com and waits for jobs. If you can ssh into it from your couch, you're good.

docker-compose

Paste the snippet below into a file called docker-compose.yml. Replace SAVEPLATE_TOKEN with the token you'll generate at saveplate.app/agents/new.

docker-compose.yml

1services:
2  saveplate-agent:
3    image: ghcr.io/saveplate/agent:0.7
4    container_name: saveplate-agent
5    restart: unless-stopped
6    environment:
7      - SAVEPLATE_TOKEN=${SAVEPLATE_TOKEN}
8      - SAVEPLATE_AGENT_NAME=home-mealie-host
9      - SAVEPLATE_DATA_DIR=/data
10    volumes:
11      - ./agent-data:/data
12    networks: [home]
13 
14networks:
15  home:
16    external: true

Bring it up with docker compose up -d. The agent prints a heartbeat every 10 seconds; you should see it appear in your dashboard within a minute.

Watch out

If you're behind a reverse proxy that buffers responses, set SAVEPLATE_TRANSPORT=long-poll in the environment. We don't recommend it — websockets are dramatically lower latency — but it works.

← What is the agentConfiguration →