Deploying on Docker

Running Curiosity Workspace as a Docker container is the most common way to install it. The same image runs in local dev, in CI, and in production behind a reverse proxy.

This page covers single-host Docker deployments. For Kubernetes, see Kubernetes; for managed cloud variants, see AWS, Azure, GCP, and OpenShift.

Requirements

• A 64-bit Linux, macOS, or Windows host with Docker installed. Follow the official Docker docs.
• 8 GB of RAM available to Docker (16 GB+ for production with embeddings).
• A persistent volume mount for MSK_GRAPH_STORAGE.
• A network plan: bind to 127.0.0.1 for local dev, put a TLS-terminating proxy in front for shared deployments.

Pulling the image

The image is published as curiosityai/curiosity:

docker pull curiosityai/curiosity:nightly

To pin to a specific release, use the numeric build tag:

docker pull curiosityai/curiosity:66474

Local development — single docker run

The simplest invocation, suitable only for a developer's own machine:

mkdir -p ~/curiosity/storage
docker run --name curiosity \
  -p 127.0.0.1:8080:8080 \
  -v ~/curiosity/storage:/data \
  -e MSK_GRAPH_STORAGE=/data/curiosity \
  -e MSK_ADMIN_PASSWORD="$(openssl rand -base64 24)" \
  curiosityai/curiosity:nightly

Notes:

• 127.0.0.1:8080:8080 binds the workspace to loopback only. Drop the IP prefix when you're ready to expose it on the host network.
• MSK_ADMIN_PASSWORD replaces the default admin/admin. Read it back from your shell history or docker inspect.

On Windows, swap the volume syntax:

