{"id":50440800,"url":"https://github.com/samsolomon/protopen","last_synced_at":"2026-05-31T19:01:51.352Z","repository":{"id":357888078,"uuid":"1238780600","full_name":"samsolomon/protopen","owner":"samsolomon","description":"A self-hostable playpen for static prototypes. Built for product teams using CLI and agent workflows.","archived":false,"fork":false,"pushed_at":"2026-05-14T17:45:49.000Z","size":12262,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-14T18:46:21.595Z","etag":null,"topics":["agpl","go","prototype","react","self-hostable","static-site-hosting"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samsolomon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-14T12:54:46.000Z","updated_at":"2026-05-14T17:46:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/samsolomon/protopen","commit_stats":null,"previous_names":["samsolomon/protopen"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/samsolomon/protopen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samsolomon%2Fprotopen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samsolomon%2Fprotopen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samsolomon%2Fprotopen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samsolomon%2Fprotopen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samsolomon","download_url":"https://codeload.github.com/samsolomon/protopen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samsolomon%2Fprotopen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33744447,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agpl","go","prototype","react","self-hostable","static-site-hosting"],"created_at":"2026-05-31T19:01:50.568Z","updated_at":"2026-05-31T19:01:51.342Z","avatar_url":"https://github.com/samsolomon.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Protopen\n\nA self-hostable playpen for static prototypes. Deploy a folder, get a live URL, and gather feedback through comments. Make it public to test designs with customers, or keep it private for you and your team. Protopen is built for product teams working with agents.\n\n**License:** [AGPL-3.0](LICENSE) \u0026middot; **Self-hosting:** [docs/self-hosting.md](docs/self-hosting.md) \u0026middot; **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## Why\n\nCoding agents—Claude Code, Codex, Cursor—can rapidly turn out static sites and prototypes. Protopen gives you a way to share them and gather feedback. It's the final step: deploy your prototype and get a live URL in seconds, then manage what you've shipped from the web dashboard.\n\n## CLI\n\n```bash\ncd cli \u0026\u0026 make build                        # build the binary\n./protopen login                            # browser-based device-code flow (default)\n./protopen login --token ptk_...            # or paste a token from Settings \u003e API Tokens\n./protopen deploy ./my-site                 # → live URL on stdout\n./protopen deploy ./dist --json             # → structured JSON\n./protopen list                             # your sites\n./protopen deploys \u003csite-name\u003e              # deploy history for a site\n./protopen rollback \u003csite-name\u003e \u003cdeploy-id\u003e # revert\n./protopen visibility \u003cname\u003e public|private\n./protopen comments \u003cname\u003e                  # comments left on a site\n./protopen version                          # print CLI version\n./protopen help                             # full command list\n```\n\nOutput is intentionally minimal so commands compose cleanly into pipelines: the live URL on stdout, git/branch metadata on stderr. Every data command — `deploy`, `list`, `deploys`, `rollback`, `visibility`, `comments`, `token` — takes `--json` for machine-readable output.\n\nConfig lives at `~/.protopen/config.json`. Resolution order: `--flag` \u003e `PROTOPEN_TOKEN` / `PROTOPEN_URL` / `PROTOPEN_ORG` env \u003e config file \u003e defaults.\n\n## MCP server\n\nFor agents that speak the [Model Context Protocol](https://modelcontextprotocol.io) (Claude Desktop, MCP-aware editors), `protopen mcp` runs an MCP server over stdio. It's the same actions as the CLI, exposed as MCP tools, sharing `~/.protopen/config.json` — so `protopen login` is the only setup step for either surface.\n\n| Action         | CLI                                  | MCP tool        |\n| -------------- | ------------------------------------ | --------------- |\n| Deploy         | `protopen deploy \u003cpath\u003e`             | `deploy`        |\n| List sites     | `protopen list`                      | `list_sites`    |\n| List deploys   | `protopen deploys \u003cname\u003e`            | `list_deploys`  |\n| Rollback       | `protopen rollback \u003cname\u003e \u003cid\u003e`      | `rollback`      |\n| Read comments  | `protopen comments \u003cname\u003e`           | `list_comments` |\n| Set visibility | `protopen visibility \u003cname\u003e \u003cvis\u003e`   | `set_visibility` |\n\nExample Claude Desktop config (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"protopen\": {\n      \"command\": \"/usr/local/bin/protopen\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nThe `deploy` tool requires absolute paths because stdio MCP has no shared working directory with the agent.\n\n## Use with agents\n\nAny agent that can run a shell command can deploy via the CLI — Claude Code, Cursor, Codex, in-house scripts, post-commit hooks.\n\nExample agent instruction:\n\n\u003e When the user asks to share, preview, or publish what we just built, run `protopen deploy \u003cpath\u003e` and return the URL it prints.\n\nOr a one-shot bash snippet you can hand off:\n\n```bash\nURL=$(protopen deploy ./dist --json | jq -r .liveUrl)\necho \"Preview at: $URL\"\n```\n\nFor agents that speak MCP natively, point them at `protopen mcp` (above). For everything else, the HTTP API is documented at [docs/api-reference.md](docs/api-reference.md).\n\n## Quickstart (local dev)\n\n```bash\ngit clone https://github.com/samsolomon/protopen.git\ncd protopen\ncp .env.example .env\ndocker compose up -d postgres\nnpm install\n(cd api \u0026\u0026 go run .) \u0026\nnpm run dev:web\n```\n\nDashboard at \u003chttp://localhost:5173\u003e, API at \u003chttp://localhost:8080\u003e, deployed sites served from \u003chttp://127.0.0.1:8081\u003e. The Postgres container binds to host port `5433` (not the usual 5432) so it coexists with a Homebrew or Postgres.app server already running locally; the API reads `.env` from the repo root automatically, so no `source .env` is needed.\n\nA demo account, three teammates, and five example sites are seeded on first boot (toggled by `SEED_DEMO` in `.env.example`, defaulted on):\n\n- email: `demo@protopen.dev`\n- password: `protopen-demo`\n\nSign in, then visit the dashboard to see the seeded sites. Thumbnails are captured by the runtime backstop once `THUMBNAILS_ENABLED=1` (also defaulted on) and a Chromium binary is available — on macOS the standard Google Chrome install is auto-detected, on Linux any `chromium-browser` / `google-chrome` on `PATH` works, otherwise set `CHROMIUM_PATH`.\n\n## What's in this repo\n\n- `cli/` — Go CLI, the primary interface\n- `api/` — Go API: auth, uploads, deploys, content serving\n- `web/` — React dashboard for managing deployed sites\n\n## Capabilities\n\n- Single-command deploy from a folder or zip\n- Stable site URLs across redeploys; versioned URLs for any previous deploy\n- Rollback to any previous deploy in one command\n- Public / private sites (private requires sign-in)\n- Local-filesystem storage for dev, Cloudflare R2 for production\n- Password auth with optional email verification; email via Resend or SMTP\n- Figma-style comments on live sites — pinned threads, `@mentions`, resolve\n- In-app and email notifications with per-user preferences; reply to a\n  comment straight from your inbox\n\n## Tests\n\nSee [CONTRIBUTING.md#running-tests](CONTRIBUTING.md#running-tests).\n\n## Production / self-hosting\n\nSee [docs/self-hosting.md](docs/self-hosting.md) — Cloudflare R2, DNS setup, email (Resend or SMTP), and deploy targets (Fly, Railway, bare VM, Docker).\n\n## License\n\n[AGPL-3.0-only](LICENSE). Network-use disclosure: if you run a modified copy of protopen as a hosted service, you must offer the modified source to your users.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamsolomon%2Fprotopen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamsolomon%2Fprotopen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamsolomon%2Fprotopen/lists"}