@cairnkeep/cli 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable user-facing changes are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [2.2.0] - 2026-07-20
+
+### Added
+
+- Add unprivileged memory-server and workspace OCI images with rootless Podman
+  launchers, authenticated HTTP deployment examples, and persistent storage.
+- Add isolated-copy and explicit shared-checkout workspace modes for private
+  derived distributions.
+- Verify stdio startup, HTTP authentication, memory persistence across
+  replacement, and both workspace modes in container CI.
+
 ## [2.1.0] - 2026-07-16
 
 ### Added
@@ -89,6 +100,7 @@ stored memories.
 - Preserve executable permissions and Bash 3.2 portability on macOS.
 - Add backup-first uninstall and SQLite-safe memory export/import guidance.
 
+[2.2.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/cairnkeep/cairnkeep/compare/v1.1.3...v2.0.0
 [1.1.3]: https://github.com/cairnkeep/cairnkeep/compare/v1.1.2...v1.1.3

package/README.md

@@ -41,6 +41,24 @@ and 20 are end-of-life upstream.
 Linux, macOS, Bash 3.2 portability, and clean Node 22/24/26 runtime checks
 are exercised in CI.
 
+## Try with Podman
+
+The minimal OCI image runs the memory server as an unprivileged user and keeps
+all databases in a named volume:
+
+```bash
+podman run --rm -i \
+  --userns=keep-id:uid=10001,gid=10001 \
+  --read-only --cap-drop=all --security-opt=no-new-privileges \
+  --tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777 \
+  --volume cairnkeep-data:/data:Z,U \
+  ghcr.io/cairnkeep/cairnkeep:latest stdio
+```
+
+For persistent authenticated HTTP, rootless Quadlet, isolated workspace mode,
+storage paths, secrets, and private derived images, see
+**[Containers](docs/containers.md)**.
+
 ## Components
 
 - **`mcp-memory-server/`** — an MCP server exposing durable, scoped memory
@@ -166,6 +184,7 @@ search):
 | `CAIRN_LLM_EXTRACTION_MODEL` | Chat model used for memory extraction |
 | `CAIRN_MEMORY_EMBEDDING_URL` | Embeddings endpoint (falls back to `CAIRN_LLM_API_URL`) |
 | `CAIRN_MEMORY_EMBEDDING_MODEL` | Embedding model name (required for semantic search) |
+| `CAIRN_MEMORY_EMBEDDING_TIMEOUT_MS` | Embedding request timeout before substring fallback (default `15000`) |
 | `CAIRN_AGENTFS_BASE_DIR` | Base dir for global memory scopes (default `~/.cairnkeep`) |
 | `CAIRN_GIT_PROVIDER` | Git host for collaboration commands: `github`\|`gitlab`\|`codeberg`\|`forgejo`\|`none` ([docs/git-providers.md](docs/git-providers.md)) |
 | `CAIRN_ROUTE_ENDPOINT` | Base URL of an already-running token-miser routing/tiering proxy (unset → `route_check` is inert) |
@@ -189,6 +208,7 @@ enabling them.
 - **Managed overlay distributions** (wrapper CLI, policy lock, private registry, rollback) — [docs/overlay-distributions.md](docs/overlay-distributions.md)
 - **Full operating guide** — [docs/operating.md](docs/operating.md)
 - **Memory storage and deployment** — [docs/storage.md](docs/storage.md)
+- **Podman and OCI containers** — [docs/containers.md](docs/containers.md)
 - **Privacy and data flow** — [docs/privacy-and-data-flow.md](docs/privacy-and-data-flow.md)
 - **Git providers** — [docs/git-providers.md](docs/git-providers.md)
 - **Support** — [SUPPORT.md](SUPPORT.md)

package/containers/compose.yaml

@@ -0,0 +1,29 @@
+services:
+  cairnkeep:
+    image: ghcr.io/cairnkeep/cairnkeep:${CAIRNKEEP_VERSION:-latest}
+    command: ["http"]
+    restart: unless-stopped
+    read_only: true
+    cap_drop: ["ALL"]
+    security_opt:
+      - no-new-privileges:true
+    environment:
+      MCP_HTTP_HOST: 0.0.0.0
+      MCP_HTTP_PORT: "7801"
+      CAIRN_MEMORY_HTTP_ALLOWED_HOSTS: ${CAIRN_MEMORY_HTTP_ALLOWED_HOSTS:-localhost:7801,127.0.0.1:7801}
+      CAIRN_MEMORY_HTTP_TOKEN_FILE: /run/secrets/http-token
+    ports:
+      - "127.0.0.1:${CAIRNKEEP_PORT:-7801}:7801"
+    volumes:
+      - cairnkeep-data:/data
+    secrets:
+      - http-token
+    tmpfs:
+      - /tmp:size=64m,mode=1777
+
+volumes:
+  cairnkeep-data:
+
+secrets:
+  http-token:
+    file: ${CAIRNKEEP_HTTP_TOKEN_FILE:-./secrets/http-token}

package/containers/entrypoint.sh

@@ -0,0 +1,54 @@
+#!/bin/sh
+set -eu
+
+load_secret() {
+  name=$1
+  eval "file=\${${name}_FILE:-}"
+  eval "value=\${${name}:-}"
+
+  if [ -n "$file" ] && [ -n "$value" ]; then
+    echo "cairnkeep: set either $name or ${name}_FILE, not both" >&2
+    exit 64
+  fi
+  if [ -n "$file" ]; then
+    if [ ! -f "$file" ] || [ ! -r "$file" ]; then
+      echo "cairnkeep: secret file for $name is not readable" >&2
+      exit 66
+    fi
+    value=$(cat "$file")
+    export "$name=$value"
+  fi
+}
+
+load_secret CAIRN_MEMORY_HTTP_TOKEN
+load_secret CAIRN_LLM_API_KEY
+load_secret ANYTHINGLLM_API_KEY
+
+mode=${1:-stdio}
+shift || true
+
+case "$mode" in
+  stdio)
+    unset MCP_HTTP_HOST MCP_HTTP_PORT
+    cd "${CAIRN_SERVER_WORKDIR:-/data/project}"
+    exec cairn memory-server "$@"
+    ;;
+  http)
+    if [ -z "${CAIRN_MEMORY_HTTP_TOKEN:-}" ]; then
+      echo "cairnkeep: HTTP mode requires CAIRN_MEMORY_HTTP_TOKEN or CAIRN_MEMORY_HTTP_TOKEN_FILE" >&2
+      exit 64
+    fi
+    export MCP_HTTP_HOST=${MCP_HTTP_HOST:-0.0.0.0}
+    export MCP_HTTP_PORT=${MCP_HTTP_PORT:-7801}
+    allowed_hosts=${CAIRN_MEMORY_HTTP_ALLOWED_HOSTS:-}
+    export CAIRN_MEMORY_HTTP_ALLOWED_HOSTS="${allowed_hosts:+$allowed_hosts,}localhost:${MCP_HTTP_PORT},127.0.0.1:${MCP_HTTP_PORT}"
+    cd "${CAIRN_SERVER_WORKDIR:-/data/project}"
+    exec cairn memory-server "$@"
+    ;;
+  cairn)
+    exec cairn "$@"
+    ;;
+  *)
+    exec "$mode" "$@"
+    ;;
+esac

