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

# Run Supermemory with Docker

> Start the prebuilt Local image, keep your data, and upgrade an existing Compose installation.

Run Supermemory Local with the prebuilt Docker image. Docker chooses the Linux amd64 or arm64 image for your machine. You don’t need the server source, a local build, or a registry login.

You need Docker with the Compose plugin. Docker Desktop on macOS or Windows must run Linux containers. These shell examples use Bash or a compatible shell.

## Start a new installation

Use an empty directory for this installation. If you already run Supermemory with Compose, follow [Upgrade an existing installation](#upgrade-an-existing-installation) instead of overwriting your configuration.

Download the Compose file from the [0.0.9 release](https://github.com/supermemoryai/supermemory/releases/tag/server-v0.0.9):

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
release_url=https://github.com/supermemoryai/supermemory/releases
curl -fL "$release_url/download/server-v0.0.9/compose.yaml" -o compose.yaml
```

Create a `.env` file beside `compose.yaml`, replacing the placeholder with your provider key:

```dotenv theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
OPENAI_API_KEY=your_openai_api_key_here
SUPERMEMORY_VERSION=0.0.9
```

You can use `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, or `GROQ_API_KEY` instead of OpenAI. Keep `.env` private and don’t commit it. Docker runs non-interactively, so there’s no first-boot provider wizard.

Protect the file, pull the image, and start the service:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
chmod 600 .env
unset SUPERMEMORY_VERSION
docker compose pull
docker compose up -d --wait --wait-timeout 180
docker compose ps
```

The published image is `docker.io/supermemory/supermemory`. `SUPERMEMORY_VERSION=0.0.9` pins this release; `latest` follows stable releases. The Compose file binds port `6767` to `127.0.0.1`, not the public network. Allow the first startup to finish before checking health:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl --fail http://127.0.0.1:6767/v3/health
```

Local embeddings are the default. The first model download needs network access, and your chosen LLM provider may make external requests.

## Authenticate API requests

The server creates a local API key, separate from your LLM provider key. The Docker image hides that key from startup logs, so read it from the container:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
SUPERMEMORY_API_KEY="$(docker compose exec -T supermemory cat /data/api-key)"
curl --fail -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  http://127.0.0.1:6767/v3/projects
```

Treat this key as a secret. API requests require it even on localhost. Use the same key with your SDK and set `baseURL` to `http://localhost:6767`.

## Preserve data and configuration

The Compose project name is fixed as `supermemory`. Its named volume, `supermemory_supermemory-data`, mounts at `/data` and contains your store, API key, encryption identity, configuration, and model cache. Container replacement keeps that volume.

<Warning>
  Don’t run `docker compose down -v` or delete the volume: that removes your stored data and credentials. Keep the project name and volume mapping unchanged when upgrading. Changing the provider or embedding settings is a separate operation.
</Warning>

The Compose file passes through the provider keys listed above and `FIRECRAWL_API_KEY`. To disable telemetry, add `SUPERMEMORY_DISABLE_TELEMETRY=1` to `.env`. Other [configuration variables](/docs/self-hosting/configuration) need entries in the service’s `environment` block; setting them only in the host shell doesn’t pass them into the container.

## Upgrade an existing installation

Back up the complete stopped store before replacing its image. Run these commands from the directory containing your existing Compose file.

### Back up the store

Stop the service, then copy everything under `/data`, including its keys and identity files:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
docker compose stop
backup_dir="backups/$(date -u +%Y%m%dT%H%M%SZ)"
mkdir -p "$backup_dir"
chmod 700 "$backup_dir"
docker compose cp supermemory:/data/. "$backup_dir/"
```

Keep this backup and your existing `.env` file private. Confirm the copy completed before upgrading. These steps cover an existing Docker store; moving a native installation into Docker requires preserving that installation’s complete store and keys separately.

### Pull and start the new image

Keep your existing Compose configuration. If it uses an older GHCR image reference, change only its `image` line to the public Docker Hub image:

```yaml theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
image: docker.io/supermemory/supermemory:${SUPERMEMORY_VERSION:-latest}
```

Set `SUPERMEMORY_VERSION=0.0.9` in your existing `.env`, then pull and recreate the service without deleting its volume. Unset a previously exported version so `.env` takes precedence:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
unset SUPERMEMORY_VERSION
docker compose pull
docker compose up -d --wait --wait-timeout 180
curl --fail http://127.0.0.1:6767/v3/health
```

Local verifies a complete original backup before migrating an existing store. Existing cleanup can remove older duplicate documents and their source links. Keep your manual backup too; don’t point an older image at a migrated store. To roll back, restore the complete pre-upgrade backup and use its matching previous version.

Native Windows remains on 0.0.8; these Docker images run Linux containers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.