mercury-agent 0.4.5

package/docs/configuration.md

@@ -0,0 +1,54 @@
+# Configuration
+
+Mercury reads settings from **environment variables** (`MERCURY_*`) and, optionally, a project **`mercury.yaml`** file in the current working directory.
+
+**Product / design spec:** [prd-config-load.md](prd-config-load.md) (config load: YAML + env precedence, security, non-goals).
+
+## Precedence
+
+1. If a `MERCURY_*` variable is **set** in the environment (the key exists, including empty string), its value wins.
+2. Otherwise, if **`mercury.yaml`** (or **`mercury.yml`**) exists in `cwd`, values from that file apply.
+3. Otherwise, built-in defaults from `config.ts` apply.
+
+Set **`MERCURY_CONFIG_FILE`** to an explicit path to load a different file. Set it to **`""`** (empty) or **`none`** to **disable** loading any file (useful for tests or when you want env/defaults only).
+
+Relative paths in `MERCURY_CONFIG_FILE` are resolved against `cwd`.
+
+## Secrets (never use `mercury.yaml` for these)
+
+These must be supplied via environment variables only; they are **not** read from YAML:
+
+- `MERCURY_API_SECRET`
+- `MERCURY_CHAT_API_KEY`
+- `MERCURY_DISCORD_GATEWAY_SECRET`
+
+Platform tokens, provider API keys, and extension keys (e.g. `MERCURY_TELEGRAM_BOT_TOKEN`, `MERCURY_BRAVE_API_KEY`) are also **env-only** today—they are not part of the YAML schema.
+
+## YAML layout
+
+See [`resources/templates/mercury.example.yaml`](../resources/templates/mercury.example.yaml) for a commented template. Supported sections include `server`, `model`, `ingress`, `runtime`, `trigger`, `context`, `conditional_context`, `compaction`, `agent`, `discord`, `telegram`, `media`, and `permissions`.
+
+The `context:` block seeds default conversation-context behavior into the `main` space on first boot:
+
+```yaml
+context:
+  mode: context              # clear | context (default: context)
+  window_size: 10            # 1-50 (default: 10). Sliding-window turns when mode=context.
+  reply_chain_depth: 10      # 1-50 (default: 10). Reply chain depth when mode=clear.
+```
+
+Per-space overrides via `mrctl config set context.<key> <value>` always win over YAML defaults; YAML re-reads on restart do not overwrite an existing space row.
+
+You may also set a top-level **`model_chain`** array as an alias for `model.chain`.
+
+## Model chain
+
+In YAML, use a list of `{ provider, model }` objects under `model.chain` (max 4 legs). The same rules apply as for `MERCURY_MODEL_CHAIN` JSON.
+
+Optional **`model.capabilities`** may be a mapping; it is applied like `MERCURY_MODEL_CAPABILITIES` JSON.
+
+### Removed: `provider: cursor`
+
+The **Cursor Agent CLI** integration has been removed. All model legs use **pi** with standard providers (`anthropic`, `openai`, `google`, `mistral`, `groq`, `openrouter`, etc.).
+
+If your chain still has `provider: cursor`, the agent run **fails fast** with an error that points here. Switch to the **native provider** for the model you want (for example `anthropic` for Claude, `openai` for GPT) and set the matching **`MERCURY_*_API_KEY`**.

package/docs/container-lifecycle.md