package/containers/healthcheck.mjs

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+
+const port = process.env.MCP_HTTP_PORT?.trim();
+if (!port) {
+    process.exit(0);
+}
+
+let token = process.env.CAIRN_MEMORY_HTTP_TOKEN?.trim();
+const tokenFile = process.env.CAIRN_MEMORY_HTTP_TOKEN_FILE?.trim();
+if (!token && tokenFile) {
+    try {
+        token = readFileSync(tokenFile, "utf8").trim();
+    } catch {
+        process.exit(1);
+    }
+}
+if (!token) {
+    process.exit(1);
+}
+
+const body = {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "initialize",
+    params: {
+        protocolVersion: "2025-06-18",
+        capabilities: {},
+        clientInfo: { name: "cairnkeep-container-health", version: "1" },
+    },
+};
+
+try {
+    const response = await fetch(`http://127.0.0.1:${port}/mcp`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(4000),
+    });
+    process.exit(response.ok ? 0 : 1);
+} catch {
+    process.exit(1);
+}

package/containers/quadlet/cairnkeep-data.volume

@@ -0,0 +1,2 @@
+[Volume]
+VolumeName=cairnkeep-data

package/containers/quadlet/cairnkeep.container

@@ -0,0 +1,32 @@
+[Unit]
+Description=Cairnkeep memory server
+After=network-online.target
+Wants=network-online.target
+
+[Container]
+Image=ghcr.io/cairnkeep/cairnkeep:latest
+ContainerName=cairnkeep
+Exec=http
+UserNS=keep-id:uid=10001,gid=10001
+Volume=cairnkeep-data.volume:/data:Z
+Secret=cairnkeep-http-token,type=mount,target=http-token
+Environment=MCP_HTTP_HOST=0.0.0.0
+Environment=MCP_HTTP_PORT=7801
+Environment=CAIRN_MEMORY_HTTP_ALLOWED_HOSTS=localhost:7801,127.0.0.1:7801
+Environment=CAIRN_MEMORY_HTTP_TOKEN_FILE=/run/secrets/http-token
+PublishPort=127.0.0.1:7801:7801
+ReadOnly=true
+DropCapability=all
+HealthCmd=node /usr/local/lib/cairnkeep/container-healthcheck.mjs
+HealthInterval=30s
+HealthTimeout=5s
+HealthStartPeriod=10s
+HealthRetries=3
+PodmanArgs=--security-opt=no-new-privileges
+
+[Service]
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target

package/containers/workspace-entrypoint.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+set -eu
+
+mode=${CAIRN_WORKSPACE_MODE:-shared}
+case "$mode" in
+  shared)
+    ;;
+  sandbox)
+    if [ ! -d /source ]; then
+      echo "cairnkeep: sandbox mode requires a read-only repository mounted at /source" >&2
+      exit 66
+    fi
+    if [ ! -e /workspace/.cairnkeep-sandbox-ready ]; then
+      cp -a /source/. /workspace/
+      : > /workspace/.cairnkeep-sandbox-ready
+    fi
+    ;;
+  *)
+    echo "cairnkeep: CAIRN_WORKSPACE_MODE must be shared or sandbox" >&2
+    exit 64
+    ;;
+esac
+
+cd /workspace
+exec /usr/local/bin/cairn-container-entrypoint "$@"

package/docs/containers.md

@@ -0,0 +1,187 @@
+# Containers
+
+Cairnkeep publishes two OCI images for Podman and other OCI-compatible
+engines:
+
+| Image | Purpose |
+|---|---|
+| `ghcr.io/cairnkeep/cairnkeep:<version>` | Minimal MCP memory server, over stdio or authenticated HTTP |
+| `ghcr.io/cairnkeep/cairnkeep-workspace:<version>` | Derivation base with Cairnkeep, Git, SSH, and ripgrep |
+
+Both images run as the unprivileged user `10001:10001`. The workspace image is
+not a preconfigured coding harness: a private distribution can derive from it
+and install only its approved harnesses and policies.
+
+## Local stdio
+
+After installing `@cairnkeep/cli`, register the container launcher rather than
+the host memory server:
+
+```bash
+claude mcp add cairn-memory -s user -- cairn-container stdio
+```
+
+Each harness session starts an ephemeral server container. Memory survives in
+the `cairnkeep-data` named volume. The container does not discover or contact a
+remote Cairnkeep server.
+
+The equivalent direct Podman command is:
+
+```bash
+podman run --rm -i \
+  --userns=keep-id:uid=10001,gid=10001 \
+  --read-only --cap-drop=all --security-opt=no-new-privileges \
+  --tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777 \
+  --volume cairnkeep-data:/data:Z,U \
+  ghcr.io/cairnkeep/cairnkeep:latest stdio
+```
+
+Pin a version instead of `latest` for managed installations.
+
+## Authenticated HTTP
+
+Generate the bearer token into a private file and start a loopback-only
+listener:
+
+```bash
+install -m 700 -d ~/.config/cairnkeep/secrets
+openssl rand -hex 32 > ~/.config/cairnkeep/secrets/http-token
+chmod 600 ~/.config/cairnkeep/secrets/http-token
+
+cairn-container http \
+  --token-file ~/.config/cairnkeep/secrets/http-token \
+  --port 7801
+```
+
+The launcher refuses token files that are symlinks or have a mode other than
+`0400` or `0600`. It mounts the token read-only instead of putting it in the
+container environment or image.
+
+The listener is deliberately published only on `127.0.0.1`. For access from
+other machines, keep it on loopback behind a TLS reverse proxy or encrypted
+private network. Add the externally visible `Host` header to the DNS-rebinding
+allowlist:
+
+```bash
+cairn-container http \
+  --token-file ~/.config/cairnkeep/secrets/http-token \
+  --allowed-hosts memory.example.com
+```
+
+The container always adds its own loopback address for health checks.
+
+One HTTP server and bearer token form one trust domain. They are not a
+multi-tenant authorization boundary; see [Memory storage and
+deployment](storage.md).
+
+## Persistent service
+
+[`containers/compose.yaml`](../containers/compose.yaml) is a portable starting
+point:
+
+```bash
+mkdir -p containers/secrets
+openssl rand -hex 32 > containers/secrets/http-token
+chmod 600 containers/secrets/http-token
+podman compose -f containers/compose.yaml up -d
+```
+
+Set `CAIRNKEEP_VERSION` to pin the image and
+`CAIRN_MEMORY_HTTP_ALLOWED_HOSTS` when a reverse proxy sends a different host
+name. The named volume contains all memory state.
+
+For rootless Podman managed by systemd, copy the files from
+[`containers/quadlet`](../containers/quadlet) to
+`~/.config/containers/systemd/`, create the referenced secret, and reload:
+
+```bash
+printf '%s' "$(openssl rand -hex 32)" |
+  podman secret create cairnkeep-http-token -
+systemctl --user daemon-reload
+systemctl --user enable --now cairnkeep.service
+```
+
+Review the image tag, published port, allowed hosts, and backup location before
+using the sample as a long-running service.
+
+## Storage and backups
+
+Inside the server image:
+
+| Data | Container path |
+|---|---|
+| Local/legacy project database | `/data/project/.agentfs/project.db` |
+| Named/global scopes | `/data/scopes/<scope>.db` |
+| Header-routed HTTP projects | `/data/scopes/projects/<project-id>.db` |
+
+All three paths are below `/data`, so replacing the container while retaining
+the volume does not move or delete memory. Removing the volume does delete the
+store. Back up the volume with the service stopped, or use SQLite online
+backups for each database as described in [storage.md](storage.md).
+
+## Model and RAG endpoints
+
+Embedding, extraction, and document-RAG services remain optional external
+services. Supply non-secret settings with an env file:
+
+```dotenv
+CAIRN_LLM_API_URL=https://models.example.com/v1
+CAIRN_LLM_EXTRACTION_MODEL=example-chat-model
+CAIRN_MEMORY_EMBEDDING_URL=https://models.example.com/v1
+CAIRN_MEMORY_EMBEDDING_MODEL=example-embedding-model
+```
+
+For workspace containers, pass keys as files:
+
+```bash
+cairn-container workspace --repo . \
+  --env-file ~/.config/cairnkeep/container.env \
+  --secret CAIRN_LLM_API_KEY=~/.config/cairnkeep/secrets/llm-key
+```
+
+The entrypoint reads `CAIRN_LLM_API_KEY_FILE`,
+`CAIRN_MEMORY_HTTP_TOKEN_FILE`, and `ANYTHINGLLM_API_KEY_FILE`. Do not bake
+credentials, cookies, SSH private keys, or a populated `.env` into an image.
+
+## Isolated workspaces
+
+The default `sandbox` mode copies the selected repository into a persistent
+named volume. Commands can change that copy but cannot write to the host
+checkout:
+
+```bash
+cairn-container workspace --repo /path/to/repository
+```
+
+Rerunning the command with the same workspace volume resumes the copy. Use
+`--workspace-volume` when repositories have the same basename or when an
+explicit lifecycle is preferable.
+
+`shared` mode is opt-in and bind-mounts the checkout read/write:
+
+```bash
+cairn-container workspace --repo /path/to/repository --mode shared
+```
+
+The container has normal outbound network access but receives no host home
+directory, container-engine socket, or host credentials unless the operator
+mounts them. For stricter execution, add network policy and resource limits in
+the private distribution.
+
+## Private derived images
+
+A managed overlay should derive from a pinned workspace image:
+
+```dockerfile
+ARG CAIRNKEEP_VERSION
+FROM ghcr.io/cairnkeep/cairnkeep-workspace:${CAIRNKEEP_VERSION}
+
+USER root
+# Install the approved harness package from the approved registry.
+USER 10001:10001
+```
+
+The derived image may contain non-secret organization policy and launchers.
+Machine credentials and repository access remain runtime secrets. Build and
+publish that image from the private overlay repository to its approved private
+registry; do not add private configuration to the public Cairnkeep image.

