Skip to content

fix(docker): persistent container + exec pattern#41

Merged
KailasMahavarkar merged 2 commits intomainfrom
fix/enforcement-hardening
Apr 10, 2026
Merged

fix(docker): persistent container + exec pattern#41
KailasMahavarkar merged 2 commits intomainfrom
fix/enforcement-hardening

Conversation

@KailasMahavarkar
Copy link
Copy Markdown
Collaborator

Summary

  • Switches install.md Option A from docker run --rm per session → persistent hyperstack-mcp container + docker exec per session
  • Adds stdin close / SIGTERM handling to src/index.ts so bun exits cleanly when the client disconnects
  • Bumps version to 1.0.1 to trigger image rebuild with the fix
  • Adds migration troubleshooting: how to clean up legacy containers

Why

Previous pattern spawned a new container for every claude invocation. Combined with missing stdin lifecycle handling, orphaned containers piled up over multiple sessions.

New pattern

# One-time setup
docker run -d --name hyperstack-mcp --restart unless-stopped \
  --memory=512m --cpus=1 \
  --entrypoint sleep \
  ghcr.io/orkait/hyperstack:main infinity
{
  "mcpServers": {
    "hyperstack": {
      "command": "docker",
      "args": ["exec", "-i", "hyperstack-mcp", "bun", "/app/src/index.ts"]
    }
  }
}

One container. All sessions exec into it. Zero per-invocation container cost.

Validated

  • Tested docker exec -i hyperstack-mcp bun /app/src/index.ts locally → MCP init response returned correctly
  • stdin close handler prevents orphan bun processes inside the persistent container

🤖 Generated with Claude Code

KailasMahavarkar and others added 2 commits April 11, 2026 03:16
Previous docker run --rm pattern spawned a new container for every
claude CLI invocation. Combined with the server not exiting on stdin
close, this left orphaned containers running across sessions.

Fix:
- install.md Option A now documents a persistent `hyperstack-mcp`
  container started once with `sleep infinity` as PID 1, and each
  MCP session `docker exec`s a fresh bun process into it. One container
  total, zero per-invocation container startup cost.
- src/index.ts now handles stdin close / SIGTERM / SIGINT to exit
  cleanly when the client disconnects, preventing zombie bun processes
  inside the persistent container.
- Troubleshooting section adds a cleanup command for users migrating
  from the legacy docker run --rm config.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Triggers rebuild of ghcr.io image with stdin close handler fix.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@KailasMahavarkar KailasMahavarkar merged commit 7c9b977 into main Apr 10, 2026
4 checks passed
@KailasMahavarkar KailasMahavarkar deleted the fix/enforcement-hardening branch April 10, 2026 21:52
KailasMahavarkar added a commit that referenced this pull request Apr 14, 2026
fix(docker): persistent container + exec pattern
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant