platform

# ProAgentStore Platform

Marketplace for server-powered AI agents. Creators build agent templates, clients subscribe and run them on their own data.

**Store:** https://proagentstore.online
**API:** https://api.proagentstore.online
**MCP:** https://mcp.proagentstore.online/mcp
**Console:** https://proagentstore.online/console/
**GitHub:** https://github.com/ProAgentStore
**Free pair:** https://freeagentstore.online

## What's in here

```
platform/
├── packages/sdk/     Internal TypeScript SDK for agents
├── packages/cli/     @proagentstore/cli — init, check, publish, MCP proxy, local runtime
├── packages/browser-runner/ ProAgentStore Playwright + terminal/coding runtime bundled into the CLI
├── workers/api/      Hono API worker (auth, agents, instances, coding, apply, keys, analytics)
├── workers/host/     Marketing site + console + widget
├── workers/mcp/      MCP server for Codex, Claude Code, Cursor, and VS Code
├── store/            Source HTML for all pages
├── skills/           Open Agent Skills source files
├── plugins/          Codex and Claude plugin wrappers
├── agents/           Tier-0 first-party agent sources kept in this repo
└── templates/        Agent scaffolding (worker, cron, api)
```

## Agent types

| Type | Template | What it does |
|---|---|---|
| **Agent** | `worker` | Full AI: conversation, memory, knowledge base, core tools, Workers AI |
| **Worker** | `cron` | Scheduled tasks: daily digests, monitoring, batch processing |
| **Tool** | `api` | Stateless endpoint: transform, generate, analyze |

## Quick start

### Use an agent
```bash
# Try any published agent — no sign-up needed
curl -X POST https://api.proagentstore.online/v1/public/agents/chatbot/try \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello!"}'
```

### Build an agent
```bash
npx @proagentstore/cli init my-agent --template worker
cd my-agent
pnpm install && pnpm dev
npx @proagentstore/cli publish
```

### SDK
```typescript
import { initPro } from '@proagentstore/sdk'

const agent = initPro({ agentId: 'your-id', token: 'your-token' })
const { response } = await agent.chat('Hello!')
```

### Embed widget
```html
<script src="https://proagentstore.online/widget.js"
  data-agent="chatbot" data-theme="dark"></script>
```

### MCP
```bash
codex mcp add proagentstore --url https://mcp.proagentstore.online/mcp
codex mcp list
# If the server shows "Not logged in":
codex mcp login proagentstore

claude mcp add --transport http proagentstore https://mcp.proagentstore.online/mcp
claude mcp list

npx mcp-remote https://mcp.proagentstore.online/mcp
npx @proagentstore/cli mcp
```

MCP has two runtime modes:

- `chat_with_agent` calls the public trial endpoint. Use it for discovery and smoke tests.
- `subscribe_agent` creates your private instance, then `chat_with_instance` runs that instance with your own state, knowledge, and caller-provided AI credentials.

Typical user run:

```text
list_agents -> subscribe_agent -> my_instances -> add_instance_knowledge -> chat_with_instance
```

The expected response when user-owned AI credentials are missing is:

```text
Add your Cloudflare Workers AI account ID and API token before running this agent.
```

That means the instance runtime path is working and correctly refusing to bill the platform AI account. See [MCP Instance Runtime](docs/mcp-instance-runtime.md) for the full tool map, live test record, and OAuth troubleshooting.

The full MCP-first developer surface is documented at:

- https://proagentstore.online/docs/mcp/
- [MCP](platform-docs/mcp.md)
- [server.json](server.json)
- [.mcp.json](.mcp.json)
- [AGENTS.md](AGENTS.md)

MCP safety is enforced server-side. OAuth supports `read`, `write`, `runtime`, and `destructive` scopes; `MCP_READ_ONLY=1` forces read-only mode; mutating tools support `dry_run` where useful; overwrite/destructive tools require exact `confirm` values; and `mcp_audit_log` exposes recent MCP write, runtime, dry-run, denied, and destructive events.

## Architecture

The current system map, runtime boundaries, data ownership rules, risk assessment, and refactor roadmap live in [Architecture](docs/architecture.md).

### Browser runtime (`pags up`)

Browser- and coding-capable agents use PAGS as the control-plane brain and a local **ProAgentStore browser runtime** (`runtimePlane: "pags"`, Playwright + terminal/coding capabilities, bundled into the CLI) as the hands. One public package, one command — no monorepo and no tunnel binary.

```text
PAGS control plane / MCP / Workflows
  -> task, auth, approval, audit, the LLM brain
ProAgentStore browser runtime (pags up)
  -> Playwright, local files, real browser profile, terminal/coding engines
Real browser / real repo
  -> job boards, uploads, receipts, coding sessions
```