package/docs/operating.md

@@ -23,6 +23,8 @@ installs. This guide covers all three in order.
 - Optional: an OpenAI-compatible LLM endpoint for memory extraction and
   embedding-ranked search. Without it, memory search degrades to substring
   matching — everything else still works.
+- Optional: rootless Podman for the containerized memory server and isolated
+  workspace base described in [Containers](containers.md).
 
 ## Setup order (Claude Code)
 
@@ -87,6 +89,17 @@ Step 3 installs into `~/.claude` (override with `CLAUDE_CONFIG_DIR` or
 Re-running `sync-claude-assets.sh --apply` is idempotent; use `--check` to see
 drift without writing. Run it again whenever you pull changes to `claude/`.
 
+To keep the memory-server runtime in a container, install the npm package for
+the launcher and replace the registration command with:
+
+```bash
+claude mcp add cairn-memory -s user -- cairn-container stdio
+```
+
+This still stores memory locally, in the `cairnkeep-data` Podman volume. It
+does not configure remote HTTP storage or containerize the harness. See
+[Containers](containers.md) for those separate deployment choices.
+
 ## Setup order (OpenCode)
 
 OpenCode is a secondary path. Steps 1, 4, and 5 are identical (use
@@ -146,6 +159,7 @@ vendor or host.
 | `CAIRN_LLM_EXTRACTION_MODEL` | Chat model for `memory-capture` extraction |
 | `CAIRN_MEMORY_EMBEDDING_URL` | Embeddings endpoint (falls back to `CAIRN_LLM_API_URL`) |
 | `CAIRN_MEMORY_EMBEDDING_MODEL` | Embedding model name (required for semantic search) |
+| `CAIRN_MEMORY_EMBEDDING_TIMEOUT_MS` | Embedding request timeout before substring fallback (default `15000`) |
 | `CAIRN_AGENTFS_BASE_DIR` | Server-side base dir for named/global memory scopes (default `~/.cairnkeep`); it does not affect `project` scope |
 | `CAIRN_GIT_PROVIDER` | Git host for collaboration commands: `github`\|`gitlab`\|`codeberg`\|`forgejo`\|`none`. See [git-providers.md](git-providers.md) |
 | `CAIRN_ROUTE_ENDPOINT` | Base URL of an already-running token-miser routing/tiering proxy (unset → the `route_check` tool is inert) |

package/docs/overlay-distributions.md

@@ -77,6 +77,14 @@ checkout. Avoid `postinstall` enrollment: installing a package must not silently
 replace machine policy. Provide an explicit enrollment command with a retained
 rollback target.
 
+For container delivery, derive from an exact
+`ghcr.io/cairnkeep/cairnkeep-workspace:<version>` tag and publish only to the
+approved private registry. Install approved harnesses and non-secret policy in
+the derived image, but inject credentials at runtime through the platform's
+secret mechanism. The public image deliberately contains no organization
+profile and never selects a remote memory service. See
+[Containers](containers.md) for the base-image and workspace contracts.
+
 ## Release and fleet safety
 
 Every release should verify:

package/docs/privacy-and-data-flow.md

@@ -36,6 +36,12 @@ Project-scoped and named/global database locations are documented in
 the remote server host; changing a storage environment variable on the client
 does not relocate that server's databases.
 
+The official container stores all databases below `/data`. A named volume
+persists them after container replacement and remains sensitive data. Sandbox
+workspace mode also retains a repository copy in its named volume. Neither
+volume is encrypted by Cairnkeep; remove it explicitly when its retention
+period ends. See [Containers](containers.md).
+
 ## Credentials and transport
 
 Keep API keys and bearer tokens out of repositories and command output. Load

package/docs/releasing.md

@@ -14,20 +14,35 @@ from a workstation.
    tests, and publishes `@cairnkeep/cli` with npm provenance.
 6. The workflow attaches the npm tarball, a CycloneDX SBOM, and SHA-256 checksums
    to the GitHub Release.
+7. The workflow publishes versioned `linux/amd64` and `linux/arm64`
+   memory-server and workspace images to GHCR. It also updates `latest` for a
+   stable release or `next` for a prerelease.
+8. Verify both image digests, SBOM attestations, provenance attestations, and an
+   anonymous pull before announcing the release.
 
 Stable versions must use a stable GitHub Release and publish to npm's `latest`
 tag. SemVer prerelease versions must use a GitHub prerelease and publish to
 `next`. A mismatch fails before publication.
 
-The workflow is safe to rerun: it skips `npm publish` when that exact version is
-already present, then regenerates and replaces the release artifacts.
+The workflow is safe to rerun: it skips `npm publish` and each versioned OCI
+image when that exact version is already present. It regenerates release
+artifacts, retries attestations against the resolved image digests, and moves
+only the `latest` or `next` channel tag. A versioned image tag is never rebuilt
+or moved.
 
 ## Repository configuration
 
 The repository must provide an `NPM_TOKEN` Actions secret authorized to publish
 `@cairnkeep/cli`. Keep that credential out of local files and rotate it according
-to the npm account's security policy. The workflow grants only `contents: write`
-and `id-token: write`; the latter is required for npm provenance.
+to the npm account's security policy. The workflow grants `contents: write`,
+`packages: write`, `attestations: write`, and `id-token: write`; the last two
+are required for registry-backed build provenance.
+
+GitHub creates each new GHCR package as private. After the first container
+release, a package administrator must change both `cairnkeep` and
+`cairnkeep-workspace` to Public in their Package settings. This is a one-time,
+irreversible visibility change for each package; subsequent releases remain
+automatic. Confirm an unauthenticated pull after changing visibility.
 
 Treat a published version as immutable. If a release is wrong, fix it in a new
 version rather than moving its tag or replacing the npm package.

package/docs/storage.md

@@ -29,6 +29,12 @@ services used to process/search memory. They do not change where the SQLite
 databases are stored. Git-provider and routing configuration do not change
 storage either.
 
+When the memory server runs in the official container, the same rule applies:
+the process stores databases below `/data`, normally backed by the
+`cairnkeep-data` named volume. Replacing the container preserves that volume;
+removing the volume removes the databases. See [Containers](containers.md) for
+the exact paths and backup boundary.
+
 ## Remote HTTP mode
 
 Remote storage is explicit. An operator starts Cairnkeep in HTTP mode on a

package/mcp-memory-server/dist/embeddings.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
+const DEFAULT_EMBEDDING_TIMEOUT_MS = 15000;
 // Resolve the embeddings endpoint from the environment. Returns null when the
 // API key, URL, or model name is not configured, so callers can fall back to
 // substring search. Point CAIRN_LLM_API_URL (or CAIRN_MEMORY_EMBEDDING_URL) at
@@ -21,7 +22,11 @@ export function getEmbeddingConfig() {
     if (!model) {
         return null;
     }
-    return { apiUrl, apiKey, model };
+    const rawTimeout = Number(process.env.CAIRN_MEMORY_EMBEDDING_TIMEOUT_MS);
+    const timeoutMs = Number.isFinite(rawTimeout) && rawTimeout >= 100 && rawTimeout <= 120000
+        ? Math.floor(rawTimeout)
+        : DEFAULT_EMBEDDING_TIMEOUT_MS;
+    return { apiUrl, apiKey, model, timeoutMs };
 }
 export function hashText(text) {
     return createHash("sha1").update(text).digest("hex");
@@ -59,7 +64,7 @@ export async function embedTexts(config, texts, chunkSize = 64) {
                 "Content-Type": "application/json",
             },
             body: JSON.stringify({ model: config.model, input: chunk }),
-            signal: AbortSignal.timeout(120000),
+            signal: AbortSignal.timeout(config.timeoutMs),
         });
         if (!response.ok) {
             const text = await response.text();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnkeep/cli",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "A durable, harness-agnostic memory + context layer for coding agents (Claude Code, OpenCode).",
   "license": "Apache-2.0",
   "type": "module",
@@ -8,7 +8,8 @@
     "access": "public"
   },
   "bin": {
-    "cairn": "bin/cairn"
+    "cairn": "bin/cairn",
+    "cairn-container": "scripts/cairn-container"
   },
   "files": [
     "bin/",
@@ -18,6 +19,7 @@
     "opencode/",
     "examples/anythingllm/",
     "examples/overlay-distribution/",
+    "containers/",
     "schemas/",
     "docs/",
     "CHANGELOG.md",

package/scripts/cairn-container

@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+VERSION=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$ROOT/package.json" | head -1)
+ENGINE=${CONTAINER_ENGINE:-podman}
+SERVER_IMAGE=${CAIRNKEEP_CONTAINER_IMAGE:-ghcr.io/cairnkeep/cairnkeep:${VERSION:-latest}}
+WORKSPACE_IMAGE=${CAIRNKEEP_WORKSPACE_IMAGE:-ghcr.io/cairnkeep/cairnkeep-workspace:${VERSION:-latest}}
+
+usage() {
+  cat <<'EOF'
+Usage:
+  cairn-container stdio [--image IMAGE] [--volume VOLUME]
+  cairn-container http --token-file FILE [--port PORT] [--name NAME]
+                       [--allowed-hosts HOSTS] [--image IMAGE]
+                       [--volume VOLUME] [--env-file FILE]
+  cairn-container workspace --repo PATH [--mode sandbox|shared]
+                            [--image IMAGE] [--data-volume VOLUME]
+                            [--workspace-volume VOLUME] [--home-volume VOLUME]
+                            [--env-file FILE] [--secret NAME=FILE]... [--] [COMMAND...]
+
+`sandbox` copies the selected repository into a named volume and leaves the
+host checkout untouched. `shared` bind-mounts the selected repository read/write.
+Secret files are mounted read-only and exposed through NAME_FILE variables.
+EOF
+}
+
+fail() {
+  echo "cairn-container: $*" >&2
+  exit 2
+}
+
+require_engine() {
+  command -v "$ENGINE" >/dev/null 2>&1 || fail "$ENGINE is not installed"
+}
+
+absolute_dir() {
+  [ -d "$1" ] || fail "not a directory: $1"
+  (cd "$1" && pwd -P)
+}
+
+absolute_file() {
+  [ -f "$1" ] || fail "not a regular file: $1"
+  [ ! -L "$1" ] || fail "refusing symlink: $1"
+  dir=$(dirname "$1")
+  base=$(basename "$1")
+  printf '%s/%s\n' "$(cd "$dir" && pwd -P)" "$base"
+}
+
+check_secret_mode() {
+  file=$1
+  if stat -c '%a' "$file" >/dev/null 2>&1; then
+    mode=$(stat -c '%a' "$file")
+  else
+    mode=$(stat -f '%Lp' "$file")
+  fi
+  case "$mode" in
+    400 | 600) ;;
+    *) fail "secret file must have mode 400 or 600: $file" ;;
+  esac
+}
+
+safe_name() {
+  printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9_.-' '-'
+}
+
+podman_base_args() {
+  PODMAN_ARGS=(
+    run --rm
+    --userns=keep-id:uid=10001,gid=10001
+    --cap-drop=all
+    --security-opt=no-new-privileges
+    --read-only
+    --tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777
+  )
+}
+
+run_stdio() {
+  image=$SERVER_IMAGE
+  volume=cairnkeep-data
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --image) [ "$#" -ge 2 ] || fail "--image requires a value"; image=$2; shift 2 ;;
+      --volume) [ "$#" -ge 2 ] || fail "--volume requires a value"; volume=$2; shift 2 ;;
+      -h | --help) usage; exit 0 ;;
+      *) fail "unknown stdio option: $1" ;;
+    esac
+  done
+
+  require_engine
+  podman_base_args
+  exec "$ENGINE" "${PODMAN_ARGS[@]}" -i \
+    --volume "$volume:/data:Z,U" \
+    "$image" stdio
+}
+
+run_http() {
+  image=$SERVER_IMAGE
+  volume=cairnkeep-data
+  name=cairnkeep
+  port=7801
+  token_file=
+  env_file=
+  allowed_hosts=
+
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --image) [ "$#" -ge 2 ] || fail "--image requires a value"; image=$2; shift 2 ;;
+      --volume) [ "$#" -ge 2 ] || fail "--volume requires a value"; volume=$2; shift 2 ;;
+      --name) [ "$#" -ge 2 ] || fail "--name requires a value"; name=$2; shift 2 ;;
+      --port) [ "$#" -ge 2 ] || fail "--port requires a value"; port=$2; shift 2 ;;
+      --token-file) [ "$#" -ge 2 ] || fail "--token-file requires a value"; token_file=$2; shift 2 ;;
+      --env-file) [ "$#" -ge 2 ] || fail "--env-file requires a value"; env_file=$2; shift 2 ;;
+      --allowed-hosts) [ "$#" -ge 2 ] || fail "--allowed-hosts requires a value"; allowed_hosts=$2; shift 2 ;;
+      -h | --help) usage; exit 0 ;;
+      *) fail "unknown http option: $1" ;;
+    esac
+  done
+
+  [ -n "$token_file" ] || fail "http mode requires --token-file"
+  token_file=$(absolute_file "$token_file")
+  check_secret_mode "$token_file"
+  case "$port" in *[!0-9]* | "") fail "invalid port: $port" ;; esac
+
+  require_engine
+  podman_base_args
+  PODMAN_ARGS+=(--detach --replace --name "$name")
+  [ -z "$env_file" ] || PODMAN_ARGS+=(--env-file "$(absolute_file "$env_file")")
+  if [ -z "$allowed_hosts" ]; then
+    allowed_hosts="localhost:${port},127.0.0.1:${port},localhost:7801,127.0.0.1:7801"
+  fi
+
+  exec "$ENGINE" "${PODMAN_ARGS[@]}" \
+    --publish "127.0.0.1:${port}:7801" \
+    --volume "$volume:/data:Z,U" \
+    --volume "$token_file:/run/secrets/http-token:ro,Z" \
+    --env MCP_HTTP_HOST=0.0.0.0 \
+    --env MCP_HTTP_PORT=7801 \
+    --env "CAIRN_MEMORY_HTTP_ALLOWED_HOSTS=$allowed_hosts" \
+    --env CAIRN_MEMORY_HTTP_TOKEN_FILE=/run/secrets/http-token \
+    "$image" http
+}
+
+run_workspace() {
+  image=$WORKSPACE_IMAGE
+  mode=sandbox
+  repo=
+  data_volume=cairnkeep-data
+  home_volume=cairnkeep-home
+  workspace_volume=
+  env_file=
+  secret_specs=()
+
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --repo) [ "$#" -ge 2 ] || fail "--repo requires a value"; repo=$2; shift 2 ;;
+      --mode) [ "$#" -ge 2 ] || fail "--mode requires a value"; mode=$2; shift 2 ;;
+      --image) [ "$#" -ge 2 ] || fail "--image requires a value"; image=$2; shift 2 ;;
+      --data-volume) [ "$#" -ge 2 ] || fail "--data-volume requires a value"; data_volume=$2; shift 2 ;;
+      --home-volume) [ "$#" -ge 2 ] || fail "--home-volume requires a value"; home_volume=$2; shift 2 ;;
+      --workspace-volume) [ "$#" -ge 2 ] || fail "--workspace-volume requires a value"; workspace_volume=$2; shift 2 ;;
+      --env-file) [ "$#" -ge 2 ] || fail "--env-file requires a value"; env_file=$2; shift 2 ;;
+      --secret) [ "$#" -ge 2 ] || fail "--secret requires NAME=FILE"; secret_specs+=("$2"); shift 2 ;;
+      --) shift; break ;;
+      -h | --help) usage; exit 0 ;;
+      *) break ;;
+    esac
+  done
+
+  [ -n "$repo" ] || fail "workspace mode requires --repo"
+  repo=$(absolute_dir "$repo")
+  case "$mode" in sandbox | shared) ;; *) fail "--mode must be sandbox or shared" ;; esac
+  if [ -z "$workspace_volume" ]; then
+    workspace_volume="cairnkeep-workspace-$(safe_name "$(basename "$repo")")"
+  fi
+
+  require_engine
+  podman_base_args
+  PODMAN_ARGS+=(-i)
+  [ ! -t 0 ] || PODMAN_ARGS+=(-t)
+  PODMAN_ARGS+=(
+    --volume "$data_volume:/data:Z,U"
+    --volume "$home_volume:/home/cairn:Z,U"
+    --env "CAIRN_WORKSPACE_MODE=$mode"
+  )
+  if [ "$mode" = shared ]; then
+    PODMAN_ARGS+=(--volume "$repo:/workspace:rw,Z")
+  else
+    PODMAN_ARGS+=(
+      --volume "$repo:/source:ro,Z"
+      --volume "$workspace_volume:/workspace:Z,U"
+    )
+  fi
+  [ -z "$env_file" ] || PODMAN_ARGS+=(--env-file "$(absolute_file "$env_file")")
+
+  for spec in "${secret_specs[@]}"; do
+    name=${spec%%=*}
+    file=${spec#*=}
+    [ "$name" != "$spec" ] || fail "--secret requires NAME=FILE"
+    case "$name" in *[!A-Z0-9_]* | "") fail "invalid secret variable name: $name" ;; esac
+    file=$(absolute_file "$file")
+    check_secret_mode "$file"
+    target=$(safe_name "$name")
+    PODMAN_ARGS+=(
+      --volume "$file:/run/secrets/$target:ro,Z"
+      --env "${name}_FILE=/run/secrets/$target"
+    )
+  done
+
+  if [ "$#" -eq 0 ]; then
+    set -- bash
+  fi
+  exec "$ENGINE" "${PODMAN_ARGS[@]}" "$image" "$@"
+}
+
+cmd=${1:-help}
+[ "$#" -eq 0 ] || shift
+case "$cmd" in
+  stdio) run_stdio "$@" ;;
+  http) run_http "$@" ;;
+  workspace) run_workspace "$@" ;;
+  help | -h | --help) usage ;;
+  *) fail "unknown command: $cmd" ;;
+esac

