> ## Documentation Index
> Fetch the complete documentation index at: https://agent-memory.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment

> Background services, Docker, remote servers, Windows, and clean removal

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:

```bash theme={"dark"}
npm install -g @agentmemory/agentmemory
which agentmemory
```

## 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.

<Tabs>
  <Tab title="Linux (systemd)">
    Create `~/.config/systemd/user/agentmemory.service`, substituting the path from `which agentmemory`:

    ```ini theme={"dark"}
    [Unit]
    Description=agentmemory daemon
    After=network.target

    [Service]
    ExecStart=/usr/local/bin/agentmemory
    Restart=on-failure
    RestartSec=5

    [Install]
    WantedBy=default.target
    ```

    ```bash theme={"dark"}
    systemctl --user daemon-reload
    systemctl --user enable --now agentmemory
    loginctl enable-linger $USER
    ```

    `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'`.
  </Tab>

  <Tab title="macOS (launchd)">
    Create `~/Library/LaunchAgents/dev.agentmemory.plist`, substituting the path from `which agentmemory`:

    ```xml theme={"dark"}
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
      <key>Label</key><string>dev.agentmemory</string>
      <key>ProgramArguments</key>
      <array><string>/opt/homebrew/bin/agentmemory</string></array>
      <key>RunAtLoad</key><true/>
      <key>KeepAlive</key>
      <dict><key>SuccessfulExit</key><false/></dict>
    </dict>
    </plist>
    ```

    ```bash theme={"dark"}
    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.agentmemory.plist
    ```

    Unload with `launchctl bootout gui/$(id -u)/dev.agentmemory`.
  </Tab>
</Tabs>

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.

<Note>
  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.
</Note>

## 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/`](https://github.com/rohitg00/agentmemory/tree/main/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:

```bash theme={"dark"}
# on each client machine / in each agent's env
export AGENTMEMORY_URL=https://memory.example.com
export AGENTMEMORY_SECRET=<the server's secret>
```

`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](/docs/sharing); separate daemons that should exchange memories use the [mesh](/docs/sharing#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](/docs/configuration#cli-and-runtime-knobs) (`SNAPSHOT_ENABLED=true`).

## Clean uninstall

```bash theme={"dark"}
agentmemory remove
```

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.