```bash
npm i -g @proagentstore/cli
pags login
pags up            # one runner for every active runtime-capable instance
```

**Install once per machine, ever.** Since CLI 0.4.63 the `pags` that npm installs is a small bootstrap stub (#862): every `pags up` asks npm for the latest `@proagentstore/cli`, fetches a newer release into `~/.config/proagentstore/cli/<version>/` and runs it — so a machine never needs `npm i -g` again, however far behind it falls or whether it has ever heard of `runner_update`. `runner_update` (#859) updates the same cache remotely while `pags up` keeps running. A machine on 0.4.62 or older gets the stub from one last `npm i -g @proagentstore/cli` (or, on 0.4.62, from `runner_update`). `PAGS_NO_SELF_UPDATE=1` turns the check off; a source checkout is never self-updated.

**Remote updates restart everything, not just the runner (#860).** After `runner_update` installs a release, `pags up` restarts itself — supervisor included — with the same flags, and every agent re-attaches (an older `pags up` restarts only the runner, and `runner_update`'s answer says so in `supervisor`). A runner started without `pags up` can be updated remotely too, once something will start it again:

- **launchd / systemd** — run `pags runner connect <any-instance-id> --watch-instances` with `PAGS_SERVICE=1` and restart-on-failure (launchd `KeepAlive` → `SuccessfulExit: false`; systemd `Restart=on-failure`). The runner exits with code 75 after an update, and the service manager starts it on the new release. It signs in with the saved `pags login` session.
- **anything else** (a tmux script, `nohup`) — set `PAGS_RESTART_COMMAND` to the shell command that starts it; the runner runs it, detached, as it exits.

With neither, `runner_update` refuses rather than stop a runner nothing would bring back. Either way a coding engine mid-turn is waited for first.

`pags up` is the canonical runner: **one process serves every active instance whose `capabilities.runtime` is non-null**. Cloud-only chat/RAG/connector agents (`runtime: null`) are skipped — they never need a local runner.

Membership is **live**, not a startup snapshot. `pags up` passes `--watch-instances` (CLI ≥ 0.4.30), so the runner re-reads `/v1/instances/my/instances` every 20s and attaches newly eligible agents — and detaches ones that stopped being eligible — without a restart. Subscribing to a coding agent while the runner is up just works. (Polling, not push: a brand-new instance has no socket to push over; #83 tracks the push path.) A scoped `pags up --instance <id>` deliberately does *not* watch — it means that one agent and nothing else.

Transport is a **WebSocket relay**: the runner connects outbound to a per-(instance, node) `RelayDO` — no cloudflared, no public server, no inbound port. Cloud -> `callRunner()` -> `RelayDO` -> WebSocket -> runner. There is no `--tunnel` flag or tunnel fallback in the current CLI. The runner mints a short-lived, instance-scoped relay token for the handshake; the 30-day account JWT is never put in the WebSocket URL.

- Coder can run multiple machines against the same instance at once. Each coding session is pinned to the runner node that owns it; different repos can run on different machines concurrently.
- `pags up --force` — replace the current relay socket when debugging stale local connections
- `pags up --instance <id>` — pin to one agent (debug)
- `pags up --headless` — headless mode

The former `JOB_APPLY` job-application workflow is retired for new starts. Its endpoint, chat tool, and MCP tool return a migration response without creating work; existing tasks and history remain readable. New applications use the Scout → Tailor → Runner pipeline below. The **Coder** agent runs its chosen engine (Claude Code, Codex, Gemini CLI, Grok, or a local command) on the session's assigned runner node; Claude uses a persistent structured session, while other engines run one-shot turns.

### Legacy job application agent (retired for new starts)

The prior Cloudflare `JobApplyWorkflow` brain and browser-runner task are retained only so existing runs, board cards, traces, résumé metadata, and ATS history can still be read. No endpoint creates another one. For new work, use the owner-controlled Scout → Tailor → Runner pipeline: triage a lead, tailor materials, then ask for review or let the Application Runner fill under its configured submission policy.

### Skills and plugins

ProAgentStore publishes skills through platform-specific plugin marketplaces so users can find them from both Codex and Claude Code.

Codex:

```bash
codex plugin marketplace add ProAgentStore/platform
```

Claude Code:

```text
/plugin marketplace add ProAgentStore/platform
/plugin install proagentstore@proagentstore
/reload-plugins
```

See [Skill Publishing](platform-docs/skill-publishing.md) for the publishing layout, marketplace files, and dual Codex/Claude release checklist.

Public discovery pages:

- https://proagentstore.online/skills/
- https://proagentstore.online/skills/proagentstore-mcp-operator/
- https://proagentstore.online/llms.txt
- https://proagentstore.online/llms-full.txt
- https://proagentstore.online/skills.json

## Catalog agents

### Where the catalog actually