package/scripts/doctor.sh

@@ -28,6 +28,17 @@ fail() { printf '  [FAIL] %s\n' "$1"; fails=$((fails + 1)); }
 # reachable); a connect/timeout failure returns non-zero.
 reachable() { curl -sS -m 5 -o /dev/null "$1" >/dev/null 2>&1; }
 
+embedding_works() {
+  local payload
+  payload=$(node -e 'process.stdout.write(JSON.stringify({ model: process.argv[1], input: ["cairnkeep health check"] }))' \
+    "$CAIRN_MEMORY_EMBEDDING_MODEL") || return 1
+  curl -fsS -m 10 -o /dev/null \
+    -H "Authorization: Bearer $CAIRN_LLM_API_KEY" \
+    -H "Content-Type: application/json" \
+    --data "$payload" \
+    "${CAIRN_MEMORY_EMBEDDING_URL%/}/embeddings" >/dev/null 2>&1
+}
+
 echo "cairn doctor"
 
 # 1. Required memory server: prove that the shipped build and dependencies can
@@ -66,10 +77,12 @@ fi
 if [[ -n "${CAIRN_MEMORY_EMBEDDING_URL:-}" ]]; then
   if ! command -v curl >/dev/null 2>&1; then
     skip "embedding endpoint: curl not installed, cannot probe ${CAIRN_MEMORY_EMBEDDING_URL}"
