Poke PC

macOS App

The macOS app is downloadable from GitHub Releases. You can download latest DMG file from here

Related MCP server: mcp2term

CLI

npx poke-pc

A Dockerized MCP worker with persistent terminal control, automatic Poke tunnel connection, and optional command status notifications to Poke.

License: MIT

Introduce Poke PC to your Poke ⭐

Use this direct recipe link:

https://poke.com/r/kWWE0sbthIQ

You can also copy RECIPE.md into your Poke configuration.

Quick Start 🚀

The command runs an interactive setup that:

• checks Docker

• runs Poke SDK device login if credentials are missing

• stores OAuth token in ~/.config/poke/credentials.json

• asks if command status notifications to Poke should be enabled (default: yes)

• creates persistent volume and starts container in detached mode (no --rm)

Useful after setup:

docker logs -f poke-pc
docker exec -it poke-pc tail -f /root/poke-pc/terminal/history.ndjson

Authentication 🔐

• Tunnel and notifications use the same OAuth token credentials from ~/.config/poke/credentials.json.

• Quickstart uses Poke SDK device login to generate credentials automatically.

• No separate manual key setup is required.

If credentials are missing on first run, the app shows a login URL and code in logs.

Manual Docker Run

docker run -d \
  --name poke-pc \
  -p 3000:3000 \
  -e POKE_TUNNEL_NAME="poke-pc" \
  -e MCP_PUBLIC_URL="http://127.0.0.1:3000/mcp" \
  -e POKE_PC_AUTOREGISTER_WEBHOOK="true" \
  -v poke_pc_state:/root/poke-pc \
  -v "$HOME/.config/poke:/root/.config/poke" \
  ghcr.io/calganaygun/poke-pc:latest

To run without command status notifications:

-e POKE_PC_AUTOREGISTER_WEBHOOK="false"

Configuration

Copy .env.example and adjust as needed.

Common defaults:

• POKE_TUNNEL_NAME=poke-pc

• MCP_HOST=0.0.0.0

• MCP_PORT=3000

• MCP_PUBLIC_URL=http://127.0.0.1:3000/mcp

• POKE_PC_AUTOREGISTER_WEBHOOK=true

Bootstrap config can be loaded from file with POKE_PC_BOOTSTRAP_CONFIG.

MCP Tools

• terminal_create_session

• terminal_list_sessions

• terminal_run_command

• terminal_get_command_status

• terminal_capture_output

• terminal_kill_session

• terminal_list_commands

• filesystem_read_file (blocks access under ~/.config)

Project docs

• CONTRIBUTING.md

• CODE_OF_CONDUCT.md

• SECURITY.md

• CHANGELOG.md

• RELEASE_CHECKLIST.md

Local Development

npm install
npm run dev

Build

npm run build
npm start

Runtime behavior

Startup order:

1. Validate config and initialize state directories.

2. Initialize tmux manager and restore known sessions.

3. Run bootstrap commands.

4. Initialize command notification channel (load persisted or auto-register).

5. Start MCP server.

6. Start Poke tunnel with reconnection loop.

7. Start command monitor for adaptive heartbeat/completion notifications.

Observability and command history

• Runtime app logs are emitted via pino to container stdout/stderr.

• Command/bootstrap lifecycle events are persisted in append-only NDJSON:

  • /root/poke-pc/terminal/history.ndjson

• This history file is intentionally logging-only and not exposed as an MCP tool.

Example:

docker exec -it poke-pc tail -f /root/poke-pc/terminal/history.ndjson

CI/CD and release

• CI workflow: .github/workflows/ci.yml

• GHCR publish workflow: .github/workflows/docker-publish.yml

• GitHub release workflow: .github/workflows/release.yml

Published image path:

• ghcr.io/calganaygun/poke-pc

Security notes

• Container currently runs as root by design for bootstrap flexibility.

• filesystem_read_file resolves real paths and blocks ~/.config access to protect credentials.

• Persisted webhook token is stored in state path with mode 0600.

• Logs redact common secret fields.

Acknowledgements and Credits

• Inspired by the need for a more robust and persistent Poke work environment.

• Built with Node.js, Docker, and the Poke SDK.

• Poke by The Interaction Company of California

• Official Poke SDK