@@ -0,0 +1,349 @@
+# Container Lifecycle
+
+Mercury runs agent code inside Docker containers. This document covers how containers are managed, what happens when they fail, and how the system recovers.
+
+## Deployment Topology
+
+Mercury uses a two-layer container model. The layers differ between local and production (Hetzner) deployments.
+
+### Local (`mercury run`)
+
+```
+Local machine
+└── mercury run  (host process)
+    └── mercury-<ts>-<id>  (inner container, ephemeral --rm, one per message)
+```
+
+Mercury runs directly on the host. Each incoming message spawns a short-lived inner container to run the Claude agent, which is deleted automatically on exit (`--rm`).
+
+### Production node
+
+```
+Production node
+├── orchestrator                (manages the node — start/stop/update agents)
+├── traefik                     (routes *.baseDomain → agent containers)
+├── mercury-agent-<user1>       (outer container, persistent, one per tenant)
+│   └── mercury-<ts>-<id>       (inner container, ephemeral --rm, one per message)
+├── mercury-agent-<user2>       (outer container, persistent)
+│   └── mercury-<ts>-<id>
+└── ...
+```
+
+A single node hosts many tenants. Each user's Mercury process runs inside its own persistent outer container (`--restart=unless-stopped`). Inside that, per-message inner containers work exactly as they do locally.
+
+### Why outer containers in production?
+
+| Concern | How outer containers solve it |
+|---|---|
+| Tenant isolation | Each agent runs in its own container — can't interfere with others |
+| Resource limits | `--memory` and `--cpus` enforced per-agent by the orchestrator |
+| Routing | Traefik labels assign each container its own subdomain (`agentId.baseDomain`) |
+| Independent lifecycle | orchestrator can start/stop/restart/update one agent without touching others |
+| Persistent state | Named Docker volume per agent (`mercury-<agentId>-data`) holds SQLite DB, WhatsApp auth, and spaces |
+
+### Comparison
+
+| | Local (`mercury run`) | Production node |
+|---|---|---|
+| Mercury process | host process | `mercury-agent-<id>` container (`-d --restart=unless-stopped`) |
+| Per-message agent | ephemeral container (`--rm`) | ephemeral container (`--rm`) inside the outer container |
+| Logs | lost on exit | retained — `--log-opt max-size=20m --log-opt max-file=3` |
+| State | host filesystem | named Docker volume |
+
+### Debugging inner container logs
+
+Inner containers are `--rm` and their logs are gone once they exit. To capture them you must stream live while the container runs:
+
+```bash
+# Watch for the container to appear
+docker ps --filter "label=mercury.managed=true"
+
+# Tail its logs while it runs
+docker logs -f mercury-<ts>-<id>
+```
+
+On a production node, the outer container logs are always available via SSH:
+```bash
+docker logs mercury-agent-<agentId> -f
+```
+
+---
+
+## Container Identity
+
+Each container is tagged for tracking and cleanup:
+
+| Property | Format | Purpose |
+|----------|--------|---------|
+| **Name** | `mercury-<timestamp>-<id>` | Unique identifier for logging/debugging |
+| **Label** | `mercury.managed=true` | Identifies mercury-owned containers for cleanup |
+
+Example:
+```
+docker ps --filter "label=mercury.managed=true"
+CONTAINER ID   IMAGE              NAMES
+a1b2c3d4e5f6   mercury-agent     mercury-1709312456789-1
+```
+
+## Timeout
+
+Containers have a maximum runtime to prevent runaway processes.
+
+| Config | Env Var | Default | Range |
+|--------|---------|---------|-------|
+| `containerTimeoutMs` | `MERCURY_CONTAINER_TIMEOUT_MS` | 5 minutes | 10s – 1h |
+
+When a container exceeds the timeout:
+1. Container is killed via `docker kill`
+2. `ContainerError` thrown with `reason: "timeout"`
+3. User sees: "Container timed out."
+4. Queue unblocks, next message can proceed
+
+The host always injects a resolved **model chain** into the container (after `MERCURY_*` passthrough) so retries and fallbacks use the same policy Mercury loaded at startup:
+
+| In-container env | Source (host) | Purpose |
+|------------------|---------------|---------|
+| `MODEL_CHAIN` | `resolvedModelChain` (from `MERCURY_MODEL_CHAIN` or primary+fallback) | Ordered `{ provider, model }` legs (max 4) |
+| `MODEL_RETRY_MAX_PER_LEG` | `MERCURY_MODEL_MAX_RETRIES_PER_LEG` | Extra attempts per leg for transient errors |
+| `MODEL_CHAIN_BUDGET_MS` | `effectiveModelChainBudgetMs` | Wall-clock budget for the whole chain (clamped below container timeout) |
+
+## Error Types
+
+Container failures are classified by `ContainerError`:
+
+| Reason | Exit Code | Cause | User Message |
+|--------|-----------|-------|--------------|
+| `timeout` | — | Exceeded `containerTimeoutMs` | "Container timed out." |
+| `oom` | 137 | SIGKILL (OOM, resource limits, or manual kill) | "Container was killed (possibly out of memory)." |
+| `aborted` | — | User sent `stop` command | "Stopped current run." |
+| `error` | non-zero | Agent crashed or failed | *(error thrown, logged)* |
+
+Exit code 137 = 128 + 9 (SIGKILL), typically from Docker's OOM killer.
+
+## Orphan Cleanup
+
+If the host process crashes or restarts while containers are running, those containers become orphans. On startup, mercury cleans them up:
+
+```
+Startup
+  │
+  └─► runtime.initialize()
+        │
+        └─► containerRunner.cleanupOrphans()
+              │
+              ├─► docker ps -a --filter "label=mercury.managed=true"
+              ├─► docker rm -f <container-ids>
+              └─► Log: "Cleaned up N orphaned container(s)"
+```
+
+This ensures:
+- No zombie containers consuming resources
+- No blocked space queues from previous runs
+- Clean state before accepting new work
+
+## Lifecycle Diagram
+
+```
+Message received
+  │
+  ├─► Queue (one per space)
+  │
+  ├─► Spawn container
+  │     • --name mercury-<ts>-<id>
+  │     • --label mercury.managed=true
+  │     • --rm (auto-remove on exit)
+  │
+  ├─► Start timeout timer
+  │
+  ├─► Wait for completion
+  │     │
+  │     ├─► Success (exit 0) → parse reply + scan outbox/ → respond
+  │     ├─► Timeout → kill container → ContainerError(timeout)
+  │     ├─► OOM (exit 137) → ContainerError(oom)
+  │     ├─► Aborted → ContainerError(aborted)
+  │     └─► Other failure → ContainerError(error)
+  │
+  └─► Cleanup
+        • Clear timeout timer
+        • Remove from tracking map
+        • Queue unblocks (finally block)
+```
+
+## Configuration
+
+```bash
+# Set container timeout to 10 minutes
+export MERCURY_CONTAINER_TIMEOUT_MS=600000
+
+# Use a preset image from GitHub Container Registry
+export MERCURY_AGENT_IMAGE=ghcr.io/michaelliv/mercury-agent:latest   # Full (default)
+export MERCURY_AGENT_IMAGE=ghcr.io/michaelliv/mercury-agent:minimal  # Lightweight
+```
+
+## Sandboxing (Bubblewrap)
+
+Mercury uses a two-layer isolation model:
+
+1. **Docker** — isolates the agent from the host
+2. **Bubblewrap** — restricts the pi process within the container (defense-in-depth)
+
+The pi agent runs inside `bwrap`, which creates a minimal mount namespace with only the paths needed for the agent: workspace (`/spaces`), app code (`/app`), docs (`/docs`), and runtime dirs (`/root`, `/usr`, `/etc`, `/proc`, `/dev`, `/tmp`). This limits blast radius if the agent is compromised.
+
+| Env Var | Purpose |
+|---------|---------|
+| `MERCURY_CONTAINER_BWRAP_DOCKER_COMPAT=1` | **Host only.** Adds `docker run --security-opt seccomp=unconfined --cap-add SYS_ADMIN` so `bwrap` can nest inside the agent container (e.g. Docker Desktop). Keeps bubblewrap on. |
+| `MERCURY_DISABLE_BUBBLEWRAP=1` | Disable bubblewrap; run pi directly (last resort / debugging) |
+
+If you see `bwrap: Creating new namespace failed: Operation not permitted`, try **`MERCURY_CONTAINER_BWRAP_DOCKER_COMPAT=1`** first so you keep defense-in-depth. Only use `MERCURY_DISABLE_BUBBLEWRAP=1` if compat mode is not enough.
+
+Custom images must install `bubblewrap` for sandboxing to work.
+
+## Agent Image Presets
+
+Mercury publishes two image presets to GitHub Container Registry:
+
+| Preset | Size | Contents |
+|--------|------|----------|
+| `ghcr.io/michaelliv/mercury-agent:latest` | ~2.8GB | Full devcontainer: Bun, Node.js, Python, Go, git, build tools |
+| `ghcr.io/michaelliv/mercury-agent:minimal` | ~1.9GB | Lightweight runtime: Bun + pi + Chromium deps |
+
+Images are published on each release. Version-specific tags are also available (e.g., `:0.2.0`, `:0.2.0-minimal`).
+
+### Building Locally
+
+To build images locally instead of pulling from the registry:
+```bash
+./container/build.sh all      # Both presets
+./container/build.sh latest   # Full image only (default)
+./container/build.sh minimal  # Lightweight image only
+```
+
+Then use `mercury-agent:latest` or `mercury-agent:minimal` (without the ghcr.io prefix).
+
+## Custom Agent Images
+
+You can use custom Docker images via `MERCURY_AGENT_IMAGE`.
+
+### Requirements
+
+Your image **must** have:
+- `bun` runtime
+- `pi` CLI (`@mariozechner/pi-coding-agent`)
+- `bubblewrap` (for agent sandboxing)
+- `mrctl` wrapper (copied during build)
+Extension CLIs (e.g. `pinchtab`, `napkin`, `gws`) are installed in derived images at runtime based on `.mercury/extensions/*` declarations.
+
+### Entry Point
+
+The image must use this entrypoint:
+```dockerfile
+ENTRYPOINT ["bun", "run", "/app/src/agent/container-entry.ts"]
+```
+
+### Required Files
+
+Copy these files into your image at `/app/`:
+```dockerfile
+COPY src/agent/container-entry.ts /app/src/agent/container-entry.ts
+COPY src/agent/pi-failure-class.ts /app/src/agent/pi-failure-class.ts
+COPY src/agent/pi-jsonl-parser.ts /app/src/agent/pi-jsonl-parser.ts
+COPY src/agent/preferences-prompt.ts /app/src/agent/preferences-prompt.ts
+COPY src/cli/mrctl.ts /app/src/cli/mrctl.ts
+COPY src/cli/mrctl-http.ts /app/src/cli/mrctl-http.ts
+COPY src/extensions/reserved.ts /app/src/extensions/reserved.ts
+COPY src/types.ts /app/src/types.ts
+```
+
+### mrctl Setup
+
+Create the mrctl wrapper:
+```dockerfile
+RUN echo '#!/bin/sh\nbun run /app/src/cli/mrctl.ts "$@"' > /usr/local/bin/mrctl && \
+    chmod +x /usr/local/bin/mrctl
+```
+
+### Volume Mounts
+
+Mercury mounts these paths into containers:
+- `/spaces` — Space workspaces (read/write)
+- `/home/mercury/.pi/agent` — Global agent config, skills, auth (read/write)
+- `/docs/mercury/` — Self-documentation (read-only)
+
+### Example Custom Dockerfile
+
+```dockerfile
+FROM your-base-image:tag
+
+# Install Bun
+RUN curl -fsSL https://bun.sh/install | bash
+ENV PATH="/home/mercury/.bun/bin:$PATH"
+
+# Install required CLIs
+RUN bun add -g @mariozechner/pi-coding-agent
+
+# Optional: install Playwright/Chromium if your extensions need browser automation
+RUN bunx playwright install chromium
+
+WORKDIR /app
+
+# Copy Mercury agent files
+COPY src/agent/container-entry.ts /app/src/agent/container-entry.ts
+COPY src/agent/pi-failure-class.ts /app/src/agent/pi-failure-class.ts
+COPY src/agent/pi-jsonl-parser.ts /app/src/agent/pi-jsonl-parser.ts
+COPY src/agent/preferences-prompt.ts /app/src/agent/preferences-prompt.ts
+COPY src/cli/mrctl.ts /app/src/cli/mrctl.ts
+COPY src/cli/mrctl-http.ts /app/src/cli/mrctl-http.ts
+COPY src/extensions/reserved.ts /app/src/extensions/reserved.ts
+COPY src/types.ts /app/src/types.ts
+
+# Setup mrctl
+RUN echo '#!/bin/sh\nbun run /app/src/cli/mrctl.ts "$@"' > /usr/local/bin/mrctl && \
+    chmod +x /usr/local/bin/mrctl
+
+ENTRYPOINT ["bun", "run", "/app/src/agent/container-entry.ts"]
+```
+
+### Validation
+
+When using a custom image (not `mercury-agent:*`), Mercury logs a warning at startup:
+```
+WARN  Using custom agent image
+      image: your-image:tag
+      note: Ensure image has: bun, pi, bubblewrap, mrctl
+```
+
+## API
+
+### `AgentContainerRunner`
+
+```ts
+runner.cleanupOrphans()     // Remove orphaned containers (called on startup)
+runner.reply(input)         // Run container, returns ContainerResult (reply + outbox files)
+runner.abort(spaceId)       // Kill container for a space
+runner.killAll()            // Kill all running containers (shutdown)
+runner.isRunning(spaceId)   // Check if container is active
+runner.activeCount          // Number of running containers
+```
+
+### `MercuryCoreRuntime`
+
+```ts
+await runtime.initialize()  // Call before accepting work (runs orphan cleanup)
+```
+
+### `ContainerError`
+
+```ts
+import { ContainerError } from "./agent/container-error.js";
+
+// Properties
+error.reason    // "timeout" | "oom" | "aborted" | "error"
+error.exitCode  // number | null
+error.message   // Human-readable description
+
+// Factory methods
+ContainerError.timeout(spaceId)
+ContainerError.oom(spaceId, exitCode)
+ContainerError.aborted(spaceId)
+ContainerError.error(exitCode, output)
+```