-  elif reachable "$CAIRN_MEMORY_EMBEDDING_URL"; then
-    pass "embedding endpoint reachable (${CAIRN_MEMORY_EMBEDDING_URL})"
+  elif [[ -z "${CAIRN_LLM_API_KEY:-}" || -z "${CAIRN_MEMORY_EMBEDDING_MODEL:-}" ]]; then
+    fail "embedding configuration incomplete (CAIRN_LLM_API_KEY and CAIRN_MEMORY_EMBEDDING_MODEL are required)"
+  elif embedding_works; then
+    pass "embedding endpoint accepted model ${CAIRN_MEMORY_EMBEDDING_MODEL} (${CAIRN_MEMORY_EMBEDDING_URL})"
   else
-    fail "embedding endpoint unreachable (${CAIRN_MEMORY_EMBEDDING_URL})"
+    fail "embedding request failed for model ${CAIRN_MEMORY_EMBEDDING_MODEL} (${CAIRN_MEMORY_EMBEDDING_URL})"
   fi
 else
   skip "embedding endpoint (CAIRN_MEMORY_EMBEDDING_URL unset)"

package/scripts/probe-container-memory.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const [mode, rawUrl, token] = process.argv.slice(2);
+if (!["write", "read"].includes(mode) || !rawUrl || !token) {
+    console.error("usage: probe-container-memory.mjs <write|read> URL TOKEN");
+    process.exit(2);
+}
+
+const client = new Client({ name: "cairnkeep-container-probe", version: "1" });
+const transport = new StreamableHTTPClientTransport(new URL(rawUrl), {
+    requestInit: {
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "X-Cairn-Project": "container-smoke",
+            "X-Cairn-Scopes": "identity,project",
+        },
+    },
+});
+
+try {
+    await client.connect(transport);
+    if (mode === "write") {
+        const response = await client.callTool({
+            name: "memory_write",
+            arguments: {
+                scope: "identity",
+                key: "patterns/container-persistence",
+                value: "survives container replacement",
+            },
+        });
+        if (response.isError) throw new Error("memory_write returned an error");
+        console.log("container memory write: ok");
+    } else {
+        const response = await client.callTool({
+            name: "memory_read",
+            arguments: {
+                scope: "identity",
+                key: "patterns/container-persistence",
+            },
+        });
+        const value = response.structuredContent?.results?.[0]?.value;
+        if (value !== "survives container replacement") {
+            throw new Error("persisted memory was not recovered");
+        }
+        console.log("container memory persistence: ok");
+    }
+} finally {
+    await client.close();
+}

