Ploinky Interfaces
The authenticated Router surfaces that connect browsers, agents, and workspace operators to private runtimes.
Router boundary
The Router is the single HTTP, server-sent event, WebSocket, and MCP edge for a Ploinky Box. It selects an exact listener, Host, route, caller, and active generation before opening an upstream connection.
flowchart TD
C[Browser or agent] --> R[Router]
R --> P[Authentication and route policy]
P --> G[Active generation check]
G --> A[Private agent runtime]Port 8080 is the Router's inner public surface. Port 8081 is private to the Box and is never outer-published. Unknown or stale host and path combinations fail before the Router reveals or contacts an upstream target.
Browser APIs
Browser-facing routes use the Router login session. The table names the stable route families and their observable purpose.
| API route | Purpose and access boundary |
|---|---|
/webchat/* | Hosts the TTY-backed chat page, EventSource stream, interactions, and workspace-scoped upload flow for an authenticated session. |
/workspace-files/* | Reads an approved workspace file for preview after path validation and route authorization. |
/status/* | Returns a read-only status snapshot or NDJSON metric stream to a local administrator. |
/auth/* | Runs local or configured SSO login, logout, session, and invitation flows. |
Browser mutations require the established session protections, including Origin and CSRF checks where applicable. Browser clients never connect directly to an agent container or receive its reusable credentials.
MCP APIs
The Model Context Protocol surfaces expose configured tools and resources through the Router. The Router applies caller policy and mints a request-bound token before the target AgentServer executes a tool or resource command.
| API route | Purpose and access boundary |
|---|---|
/mcp | Aggregates discovery and calls across active agents for Router-authenticated users. Shared tool names must identify their source agent. |
/<agent>/mcp | Proxies JSON-RPC to one admitted agent after user authentication or an authenticated Agent Assertion. |
/<agent>/task | Returns protected status for an asynchronous agent task. |
/<agent>/task/cancel | Cancels an admitted task through a token bound to that task operation. |
Tool policy is fail-closed. It distinguishes authenticated, administrator, and internal tools; resource reads require a Router-authenticated user or guest session. Tokens are bound to the selected target, operation, method, path, arguments, generation, and replay state.
Management APIs
| API route | Purpose and access boundary |
|---|---|
GET /api/marketplace | Lists the caller's marketplace view, installed repositories, discovered agents, enabled records, and runtime state. |
POST /api/marketplace | Handles admitted repository and agent lifecycle actions. Browser mutations require a local administrator. |
/policy/command | Runs the Router-owned policy command surface for an authorized administrator or explicitly admitted agent request. |
/agent-card | Aggregates metadata from active agents without requiring a fixed card schema. |
An active agent can use only the narrow management paths explicitly admitted for an assertion. It does not inherit browser administrator authority or gain access to repository installation and removal merely because it is reachable through the Router.