package/docs/context-architecture.md

@@ -0,0 +1,87 @@
+# Context Architecture
+
+Mercury uses a three-layer approach to give the agent the right context for every request — deterministic, bounded, and never accidentally referencing stale history.
+
+## The Three Layers
+
+### Layer 1 — Identity (always present)
+
+Built by `buildSystemPrompt()` in `container-entry.ts`:
+
+- `AGENTS.md` — the space's agent persona and instructions
+- System capabilities (tools, permissions, platform)
+- Moderation rules
+- Memory guidance (see Layer 2)
+
+This layer is static per space configuration.
+
+### Layer 2 — Episodic Memory (per-space, curated)
+
+A `MEMORY.md` file that lives in the space's workspace directory (alongside `AGENTS.md`). If it exists, it is injected as `<episodic_memory>` XML at the start of every prompt.
+
+The agent can read and write `MEMORY.md` freely. It should use it to:
+- Record significant events, decisions, or patterns
+- Summarise long threads into compact notes
+- Remember user preferences or recurring context
+- Note anything that would be annoying to re-explain each session
+
+Keep it concise (~1500 tokens max). Use `mrctl recall` to search the full message archive when more history is needed.
+
+### Layer 3 — Searchable Archive (on demand)
+
+The full message history lives in SQLite and is searchable via `mrctl recall <query>`. The agent uses this explicitly when it needs to look up something specific from the past.
+
+The sliding window (see below) makes the most recent history available automatically — `mrctl recall` is for reaching further back.
+
+---
+
+## Per-Request Context
+
+Every request runs with `--no-session` (no pi session file). Continuity across requests comes from:
+
+1. **Sliding window** — the last N user+assistant turn pairs fetched from SQLite via `getRecentTurns(spaceId, 10)`, injected as `<history>` XML
+2. **MEMORY.md** — injected as `<episodic_memory>` if it exists
+3. **Ambient messages** — platform-sourced messages (e.g., thread context) passed separately
+
+The session boundary (`chat_state.min_message_id`) excludes messages older than the last `compact` call from the sliding window. Run `mrctl compact` to reset the boundary and start fresh.
+
+### Prompt structure (inside container)
+
+```
+<system>
+  [identity: AGENTS.md + capabilities + memory guidance]
+</system>
+
+<caller>…</caller>
+<episodic_memory>…</episodic_memory>   ← MEMORY.md (if present)
+<history>                               ← sliding window from DB
+  <turn timestamp="…">
+    <user>…</user>
+    <assistant>…</assistant>
+  </turn>
+  …
+</history>
+<ambient_messages>…</ambient_messages>
+<preferences>…</preferences>
+<attachments>…</attachments>
+
+[user prompt text]
+```
+
+---
+
+## Why Not a Pi Session File?
+
+Pi session files (`.mercury.session.jsonl`) are pi's intra-run working memory — essential for tracking tool calls within a single agent run. But accumulating them across separate user requests causes problems:
+
+- The session file grows unbounded
+- Loading it on every request exposes the agent to the entire conversation history
+- The agent unexpectedly references old requests
+
+By always using `--no-session`, each run starts clean. Cross-request continuity comes from the explicit, bounded sliding window instead.
+
+---
+
+## Compact
+
+`mrctl compact` (or `POST /api/compact`) sets the session boundary to the latest message ID. Messages older than this boundary are excluded from the sliding window, so the agent starts with a clean slate while the archive remains searchable via `mrctl recall`.