package/scripts/test-container-runner.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+
+capture=$tmp/args
+engine=$tmp/podman
+repo=$tmp/repository
+token=$tmp/token
+env_file=$tmp/container.env
+mkdir -p "$repo"
+printf 'token\n' > "$token"
+printf 'CAIRN_MEMORY_EMBEDDING_MODEL=example\n' > "$env_file"
+chmod 600 "$token"
+
+cat > "$engine" <<'EOF'
+#!/bin/sh
+printf '%s\n' "$@" > "$CAIRN_CONTAINER_CAPTURE"
+EOF
+chmod 755 "$engine"
+
+run_launcher() {
+  CAIRN_CONTAINER_CAPTURE=$capture CONTAINER_ENGINE=$engine \
+    "$ROOT/scripts/cairn-container" "$@"
+}
+
+has_arg() {
+  grep -Fqx -- "$1" "$capture" || {
+    echo "FAIL: missing container argument: $1" >&2
+    exit 1
+  }
+}
+
+lacks_arg() {
+  if grep -Fqx -- "$1" "$capture"; then
+    echo "FAIL: unexpected container argument: $1" >&2
+    exit 1
+  fi
+}
+
+run_launcher stdio --image example/server:1 --volume example-data
+has_arg --userns=keep-id:uid=10001,gid=10001
+has_arg --read-only
+has_arg --cap-drop=all
+has_arg example-data:/data:Z,U
+has_arg example/server:1
+has_arg stdio
+
+run_launcher http --image example/server:1 --token-file "$token" --port 8123 \
+  --allowed-hosts memory.example.com --env-file "$env_file"
+has_arg --detach
+has_arg 127.0.0.1:8123:7801
+has_arg "$token:/run/secrets/http-token:ro,Z"
+has_arg CAIRN_MEMORY_HTTP_ALLOWED_HOSTS=memory.example.com
+has_arg CAIRN_MEMORY_HTTP_TOKEN_FILE=/run/secrets/http-token
+has_arg "$env_file"
+
+chmod 644 "$token"
+if run_launcher http --token-file "$token" >"$tmp/out" 2>"$tmp/err"; then
+  echo "FAIL: permissive token file was accepted" >&2
+  exit 1
+fi
+grep -Fq "mode 400 or 600" "$tmp/err"
+chmod 600 "$token"
+
+run_launcher workspace --repo "$repo" --image example/workspace:1 \
+  --workspace-volume example-workspace -- echo sandbox
+has_arg "$repo:/source:ro,Z"
+has_arg example-workspace:/workspace:Z,U
+has_arg CAIRN_WORKSPACE_MODE=sandbox
+lacks_arg "$repo:/workspace:rw,Z"
+has_arg echo
+has_arg sandbox
+
+run_launcher workspace --repo "$repo" --mode shared --image example/workspace:1
+has_arg "$repo:/workspace:rw,Z"
+has_arg CAIRN_WORKSPACE_MODE=shared
+lacks_arg "$repo:/source:ro,Z"
+has_arg bash
+
+echo "PASS: container launcher security and workspace contracts"

