Skip to content

Self-hosted MCP server + dashboard giving Claude Code, Cursor & Hermes agents shared long-term memory over a git-backed markdown vault. Agent-native, Obsidian-compatible second brain — markdown RAG, no vector DB.

fix(deploy): stdio image must refuse to boot as a web service (#9)

Ronalds Palacis28d1db07ef27
diff --git a/DEPLOY.md b/DEPLOY.md
index 7a1d760..af8d674 100644
--- a/DEPLOY.md
+++ b/DEPLOY.md
@@ -10,6 +10,12 @@ workspace is what the dashboard shows and what agents read/write.
3. Copy the Client ID + Secret.
## 2. Railway
+
+> **Deploying from a prebuilt image rather than the repo?** Use `ghcr.io/rwnalds/engram-app:latest`
+> and set the healthcheck path to `/api/health`. The similarly-named `ghcr.io/rwnalds/engram` is the
+> **stdio** MCP server for Claude Desktop/Cursor — it speaks JSON-RPC on stdin/stdout and never opens
+> a port, so as a web service it 502s no matter what else is configured.
+
1. **New Project → Deploy from GitHub repo** → this repo (builds via root `Dockerfile`).
2. **Add a Volume**, mount path `/data`.
3. **Variables** — only these five are required on the host; the rest are optional and
diff --git a/README.md b/README.md
index 360fda0..b1da046 100644
--- a/README.md
+++ b/README.md
@@ -197,7 +197,17 @@ VAULT_DIR=/path/to/your/obsidian-or-markdown/vault bun dev
bun run mcp:stdio /path/to/your/vault # defaults to ./sample-vault
```
- Same `brain_*` tools. Image: `Dockerfile.mcp` (`CMD ["bun", "scripts/mcp-stdio.ts"]`).
+ Same `brain_*` tools. Built from `Dockerfile.mcp`.
+
+**Each mode ships as its own image, and they are not interchangeable:**
+
+| Image | Mode | Use it for |
+|---|---|---|
+| `ghcr.io/rwnalds/engram-app` | HTTP — dashboard + `/api/mcp` | **Railway, Render, Fly, any host.** This is the one you deploy. |
+| `ghcr.io/rwnalds/engram` | stdio — JSON-RPC on stdin/stdout | Claude Desktop, Cursor, MCP registries. Never opens a port. |
+
+Deploying the stdio image as a web service is the one mistake worth calling out: it can only 502,
+because there is nothing listening. It now refuses to start on a PaaS and tells you this instead.
## MCP tools
@@ -232,6 +242,10 @@ page — only auth/infra bootstrap vars live on the host. Full setup: **[DEPLOY.
- **Railway:** New Project → *Deploy from GitHub repo* → add a Volume at `/data`.
- **Render:** one-click via the bundled `render.yaml` (Docker + a `/data` disk).
+Deploying from a prebuilt image instead of the repo? Use **`ghcr.io/rwnalds/engram-app:latest`** —
+not `engram:latest`, which is the stdio server and cannot answer HTTP. Set the healthcheck to
+`/api/health`.
+
## FAQ
**How do I give Claude Code long-term memory?**
diff --git a/scripts/mcp-stdio.ts b/scripts/mcp-stdio.ts
index 018938b..2842674 100644
--- a/scripts/mcp-stdio.ts
+++ b/scripts/mcp-stdio.ts
@@ -14,7 +14,56 @@
* be resolved into env BEFORE the tools module loads (config reads it at import), so imports are
* dynamic, inside main().
*/
+/**
+ * The stdio server speaks JSON-RPC on stdin/stdout and never opens a port. Deployed to a PaaS as a
+ * web service it fails like this: it prints "ready", reads EOF from a stdin nothing is attached to,
+ * exits 0 — and the platform reports a *successful* deploy whose URL 502s forever. Nothing in the
+ * logs looks wrong, which is what makes it expensive: engram's own Railway instance sat broken on
+ * exactly this, deployed from the wrong one of the two published images.
+ *
+ * The two are not interchangeable:
+ * ghcr.io/rwnalds/engram stdio — Claude Desktop, Cursor, registries (Dockerfile.mcp)
+ * ghcr.io/rwnalds/engram-app HTTP — dashboard + /api/mcp, what a PaaS runs (Dockerfile)
+ *
+ * So refuse, loudly and non-zero, when we can tell we're a web service on a PaaS: a crashed deploy
+ * with an explanation beats a green one that never answers. Only unambiguous platform markers
+ * count — PORT is an ordinary local env var and must never trip this. Running the stdio server
+ * inside a deployed container is legitimate, so ENGRAM_ALLOW_STDIO_ON_PAAS=1 overrides.
+ */
+const PAAS_MARKERS: ReadonlyArray<readonly [envVar: string, platform: string]> = [
+ ["RAILWAY_ENVIRONMENT", "Railway"],
+ ["RENDER", "Render"],
+ ["FLY_APP_NAME", "Fly.io"],
+ ["DYNO", "Heroku"],
+ ["KOYEB_APP_NAME", "Koyeb"],
+];
+
+function refuseIfDeployedAsWebService() {
+ if (process.env.ENGRAM_ALLOW_STDIO_ON_PAAS) return;
+ const marker = PAAS_MARKERS.find(([envVar]) => process.env[envVar]);
+ if (!marker) return;
+
+ console.error(
+ [
+ "",
+ `[engram] Refusing to start: this is the stdio MCP image, running on ${marker[1]}.`,
+ "",
+ " It serves JSON-RPC over stdin/stdout and never opens a port, so a web service built from",
+ " it can only 502 — and by exiting 0 it would report a deploy that 'succeeded'.",
+ "",
+ " Deploy the app image instead: ghcr.io/rwnalds/engram-app:latest",
+ " dashboard + HTTP MCP at /api/mcp · healthcheck /api/health · volume mounted at /data",
+ "",
+ " Meant to run the stdio server inside a deployed container? Set ENGRAM_ALLOW_STDIO_ON_PAAS=1",
+ "",
+ ].join("\n"),
+ );
+ process.exit(1);
+}
+
async function main() {
+ refuseIfDeployedAsWebService();
+
const vaultArg = process.argv[2];
if (vaultArg) process.env.VAULT_DIR = vaultArg;
// Local mode: never touch git, never require an Anthropic key for introspection.