Skip to main content
The default mode is a foreground process on your machine: npx @agentmemory/agentmemory starts the engine, the worker, the REST API on 3111, and the viewer on 3113. This page covers everything beyond that: keeping it running after you close the terminal, hosting it on another machine, and removing it cleanly. For services, install globally first so the binary has a stable absolute path:

​
Background service

The daemon runs in the foreground and manages its own pidfile, which is exactly what service managers want. Point them at the binary and let them handle restarts.
Create ~/.config/systemd/user/agentmemory.service, substituting the path from which agentmemory:
enable-linger keeps the user service alive after logout. Use the absolute binary path in ExecStart: systemd starts services with a minimal PATH, so npx or a version-manager shim (nvm, fnm) resolves to nothing there. If your Node comes from a version manager, ExecStart must point at a binary whose shebang resolves too; npm install -g from that same Node usually does, otherwise wrap it: ExecStart=/bin/bash -lc 'exec agentmemory'.
Environment for a service comes from ~/.agentmemory/.env, which the daemon folds in on boot, so provider keys and flags do not need to live in the unit file.
Only run one starter. If a service manager owns the daemon, don’t also start it by hand: a second instance on an occupied port is refused, and agentmemory stop signals the pidfile owner, which the service manager will then restart.

​
Docker

Two distinct Docker questions land here: The engine in Docker, everything else native. If the pinned iii-engine binary cannot run on your platform, set AGENTMEMORY_USE_DOCKER=1 (or docker pull iiidev/iii:0.11.2 ahead of time) and start normally. The CLI runs the engine from the container and the worker, REST API, and viewer stay native. The whole stack in Docker on a server. The repo ships one-click templates under deploy/ for fly.io, Railway, Render, and Coolify (self-hosted VPS). Each is a self-contained Dockerfile that installs @agentmemory/agentmemory from npm, copies the engine binary from the official iiidev/iii image, persists to a /data volume, generates the HMAC secret on first boot, and publishes only port 3111. The per-template READMEs cover secret capture, backups, and rotation.

​
Remote and shared servers

Run the daemon on one machine and point every client at it:
status, doctor, the MCP shim, and the integration plugins all honor AGENTMEMORY_URL. Rules for going beyond loopback:
  • Set AGENTMEMORY_SECRET on the server first. Without it the REST API is open, which is only acceptable on loopback. With it, every request needs Authorization: Bearer <secret>.
  • Only expose 3111. The viewer (3113) stays on loopback; reach it with an SSH tunnel: ssh -L 3113:localhost:3113 user@server, then open http://localhost:3113.
  • Put TLS in front (a reverse proxy or the platform’s ingress) before sending the bearer token across a network you don’t control.
  • Sandboxed MCP clients that can’t probe localhost can set AGENTMEMORY_FORCE_PROXY=1 to trust AGENTMEMORY_URL directly.
Teammates sharing one daemon use the team feed; separate daemons that should exchange memories use the mesh.

​
Windows and WSL

agentmemory runs natively on Windows (PowerShell or cmd) via the same npx @agentmemory/agentmemory — paths like ~/.agentmemory resolve under your user profile. Under WSL2, run the daemon inside the distro. WSL2 forwards localhost, so Windows-side agents reach it at http://localhost:3111 without extra configuration. The one split to avoid: agentmemory connect edits the config files of the agents in the environment where it runs, so run it inside WSL for agents installed in WSL and on Windows for agents installed on Windows, with AGENTMEMORY_URL pointing at the one daemon.

​
Where the data lives

Everything is under ~/.agentmemory/: .env (config), bin/ (the pinned engine binary), the KV and index stores, snapshots/, local.db (standalone shim fallback), and backups/connect-manifest.json (a record of every config file connect touched). Relocate the state directory with --data-dir or AGENTMEMORY_DATA_DIR. Back up by copying the directory while the daemon is stopped, or rely on snapshots (SNAPSHOT_ENABLED=true).

​
Clean uninstall

This reads the connect manifest, shows a plan of exactly what it will undo (agent connections, the engine binary, pidfile, backups), then executes step by step, so wired clients don’t keep pointing at a daemon that no longer exists. Two things always get a separate confirmation, even with --force: .env (it holds your API keys) and the memory data directory, which is kept by default. --keep-data skips all user data in one flag. Reinstalling later is the same npx command; memories survive as long as the data directory does.
Last modified on August 15, 2026