macOS App

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

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