# Poke Pc

> safely extend poke's capabilities to your machine with an isolated docker environment. poke pc is a secure mcp worker that lets your ai agent run terminal commands and manage sessions within a sandboxed container

- **Type:** MCP server
- **Install:** `agentstack add mcp-calganaygun-poke-pc`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [calganaygun](https://agentstack.voostack.com/s/calganaygun)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [calganaygun](https://github.com/calganaygun)
- **Source:** https://github.com/calganaygun/poke-pc

## Install

```sh
agentstack add mcp-calganaygun-poke-pc
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Poke PC
  
  
    safely extend poke's capabilities to your machine with an isolated docker environment
  

  
    Let your Poke AI assistant to work on a isolated fully containerized environment.
    A community project — not affiliated with Poke or The Interaction Company.
  
  
  
    
    
    
    
  

## macOS App

The macOS app is downloadable from [GitHub Releases](https://github.com/calganaygun/poke-pc/releases).
You can download latest DMG file from [here](https://github.com/calganaygun/poke-pc/releases/latest/download/Poke-PC.dmg)

  

## CLI
```bash
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:

```bash
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

```bash
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:

```bash
-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

```bash
npm install
npm run dev
```

## Build

```bash
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:

```bash
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](https://poke.com) by [The Interaction Company of California](https://interaction.co)
- [Official Poke SDK](https://www.npmjs.com/package/poke)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [calganaygun](https://github.com/calganaygun)
- **Source:** [calganaygun/poke-pc](https://github.com/calganaygun/poke-pc)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-calganaygun-poke-pc
- Seller: https://agentstack.voostack.com/s/calganaygun
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.