mkdir c:\curiosity\storage
docker run --name curiosity `
  -p 127.0.0.1:8080:8080 `
  -v c:/curiosity/storage:/data `
  -e MSK_GRAPH_STORAGE=/data/curiosity `
  -e MSK_ADMIN_PASSWORD=ChangeMeNow! `
  curiosityai/curiosity:nightly

Docker on Windows expects forward slashes inside volume paths.

Staging / production — Docker Compose

For anything beyond local dev, use Docker Compose so the configuration is versioned and reproducible.

docker-compose.yml:

services:
  curiosity:
    image: curiosityai/curiosity:66474
    container_name: curiosity
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"   # exposed via the reverse proxy below
    volumes:
      - curiosity-data:/data
      - curiosity-backups:/backups
      - ./certs:/certs:ro
    environment:
      MSK_GRAPH_STORAGE: /data/curiosity
      MSK_GRAPH_BACKUP_FOLDER: /backups
      MSK_GRAPH_JOURNAL_FOLDER: /data/journal
      MSK_PUBLIC_ADDRESS: https://workspace.example.com
      MSK_USE_HSTS: "true"
      MSK_REDIRECT_TO_HTTPS: "true"
      # Secrets injected via env_file (kept out of git)
    env_file:
      - .env
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/api/login/check", "-o", "/dev/null"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 60s

volumes:
  curiosity-data:
  curiosity-backups:

.env (kept out of source control — see your secret manager):

MSK_ADMIN_PASSWORD=<from secret manager>
MSK_ADMIN_EMAIL=ops@example.com
MSK_JWT_KEY=<32+ random bytes, from secret manager>
MSK_LICENSE=<your license token>
MSK_GRAPH_MASTER_KEY=<32+ random bytes, backed up separately>

Bring it up:

docker compose up -d
docker compose logs -f curiosity

Environment variables

The container is configured almost entirely through MSK_* environment variables — there is no file-based config inside the image. Pass them with -e flags on docker run, an environment: block in Compose, or an env_file: for secrets. The tables below cover the variables you're most likely to set on a Docker host; see Configuration reference for the full list including integration-specific keys (OpenAI, S3, Azure OCR, etc.).

Storage and data

Networking and addresses

TLS and certificates

Authentication and security

Logging and diagnostics

Replication and state tracking

In-product updates

These variables control the Software Updates admin page (Operate → Software Updates), which lets system admins pull a newer image tag and recreate the running container from the UI. See In-product updates below for the full flow and security trade-offs.

Performance and runtime

Licensing and application metadata

Production checklist

A short list of must-haves before a Docker-based workspace serves real users:

• Numeric build tag (curiosityai/curiosity:66474), not :nightly.
• Persistent volume for MSK_GRAPH_STORAGE on durable storage (SSD or better) - ideally with snapshot support.
• Optional backup volume for MSK_GRAPH_BACKUP_FOLDER, off-host on a schedule.
• All secrets injected from a secret manager (never baked into the image or compose file).
• TLS terminated at a reverse proxy or in-container (set MSK_CERT_FILE, MSK_CERT_FILE_PRIVATE_KEY, MSK_USE_HSTS=true, MSK_REDIRECT_TO_HTTPS=true).
• MSK_PUBLIC_ADDRESS set so generated links use the right host.
• Container memory/CPU limits sized for embedding workload (start at 16 GB / 8 vCPU).
• Healthcheck enabled so the orchestrator can restart the container on hangs.
• Log routing to your aggregator — either MSK_LOG_PATH on a mounted volume or the platform's stdout collector.
• Backup/restore drill completed and documented.

See Production deployment for the broader checklist that also covers identity, monitoring, and disaster recovery.

Healthcheck details

Use the /api/health endpoint to check application health. Use /api/ping to see if the container is responding to requests.

In-product updates

System admins can pull a newer image tag and recreate the running container from the Software Updates admin page (Operate → Software Updates), without dropping to the host shell. The page lists every numeric build tag in the configured repository that is newer than the running build; picking one triggers a watchtower-style cutover.

This is intended for small single-host deployments and lab environments. If upgrades are owned by Compose CI, Kubernetes, or an external watchtower, set MSK_DISABLE_DOCKER_UPDATE=true and ignore the page.

How the swap works

A container cannot replace itself — it holds the host ports the replacement needs and would have to keep issuing daemon calls after stopping. The workspace therefore delegates the cutover to a short-lived updater helper container spawned from its own image:

1. The workspace pulls the chosen tag through the Docker Engine API.
2. It inspects its own container to capture the current Config, HostConfig, and network attachments.
3. It creates a helper container (named <original>-curiosity-updater, network none, AutoRemove: true) and starts it.
4. The helper waits ~5 s so the HTTP response that triggered the update flushes, then stops + removes the old container and creates a replacement under the same name with the new image and the captured config.
5. The daemon re-attaches the same networks. Static IPs (IPAMConfig) are preserved; service discovery by container name keeps working because the name is reused.

The workspace is unreachable for the duration of the swap — usually a few seconds, plus the new container's startup time.

Requirements

For the page to be functional:

• The workspace must be running inside a container (/.dockerenv present, or DOTNET_RUNNING_IN_CONTAINER=true).
• The Docker Engine socket must be bind-mounted into the container — by default at /var/run/docker.sock. Override the path with MSK_DOCKER_SOCKET.
• The current user inside the container must be able to read/write the socket.
• The configured MSK_DOCKER_IMAGE_REPOSITORY must be reachable on Docker Hub (or whichever registry serves it).

A minimal docker run:

docker run --name curiosity \
  -p 127.0.0.1:8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/curiosity/storage:/data \
  -e MSK_GRAPH_STORAGE=/data/curiosity \
  curiosityai/curiosity:66474

The only addition over the local development command is the second -v that bind-mounts the Docker socket.

The equivalent Compose snippet:

services:
  curiosity:
    image: curiosityai/curiosity:66474
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - curiosity-data:/data
    environment:
      MSK_GRAPH_STORAGE: /data/curiosity
      # Optional: pin a non-default repository (e.g. private mirror).
      # MSK_DOCKER_IMAGE_REPOSITORY: registry.example.com/curiosity/workspace

Picking a tag

Only numeric build tags are listed in the UI — latest and nightly are intentionally excluded because the page is about pinning to a concrete build. The dropdown shows tags newer than the running build, newest-first, with their push date and compressed size when the registry reports them.

The build number for the running container comes from MSK_BUILD_NUMBER, which is baked into every official image. If the workspace cannot determine the current build (e.g. when running an unofficial build), every tag in the repository is offered.

Disabling the feature

Set MSK_DISABLE_DOCKER_UPDATE=true. The admin sidebar entry disappears, the controller refuses status/list/update calls, and the helper-container path is unreachable. Use this whenever the deployment is managed by an external upgrade pipeline.

Troubleshooting

REST API

The page is a thin wrapper over three endpoints under /api/update/docker/, all gated by AuthorizeSystemAdmin. Useful for scripting upgrades without driving the UI:

Upgrading

Pinning a version means upgrades are deliberate. From the host:

docker compose pull
docker compose up -d

Or from inside the workspace, use the Software Updates admin page when the Docker socket is mounted.

For breaking changes, follow Upgrades and migrations: take a backup first, run on staging, validate, then promote.

Common pitfalls

• Ephemeral storage — running without -v or with a tmpfs mount loses data on container restart. Always mount a real volume on MSK_GRAPH_STORAGE.
• No MSK_PUBLIC_ADDRESS behind a proxy — generated links (SSO callback URLs, email links) point at the internal hostname instead of the user-facing one.
• Insufficient memory — the workspace process maps indexes into memory. OOM-killed containers leave the indexes in a recovery state on the next boot. Size accordingly.

See also

• Configuration reference — every MSK_* variable.
• Kubernetes — when you outgrow a single host.
• Backup and restore — what to do when something goes wrong.
• Troubleshooting — install and startup failures.