package/docs/deployment.md

@@ -0,0 +1,199 @@
+# Deployment
+
+Mercury can run as a background daemon with automatic restart on crash.
+
+For **environment variables vs `mercury.yaml`**, see [configuration.md](configuration.md).
+
+## Quick Setup
+
+```bash
+# Install as user service (recommended)
+mercury service install
+
+# Check status
+mercury service status
+
+# View logs
+mercury service logs -f
+
+# Uninstall when needed
+mercury service uninstall
+```
+
+## Platform Support
+
+### Linux (systemd)
+
+Mercury installs as a systemd user service by default:
+
+```bash
+# Install as user service (no sudo required)
+mercury service install
+
+# Or explicitly specify user mode
+mercury service install --user
+```
+
+The service file is written to `~/.config/systemd/user/mercury.service`.
+
+**Manual systemd commands:**
+
+```bash
+# Check status
+systemctl --user status mercury
+
+# Restart service
+systemctl --user restart mercury
+
+# Stop service
+systemctl --user stop mercury
+
+# View logs (follow mode)
+journalctl --user -u mercury -f
+```
+
+**User service notes:**
+- No root/sudo required
+- Service runs under your user account
+- Starts automatically on user login
+- For 24/7 operation without login, enable lingering: `loginctl enable-linger $USER`
+
+### macOS (launchd)
+
+Mercury installs as a launchd user agent:
+
+```bash
+mercury service install
+```
+
+The plist is written to `~/Library/LaunchAgents/com.mercury.agent.plist`.
+
+Logs are written to `.mercury/logs/` in your project directory:
+- `mercury.log` — stdout
+- `mercury.error.log` — stderr
+
+**Manual launchd commands:**
+
+```bash
+# Check if running
+launchctl list com.mercury.agent
+
+# Stop service
+launchctl stop com.mercury.agent
+
+# Start service
+launchctl start com.mercury.agent
+
+# Unload completely
+launchctl unload ~/Library/LaunchAgents/com.mercury.agent.plist
+
+# View logs
+tail -f .mercury/logs/mercury.log
+```
+
+### Windows
+
+Not currently supported via `mercury service`. Options:
+
+1. **Task Scheduler**: Create a task that runs `mercury run` at startup
+2. **NSSM**: Use [NSSM](https://nssm.cc/) to wrap Mercury as a Windows service
+3. **PM2**: Use `pm2 start "mercury run" --name mercury`
+
+## Auto-Restart Behavior
+
+Both systemd and launchd are configured to automatically restart Mercury if it crashes:
+
+- **systemd**: `Restart=on-failure` with 10-second delay
+- **launchd**: `KeepAlive=true` for immediate restart
+
+## Working Directory
+
+The service is configured to run from the directory where you ran `mercury service install`. This means:
+
+- Your `.env` file is loaded from that directory
+- Relative paths in configuration resolve from there
+- The `.mercury/` data directory is in that location
+
+If you move your Mercury project, you'll need to uninstall and reinstall the service.
+
+## Logs
+
+### Linux
+
+Logs go to the systemd journal:
+
+```bash
+# View recent logs
+mercury service logs
+
+# Follow logs in real-time
+mercury service logs -f
+
+# Or use journalctl directly
+journalctl --user -u mercury -n 100
+journalctl --user -u mercury --since "1 hour ago"
+```
+
+### macOS
+
+Logs go to files in `.mercury/logs/`:
+
+```bash
+# View recent logs
+mercury service logs
+
+# Follow logs in real-time
+mercury service logs -f
+
+# Or use tail directly
+tail -f .mercury/logs/mercury.log
+```
+
+## Troubleshooting
+
+### Service fails to start
+
+1. Run `mercury doctor` to check for common issues
+2. Check that `mercury run` works manually first
+3. Verify `.env` exists and is configured
+4. Check logs for errors: `mercury service logs`
+
+### Permission denied (Linux)
+
+If you see permission errors with system-level install, use user mode:
+
+```bash
+mercury service install --user
+```
+
+### Service not found after reboot (Linux)
+
+Enable user lingering so services start without login:
+
+```bash
+loginctl enable-linger $USER
+```
+
+### Logs not appearing (macOS)
+
+Check that the log directory exists:
+
+```bash
+mkdir -p .mercury/logs
+```
+
+Then reinstall the service:
+
+```bash
+mercury service uninstall
+mercury service install
+```
+
+### Multiple instances
+
+Each Mercury project should be installed as a separate service from its own directory. The service name is always `mercury`, so only one instance can be managed per user account.
+
+For multiple instances, consider:
+- Running different instances under different user accounts
+- Using Docker/Podman with separate containers
+- Manual systemd service files with unique names