Management Dashboard

Placet’s Agent Management Dashboard is an optional UI that lets a user inspect and control a connected agent runtime (sessions, audit logs, token usage, credentials, cron, MCP bridges, workspace, skills, scripts, channels, commands, agent card, A2A peers) directly from Placet — without ever exposing the agent’s bearer token to the browser. The protocol Placet speaks upstream is a bearer-authenticated management API rooted at /api/v1/*. Any agent runtime that implements the same surface — or a compatible subset — can be connected; the routes documented below describe the wire contract Placet expects upstream. The dashboard is off by default per user. It becomes visible once a user enables it under Settings → Preferences → Management Dashboard. Placet auto-enables this preference the first time a user registers an agent that provides management credentials. Placet owns a dedicated, typed endpoint for every upstream management route — it is not a generic wildcard proxy. Controllers are explicit to give the backend room for caching, cross-agent aggregation, and request shaping. When the upstream is unreachable Placet returns 502 Bad Gateway and the frontend silently hides the view.

Registering Management Credentials

An agent registers management credentials the same way it registers a channel — by calling POST /api/v1/agents/setWebhook on the Placet backend with the additional management object, or by using the dedicated setManagement endpoint.

Option A — Combined with `setWebhook`

POST /api/v1/agents/setWebhook
x-api-key: <placet-agent-key>
Content-Type: application/json

{
  "channelId": "my-agent-id",
  "webhookUrl": "https://agent.example.com/placet/webhook",
  "management": {
    "url": "https://agent.example.com",
    "apiKey": "management-bearer-token"
  },
  "isSubagent": false,
  "parentChannelId": null
}

Field	Type	Description
`management.url`	`string` (URL)	Base URL of the agent runtime (`/api/v1` is appended automatically).
`management.apiKey`	`string`	Management bearer token. Stored encrypted, returned as `***` to the UI.
`isSubagent`	`boolean`	`true` marks this channel as a HITL sub-channel that should be hidden from the agent list.
`parentChannelId`	`string \| null`	When `isSubagent` is `true`, the `channelId` of the parent agent owning this HITL channel.

Option B — Dedicated endpoint

POST /api/v1/agents/setManagement
x-api-key: <placet-agent-key>
Content-Type: application/json

{
  "channelId": "my-agent-id",
  "url": "https://agent.example.com",
  "apiKey": "management-bearer-token"
}

Pass "url": null, "apiKey": null to clear the management credentials for a channel.

Endpoints

Every endpoint listed below lives under /api/agents/:agentId/manage/ on the Placet backend and maps 1:1 to the upstream /api/v1/ route. All requests require a valid Placet user JWT (Authorization: Bearer <jwt>) and are scoped to the authenticated user’s agent.

Health

Method	Placet path	Upstream route	Description
GET	`/health`	`/health`	Management liveness check

Sessions

Method	Placet path	Upstream route	Description
GET	`/sessions`	`/sessions`	List sessions (metadata only)
GET	`/sessions/{key}`	`/sessions/{key}`	Full history for a session key
DELETE	`/sessions/{key}`	`/sessions/{key}`	Remove a session (cache + file)

Audit log

Method	Placet path	Upstream route	Description
GET	`/audit`	`/audit`	Filtered event list
GET	`/audit/tail`	`/audit/tail`	Last N events from today
GET	`/audit/stats`	`/audit/stats`	Aggregated event counts
GET	`/audit/runs/{runId}`	`/audit/runs/{runId}`	All events for a single run

Token usage

Method	Placet path	Upstream route	Description
GET	`/usage`	`/usage`	Aggregated totals + grouped items
GET	`/usage/runs/{runId}`	`/usage/runs/{runId}`	Single-turn token-usage row

Settings

Runtime settings exposed by the agent. Browser settings include the new browser tool controls shown in the Management Dashboard: enable, max_named_sessions, domain_allowlist, and domain_denylist.

Method	Placet path	Upstream route	Description
GET	`/settings`	`/settings`	Read editable runtime settings and option lists
PATCH	`/settings`	`/settings`	Apply partial settings updates and restart hints

Credentials

Generic secrets stored on the agent and made available to skills/tools as ${credentials.KEY}. The exposed flag mirrors config.tools.exec.exposed_credentials — when true the key is injected as an env var into the shell-exec sandbox.

Method	Placet path	Upstream route	Description
GET	`/credentials`	`/credentials`	List keys (values masked) + `exposed` flags
POST	`/credentials`	`/credentials`	Create a secret (`{key, value, exposed?}`); `409` when key exists
GET	`/credentials/{key}`	`/credentials/{key}`	Existence check
PUT	`/credentials/{key}`	`/credentials/{key}`	Upsert (`{"value": "..."}`)
PUT	`/credentials/{key}/exposed`	`/credentials/{key}/exposed`	Toggle exec-sandbox exposure (`{"exposed": bool}`)
DELETE	`/credentials/{key}`	`/credentials/{key}`	Remove

LLM provider credentials

Provider API keys live under config.providers.<name>.api_key. OAuth-only providers (github_copilot, openai_codex) report isOauth: true and use a token store instead of api_key; for those, POST / PUT return 400 and the OAuth endpoints below must be used.

Method	Placet path	Upstream route	Description
GET	`/credentials/providers`	`/credentials/providers`	List providers + `hasValue` / `isOauth` state
POST	`/credentials/providers`	`/credentials/providers`	Set `api_key` (create-only — `409` when already set)
PUT	`/credentials/providers/{name}`	`/credentials/providers/{name}`	Upsert `api_key` (`{"value": "..."}`)
DELETE	`/credentials/providers/{name}`	`/credentials/providers/{name}`	Clear `api_key`, or disconnect OAuth for OAuth providers
POST	`/credentials/providers/{name}/oauth/start`	`/credentials/providers/{name}/oauth/start`	Begin OAuth device flow (`github_copilot` only — see below)
GET	`/credentials/providers/{name}/oauth/poll`	`/credentials/providers/{name}/oauth/poll`	Poll an in-progress OAuth flow (`?session_id=...`)

POST /oauth/start returns:

{
  "sessionId": "…",
  "mode": "device",
  "userCode": "ABCD-1234",
  "verificationUri": "https://github.com/login/device",
  "expiresIn": 900,
  "interval": 5
}

The agent polls the provider in the background; the client polls GET /oauth/poll?session_id=… every interval seconds and receives {status: "pending" | "ok" | "error", error?, account?}. On ok the OAuth token is persisted server-side (no value ever crosses the wire). openai_codex is intentionally not supported via REST — its OAuth client mandates a fixed http://localhost:1455/auth/callback redirect, so use your agent’s local CLI to complete the OAuth login.

Cron

Method	Placet path	Upstream route	Description
GET	`/cron`	`/cron`	List jobs
POST	`/cron`	`/cron`	Create
GET	`/cron/{id}`	`/cron/{id}`	Get single job
PATCH	`/cron/{id}`	`/cron/{id}`	Partial update
DELETE	`/cron/{id}`	`/cron/{id}`	Remove
POST	`/cron/{id}/run-now`	`/cron/{id}/run-now`	Trigger immediately
POST	`/cron/{id}/pause`	`/cron/{id}/pause`	Disable
POST	`/cron/{id}/resume`	`/cron/{id}/resume`	Enable

MCP servers

Method	Placet path	Upstream route	Description
GET	`/mcp`	`/mcp`	List servers
POST	`/mcp`	`/mcp`	Add a server
GET	`/mcp/{name}`	`/mcp/{name}`	Get single server
PATCH	`/mcp/{name}`	`/mcp/{name}`	Edit config
DELETE	`/mcp/{name}`	`/mcp/{name}`	Remove
POST	`/mcp/{name}/enable`	`/mcp/{name}/enable`	Enable + connect
POST	`/mcp/{name}/disable`	`/mcp/{name}/disable`	Disable + disconnect
POST	`/mcp/{name}/restart`	`/mcp/{name}/restart`	Reconnect

Tool policy

Persistent allow/deny rules for tool calls plus runtime toggles for the approval gate. deny wins over allow; missing rules trigger a one-time approval prompt unless the gate is disabled or skipped for cron callers.

Method	Placet path	Upstream route	Description
GET	`/policy`	`/policy`	List rules + current `enabled` / `skipCron` flags and on-disk policy file path
POST	`/policy`	`/policy`	Add a rule (`{action: 'allow' \| 'deny', tool, params?}`)
DELETE	`/policy`	`/policy`	Remove a single rule (same body shape as `POST`)
DELETE	`/policy/all`	`/policy/all`	Clear all rules
PATCH	`/policy/settings`	`/policy/settings`	Update runtime flags (`{enabled?: boolean, skipCron?: boolean}`)

The enabled flag is the master switch for the approval gate — when off, every tool call runs without prompts and the rule list is ignored. skipCron lets cron-triggered tool calls bypass the approval prompt while keeping the gate active for interactive callers.

Workspace

Method	Placet path	Upstream route	Description
GET	`/workspace/tree`	`/workspace/tree`	Directory listing (`?path=&depth=`)
GET	`/workspace/file`	`/workspace/file`	Read file contents (`?path=`)
PUT	`/workspace/file`	`/workspace/file`	Write file contents (`?path=`)
DELETE	`/workspace/file`	`/workspace/file`	Delete file (`?path=`)

Skills & scripts

Method	Placet path	Upstream route	Description
GET	`/skills`	`/skills`	List workspace `skills/*.md`
GET	`/scripts`	`/scripts`	List workspace `scripts/*`

Channels

Method	Placet path	Upstream route	Description
GET	`/channels`	`/channels`	List channel configs
GET	`/channels/{name}`	`/channels/{name}`	Get channel config
PUT	`/channels/{name}`	`/channels/{name}`	Upsert channel config (restart required)
DELETE	`/channels/{name}`	`/channels/{name}`	Remove channel config (restart required)

Commands

Method	Placet path	Upstream route	Description
POST	`/commands/stop`	`/commands/stop`	Execute `/stop`
POST	`/commands/restart`	`/commands/restart`	Execute `/restart`
POST	`/commands/new`	`/commands/new`	Execute `/new`
POST	`/commands/reflect`	`/commands/reflect`	Execute `/reflect`
GET	`/commands/status`	`/commands/status`	Execute `/status`

Agent Card

Method	Placet path	Upstream route	Description
GET	`/agent-card`	`/agent-card`	Live A2A AgentCard JSON

A2A peers

Method	Placet path	Upstream route	Description
GET	`/a2a/peers`	`/a2a/peers`	List registered peers
POST	`/a2a/peers`	`/a2a/peers`	Register / overwrite a peer
DELETE	`/a2a/peers/{alias}`	`/a2a/peers/{alias}`	Remove a peer
GET	`/a2a/peers/{alias}/card`	`/a2a/peers/{alias}/card`	Fetch the peer Agent Card
POST	`/a2a/peers/{alias}/call`	`/a2a/peers/{alias}/call`	Send a message through the peer

Error semantics

Status	Meaning
`401`	Missing/invalid Placet JWT.
`404`	Agent has no management credentials configured.
`502`	Upstream timed out (15 s) or is unreachable. The frontend hides the dashboard silently.
other	Upstream errors are normalized to `{ error: { code: 'upstream_<status>', message }, upstreamStatus }` and re-emitted at the same HTTP status.

Minimal Upstream Requirements

To support the management dashboard, your agent runtime must:

Expose a bearer-authenticated management API on /api/v1/* that matches the wire contract documented above.
Implement any subset of the routes above that you want users to see; unsupported ones simply return 404, which the dashboard handles gracefully.
Accept a long-lived management bearer token that you can transmit to Placet via setWebhook/setManagement.

If a domain (e.g. cron, mcp) isn’t supported by your runtime, the Placet UI tab for that feature stays empty — there is nothing else you need to do to “opt out”.

Security Notes

Management keys are stored alongside webhook secrets and returned as *** on every agent read.
Only the agent owner (owner of the apiKey that registered the channel) can call /manage/* for that agent.
Rotate a key by calling setManagement again; to revoke, set both fields to null.

Getting Started

Core Concepts

Connections

Examples

Plugins

Management Dashboard

Registering Management Credentials

Option A — Combined with `setWebhook`

Option B — Dedicated endpoint

Endpoints

Health

Sessions

Audit log

Token usage

Settings

Credentials

LLM provider credentials

Cron

MCP servers

Tool policy

Workspace

Skills & scripts

Channels

Commands

Agent Card

A2A peers

Error semantics

Minimal Upstream Requirements

Security Notes

​Registering Management Credentials

​Option A — Combined with setWebhook

​Option B — Dedicated endpoint

​Endpoints

​Health

​Sessions

​Audit log

​Token usage

​Settings

​Credentials

​LLM provider credentials

​Cron

​MCP servers

​Tool policy

​Workspace

​Skills & scripts

​Channels

​Commands

​Agent Card

​A2A peers

​Error semantics

​Minimal Upstream Requirements

​Security Notes

Registering Management Credentials

Option A — Combined with `setWebhook`

Option B — Dedicated endpoint

Endpoints

Health

Sessions

Audit log

Token usage

Settings

Credentials

LLM provider credentials

Cron

MCP servers

Tool policy

Workspace

Skills & scripts

Channels

Commands

Agent Card

A2A peers

Error semantics

Minimal Upstream Requirements

Security Notes