package/scripts/test-container.sh

@@ -0,0 +1,183 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "${CAIRN_TEST_CONTAINERS:-0}" != 1 ]]; then
+  echo "SKIP: container integration (set CAIRN_TEST_CONTAINERS=1 to run)"
+  exit 0
+fi
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+ENGINE=${CONTAINER_ENGINE:-}
+if [[ -z "$ENGINE" ]]; then
+  if command -v podman >/dev/null 2>&1; then ENGINE=podman
+  elif command -v docker >/dev/null 2>&1; then ENGINE=docker
+  else echo "FAIL: Podman or Docker is required" >&2; exit 1
+  fi
+fi
+command -v "$ENGINE" >/dev/null 2>&1 || { echo "FAIL: container engine not found: $ENGINE" >&2; exit 1; }
+
+suffix=$$
+server_image="localhost/cairnkeep-test-server:$suffix"
+workspace_image="localhost/cairnkeep-test-workspace:$suffix"
+volume="cairnkeep-test-data-$suffix"
+sandbox_volume="cairnkeep-test-workspace-$suffix"
+name="cairnkeep-test-$suffix"
+tmp=$(mktemp -d)
+
+cleanup() {
+  "$ENGINE" rm -f "$name" >/dev/null 2>&1 || true
+  "$ENGINE" volume rm -f "$volume" "$sandbox_volume" >/dev/null 2>&1 || true
+  "$ENGINE" image rm -f "$server_image" "$workspace_image" >/dev/null 2>&1 || true
+  rm -rf "$tmp"
+}
+trap cleanup EXIT
+
+cd "$ROOT"
+"$ENGINE" build --target server -t "$server_image" -f Containerfile .
+"$ENGINE" build --target workspace -t "$workspace_image" -f Containerfile .
+
+image_user=$("$ENGINE" image inspect --format '{{.Config.User}}' "$server_image")
+[[ "$image_user" == "10001:10001" ]] || {
+  echo "FAIL: server image must run as 10001:10001, got $image_user" >&2
+  exit 1
+}
+
+"$ENGINE" volume create "$volume" >/dev/null
+node scripts/probe-memory-server.mjs --command \
+  "$ENGINE" run --rm -i --volume "$volume:/data" "$server_image" stdio
+
+if "$ENGINE" run --rm "$server_image" http >/dev/null 2>&1; then
+  echo "FAIL: HTTP mode started without a token" >&2
+  exit 1
+fi
+
+token=container-smoke-token
+printf '%s' "$token" > "$tmp/http-token"
+# Docker bind mounts preserve the host UID; world-read is acceptable for this
+# non-secret fixture. The real Podman launcher requires mode 400 or 600.
+chmod 644 "$tmp/http-token"
+port=$(node -e 'const s=require("net").createServer();s.listen(0,"127.0.0.1",()=>{console.log(s.address().port);s.close()})')
+
+start_http() {
+  "$ENGINE" run --detach --name "$name" \
+    --read-only --cap-drop=all --security-opt=no-new-privileges \
+    --tmpfs /tmp:rw,noexec,nosuid,size=64m,mode=1777 \
+    --publish "127.0.0.1:${port}:7801" \
+    --volume "$volume:/data" \
+    --volume "$tmp/http-token:/run/secrets/http-token:ro" \
+    --env MCP_HTTP_HOST=0.0.0.0 \
+    --env MCP_HTTP_PORT=7801 \
+    --env "CAIRN_MEMORY_HTTP_ALLOWED_HOSTS=127.0.0.1:${port}" \
+    --env CAIRN_MEMORY_HTTP_TOKEN_FILE=/run/secrets/http-token \
+    "$server_image" http >/dev/null
+
+  for _ in $(seq 1 50); do
+    if node scripts/probe-container-memory.mjs read "http://127.0.0.1:${port}/mcp" "$token" \
+      >"$tmp/read.out" 2>"$tmp/read.err"; then
+      return 0
+    fi
+    if ! "$ENGINE" inspect "$name" >/dev/null 2>&1; then break; fi
+    sleep 0.2
+  done
+  return 1
+}
+
+# First boot: wait for MCP, then write the canary.
+"$ENGINE" run --detach --name "$name" \
+  --read-only --cap-drop=all --security-opt=no-new-privileges \
+  --tmpfs /tmp:rw,noexec,nosuid,size=64m,mode=1777 \
+  --publish "127.0.0.1:${port}:7801" \
+  --volume "$volume:/data" \
+  --volume "$tmp/http-token:/run/secrets/http-token:ro" \
+  --env MCP_HTTP_HOST=0.0.0.0 \
+  --env MCP_HTTP_PORT=7801 \
+  --env "CAIRN_MEMORY_HTTP_ALLOWED_HOSTS=127.0.0.1:${port}" \
+  --env CAIRN_MEMORY_HTTP_TOKEN_FILE=/run/secrets/http-token \
+  "$server_image" http >/dev/null
+written=0
+for _ in $(seq 1 50); do
+  if node scripts/probe-container-memory.mjs write "http://127.0.0.1:${port}/mcp" "$token" \
+    >"$tmp/write.out" 2>"$tmp/write.err"; then
+    written=1
+    break
+  fi
+  sleep 0.2
+done
+[[ "$written" == 1 ]] || {
+  cat "$tmp/write.err" >&2
+  echo "FAIL: container HTTP server did not become ready" >&2
+  exit 1
+}
+cat "$tmp/write.out"
+"$ENGINE" exec "$name" node /usr/local/lib/cairnkeep/container-healthcheck.mjs
+"$ENGINE" rm -f "$name" >/dev/null
+
+# Replacement boot with the same volume must recover the canary.
+start_http || {
+  cat "$tmp/read.err" >&2
+  echo "FAIL: persisted memory was not readable after replacement" >&2
+  exit 1
+}
+cat "$tmp/read.out"
+"$ENGINE" rm -f "$name" >/dev/null
+
+mkdir -p "$tmp/repo"
+printf 'source\n' > "$tmp/repo/source.txt"
+
+# Shared mode deliberately writes through to the selected host repository.
+if [[ "$ENGINE" == podman ]]; then
+  "$ENGINE" run --rm --userns=keep-id:uid=10001,gid=10001 \
+    --volume "$tmp/repo:/workspace:Z" \
+    --env CAIRN_WORKSPACE_MODE=shared \
+    "$workspace_image" sh -c 'printf shared > shared.txt'
+else
+  chmod 755 "$tmp"
+  chmod 777 "$tmp/repo"
+  chmod 666 "$tmp/repo/source.txt"
+  "$ENGINE" run --rm \
+    --volume "$tmp/repo:/workspace" \
+    --env CAIRN_WORKSPACE_MODE=shared \
+    "$workspace_image" sh -c 'printf shared > shared.txt'
+fi
+[[ $(cat "$tmp/repo/shared.txt") == shared ]] || {
+  echo "FAIL: shared workspace did not write through" >&2
+  exit 1
+}
+
+# Prepare a writable named volume for the image's unprivileged runtime user.
+"$ENGINE" volume create "$sandbox_volume" >/dev/null
+if [[ "$ENGINE" == podman ]]; then
+  "$ENGINE" run --rm --userns=keep-id:uid=10001,gid=10001 \
+    --volume "$tmp/repo:/source:ro,Z" \
+    --volume "$sandbox_volume:/workspace:Z,U" \
+    --env CAIRN_WORKSPACE_MODE=sandbox \
+    "$workspace_image" sh -c 'printf sandbox > sandbox.txt'
+else
+  "$ENGINE" run --rm --user root --entrypoint sh \
+    --volume "$sandbox_volume:/workspace" "$workspace_image" \
+    -c 'chown 10001:10001 /workspace'
+  "$ENGINE" run --rm \
+    --volume "$tmp/repo:/source:ro" \
+    --volume "$sandbox_volume:/workspace" \
+    --env CAIRN_WORKSPACE_MODE=sandbox \
+    "$workspace_image" sh -c 'printf sandbox > sandbox.txt'
+fi
+[[ ! -e "$tmp/repo/sandbox.txt" ]] || {
+  echo "FAIL: sandbox mode modified the host repository" >&2
+  exit 1
+}
+if [[ "$ENGINE" == podman ]]; then
+  "$ENGINE" run --rm --userns=keep-id:uid=10001,gid=10001 \
+    --volume "$tmp/repo:/source:ro,Z" \
+    --volume "$sandbox_volume:/workspace:Z,U" \
+    --env CAIRN_WORKSPACE_MODE=sandbox \
+    "$workspace_image" sh -c 'test "$(cat sandbox.txt)" = sandbox'
+else
+  "$ENGINE" run --rm \
+    --volume "$tmp/repo:/source:ro" \
+    --volume "$sandbox_volume:/workspace" \
+    --env CAIRN_WORKSPACE_MODE=sandbox \
+    "$workspace_image" sh -c 'test "$(cat sandbox.txt)" = sandbox'
+fi
+
+echo "PASS: container stdio, guarded HTTP, persistence, shared, and sandbox modes"

package/scripts/test-doctor.sh

@@ -5,7 +5,12 @@ set -uo pipefail
 
 ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
 tmp=$(mktemp -d)
-trap 'rm -rf "$tmp"' EXIT
+server_pid=""
+cleanup() {
+  [[ -n "$server_pid" ]] && kill "$server_pid" 2>/dev/null || true
+  rm -rf "$tmp"
+}
+trap cleanup EXIT
 fail() { echo "FAIL: $1" >&2; exit 1; }
 
 doctor="$ROOT/scripts/doctor.sh"
@@ -46,4 +51,59 @@ else
   echo "  (curl absent — skipped the unreachable-endpoint case)"
 fi
 
-echo "PASS: cairn doctor (skip unconfigured, fail configured-unreachable)"
+# 4. The embedding check performs a real authenticated model request.
+if command -v curl >/dev/null 2>&1; then
+  cat > "$tmp/embedding-server.mjs" <<'EOF'
+import { createServer } from "node:http";
+import { writeFileSync } from "node:fs";
+
+const server = createServer((request, response) => {
+  const chunks = [];
+  request.on("data", (chunk) => chunks.push(chunk));
+  request.on("end", () => {
+    let body = {};
+    try { body = JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch {}
+    const valid = request.url === "/v1/embeddings"
+      && request.headers.authorization === "Bearer test-key"
+      && body.model === "test-embedding";
+    response.writeHead(valid ? 200 : 404, { "Content-Type": "application/json" });
+    response.end(JSON.stringify(valid
+      ? { data: [{ index: 0, embedding: [1, 0] }] }
+      : { error: "invalid request" }));
+  });
+});
+server.listen(0, "127.0.0.1", () => {
+  writeFileSync(process.argv[2], String(server.address().port));
+});
+EOF
+  node "$tmp/embedding-server.mjs" "$tmp/embedding-port" &
+  server_pid=$!
+  for _ in $(seq 1 50); do [[ -s "$tmp/embedding-port" ]] && break; sleep 0.1; done
+  [[ -s "$tmp/embedding-port" ]] || fail "embedding test server did not start"
+  port=$(cat "$tmp/embedding-port")
+
+  proj3="$tmp/embedding-ok"; mkdir -p "$proj3/.ai"
+  cat > "$proj3/.ai/.env" <<EOF
+CAIRN_MEMORY_EMBEDDING_URL=http://127.0.0.1:$port/v1
+CAIRN_MEMORY_EMBEDDING_MODEL=test-embedding
+CAIRN_LLM_API_KEY=test-key
+EOF
+  ( cd "$proj3" && "$doctor" ) >"$tmp/out3" 2>&1 ||
+    fail "doctor rejected a working embedding endpoint:\n$(cat "$tmp/out3")"
+  grep -q "\[PASS\] embedding endpoint accepted model test-embedding" "$tmp/out3" ||
+    fail "expected a functional embedding PASS line"
+
+  proj4="$tmp/embedding-wrong-model"; mkdir -p "$proj4/.ai"
+  cat > "$proj4/.ai/.env" <<EOF
+CAIRN_MEMORY_EMBEDDING_URL=http://127.0.0.1:$port/v1
+CAIRN_MEMORY_EMBEDDING_MODEL=missing-model
+CAIRN_LLM_API_KEY=test-key
+EOF
+  if ( cd "$proj4" && "$doctor" ) >"$tmp/out4" 2>&1; then
+    fail "doctor should reject a missing embedding model:\n$(cat "$tmp/out4")"
+  fi
+  grep -q "\[FAIL\] embedding request failed for model missing-model" "$tmp/out4" ||
+    fail "expected a functional embedding FAIL line"
+fi
+
+echo "PASS: cairn doctor (skip unconfigured, fail unreachable, probe embeddings)"

package/templates/env.example.template

@@ -7,6 +7,7 @@
 # CAIRN_LLM_API_URL=https://api.openai.com/v1
 # CAIRN_LLM_EXTRACTION_MODEL=gpt-4o-mini
 # CAIRN_MEMORY_EMBEDDING_MODEL=text-embedding-3-small
+# CAIRN_MEMORY_EMBEDDING_TIMEOUT_MS=15000
 #
 # Git host for the collaboration commands (memory-sync, repo-review, security-audit).
 # One of: github | gitlab | codeberg | forgejo | none.  See docs/git-providers.md.