Using plori from an agent
If you were asked to set up plori, follow Connect below: add the plori MCP server to this
client, have the account owner sign in, and confirm the tools respond before you report
success.
Plori runs AI agents in cloud Workspaces. Several agents can work on one project at once, and
Plori merges their changes back into the Workspace. A Workspace holds a project's files under
/workspace, saved versions of those files, a main conversation and the run history.
Connect
If this client already lists Plori tools and list_workspaces answers, skip this section.
MCP: Streamable HTTP at https://api.plori.ai/mcp.
Claude Code: connect from this conversation
Read these instructions in the current conversation before starting authentication.
Installing a skill or plugin is optional. Use this flow only in interactive Claude Code
when its Plori MCP client exposes both authenticate and complete_authentication.
Other clients use their ordinary OAuth or API-key setup above.
If this Claude Code build does not expose both authenticate and
complete_authentication, use /mcp instead. Pick plori, choose Authenticate, then
sign in with the emailed code. If the browser cannot reach the localhost callback,
Claude Code prompts for it directly in its own dialog, never in chat. Then verify with
list_workspaces.
- Check the current MCP configuration and active tools. Reuse an existing Plori server
at
https://api.plori.ai/mcp; do not add duplicate entries or replace a different
server with the same name. If missing, configure it once with
claude mcp add --transport http plori https://api.plori.ai/mcp.
Confirm the server is available in this conversation before authenticating. Saving
configuration alone does not prove that it loaded. If its tools are missing, ask
the user to type /reload-plugins in this Claude Code conversation, then resume
these steps in the same session. This also refreshes MCP configuration when no
plugins are installed. It is a user command; do not try to invoke it through the
Skill tool. Confirm the authentication tools are available before proceeding. If they
are still missing, use /mcp instead (above).
- If Plori tools already work, the connection is complete. Otherwise, call the
client's Plori
authenticate tool using its exposed schema. Keep the returned
authorization URL intact. Do not construct a new OAuth request or change its state,
redirect URI, or PKCE challenge.
- POST JSON
{"authorization_url":"<the exact client URL>"} once to
https://api.plori.ai/oauth/pair. The response contains user_code,
verification_uri, verification_uri_complete, device_code,
expires_in (seconds), and interval (seconds). Keep device_code private.
If a permission rule, hook, or tool denies this request, stop and use the fallback below.
- Tell the user: "Open and enter . Sign in and approve
the connection; I will continue when you finish." The user can open the page on
their phone. Display the short address and code, not the authorization or callback
URL. Do not ask the user to copy a callback URL into chat.
- Poll
https://api.plori.ai/oauth/pair/poll with JSON
{"device_code":"<device_code>"}. Keep only one request in flight, allow each
request at least 30 seconds to finish, and wait at least interval seconds
between requests. The server can hold a pending request for 25 seconds.
Read pending and failure responses from the JSON error field, not status.
On error: "authorization_pending", continue. On error: "slow_down", use the
larger of your previous delay plus five seconds and the response's interval
for all subsequent requests. Honor Retry-After when present on HTTP 429.
On HTTP 503 with error: "temporarily_unavailable", preserve this pairing and
the pending client authentication. Wait at least the larger of your poll interval
and Retry-After (five seconds), then retry the same device code. A temporary
failure does not extend expires_in; retry only within the original four-minute
window while the client authentication remains pending.
If a permission rule, hook, or tool denies a poll request, stop and use the fallback below.
- On
status: "approved", pass the returned callback_url directly to the same client's
complete_authentication tool using its exposed schema. Do not navigate to the
loopback URL or exchange the code yourself: the client owns the PKCE verifier.
Then discover Plori tools and call list_workspaces to confirm the connection before
reporting success. This verification does not create a Workspace or start paid work.
Fallback when a pairing request is denied
Use this fallback after the first permission, hook, or tool denial of either pairing
POST. Do not make another request to /oauth/pair or /oauth/pair/poll, and do not
try curl, wget, WebFetch, Python, a shell script, or another generic network
tool.
- Show the user the exact authorization URL returned by the current
authenticate
call. Ask them to open it in their browser, sign in, and approve the connection.
Do not edit the URL.
- After approval, the authorization server redirects the browser to a localhost
callback. If that
redirect connects, let the client finish authentication. If the browser cannot
connect to localhost, ask the user to copy the final localhost callback URL from
the browser address bar and paste it into this conversation. It contains one-time
authorization data, so tell the user not to paste it anywhere else. Do not ask for
that URL before the redirect has failed.
- Pass a pasted callback URL only to the same client's
complete_authentication
tool. Do not open, fetch, rewrite, log, or exchange it yourself.
- Discover Plori tools and call
list_workspaces before reporting success. This check
does not create a Workspace or start paid work.
If the authorization URL or pending client authentication expires during this
fallback, discard it and call authenticate again. Use only the new authorization
URL. Never reuse an expired URL.
Stop on access_denied; do not retry a denied request automatically. On
expired_token, an already-consumed pairing, or a client authentication timeout,
start a fresh client authentication before creating another pairing. Never reuse the
old authorization URL. Pairing lasts four minutes to fit within the client's pending
login. If the approved response is lost, restart the whole flow; the callback is
returned only once. Keep approval polling active while the user signs in.
Remote Control can use this flow only when it controls that same interactive Claude
Code process and the two authentication tools are available. A separate hosted
Claude.ai connector or Agent SDK session needs its own supported authentication flow.
URLs can still appear in client tool results; do not promise to hide tool transcripts.
Switch accounts or sign out
To connect a different Plori account or sign out, use /mcp. Pick plori, choose Clear
authentication, then Authenticate again with the new account's email code.
claude mcp remove does not clear the stored token.
CLI and REST
CLI: curl -fsSL https://plori.ai/install.sh | sh (Windows: irm https://plori.ai/install.ps1 | iex),
npm i -g @plori/cli, or npx -y @plori/cli. The shell installer writes to
~/.local/bin and edits no rc file, so run export PATH="$HOME/.local/bin:$PATH" first.
plori login signs in through the browser; headless callers use
plori login --key plori_sk_... or set PLORI_API_KEY. Piped output and --json give
JSON.
REST: https://api.plori.ai/v1 with the same bearer token. Detail: https://plori.ai/auth.md
Tools
The MCP server has 24 tools. Invitees use their own login, API keys and OAuth
sessions. Workspace calls resolve access to the owning account from the resource.
Workspaces
list_workspaces lists your own and shared Workspaces with account
(user_id, email) and your role (owner, member or viewer).
Pass workspace_id for one. storage_readiness is present while its storage starts.
create_workspace (name, idempotency_key) returns id and default_agent_id,
the Workspace's agent. Without default_manager_agent_id it creates that agent, which
counts against the agent limit. Optional account selects a shared account by user id.
Omit it for your own account. Members can create there. Viewers cannot. The result
includes account and role. Names are not unique: reuse a Workspace.
delete_workspace permanently deletes its files, saved versions, copies and
conversations.
get_credits returns the balance. Check it before long work.
Send a task
send_workspace_message (workspace_id, message) runs a task in the Workspace's main
conversation, or in the one named by session_id. Use it for most work, including work
that can be split: the Workspace's own agent splits it between several agents, merges their
changes and fixes conflicts.
- For a new or continued run, the call holds until the run ends, pauses for input,
or the hold ends. The server picks a hold that fits your client. Use that default.
- If the result is
running, call get_run_result (workspace_id, run_id) after
poll_after_seconds. Repeat until the run completes or is awaiting_input.
get_run_result, cancel_run, list_runs, list_pending_inputs and
schedule_run take the workspace_id.
- Reuse
session_id to keep context. An idle conversation starts a run. While running,
plain text returns status: "steering" or "queued" with steer_id.
- If the paused run has exactly one ordinary question assigned to you, your message
answers it. Otherwise it queues, and
pending_inputs names the request and assignee.
A message never cancels a pending request. If the result has status: "answered"
and continuation_pending: true, read the paused run until it reports
continuation_run_id. Do not submit the answer again.
- A queued or steering receipt returns immediately, regardless of
wait. It includes
run_id, session_id, agent_id, workspace_id, url and poll_after_seconds.
Its run_id is the running or paused run, not a result for this message. Use
list_runs to find a later queued turn. No lookup connects steer_id to that run.
- 409
conversation_busy still applies to attachments or run options in a busy
conversation, and to working-copy conflicts. Send attachments and options when idle.
- A retry with the same
idempotency_key returns the original run or message receipt for 24 hours.
max_turn_tokens sets an optional token ceiling for the turn. cancel_run stops a run.
Files
- Only files under
/workspace persist between runs. Software installed elsewhere and
processes a run starts do not. Use TMPDIR for temporary files.
- A completed run does not prove its files are saved: wait for
file_source.state
ready with no save_failure.
- A completed run's
files are signed URLs that need no other credential.
They expire about 10 minutes after the result. Call get_run_result again for fresh links.
read_workspace_file reads a saved version: current_revision, an agent's
saved_revision_id, or a changeset's base_revision, incoming_revision or
result_revision. A path such as /workspace/a.md is not a URL.
upload_workspace_file writes a file into the Workspace's current files. Pass text up
to 262144 bytes as content. For a larger or binary file (up to 32 MiB), omit
content and run the returned curl command in a shell within 10 minutes. Its URL
accepts one upload.
Approvals and questions
- A run started through MCP or a schedule pauses before each action outside the Workspace
(connected-account and MCP writes, outbound HTTP writes, git push, publishing, deploys,
email, public tunnels, irreversible browser actions, workflow activation) until the
account owner approves that one action in the Plori web app.
awaiting_input is an approval or a question. Show it to the human, with the approval's
approve_url.
- You cannot approve or grant
always_allow. answer_pending_input can only deny a
request or answer a question. Never send secrets through it.
- Then follow the
continuation_run_id from get_run_result. answer_pending_input
returns the continuation's run_id, or continuation_pending: true while files save;
then poll the paused run until continuation_run_id is set.
list_pending_inputs is the current queue; an old run can keep awaiting_input. A
consent_tool row is an outward write: only the human approves it or grants standing
consent, in the web app.
- Requests go to the worker's creator, or to the owner for the manager. The owner can
also answer a worker's request. Other members can read it and may answer after the
account's timeout, 30 minutes by default. Viewers never answer. Standing grants and
secret answers stay owner-only.
list_pending_inputs includes assigned_to,
open_to_members_at and can_act for the caller. Credential restrictions still apply.
- A member's monthly spend cap can refuse a new run with 402. Schedules, previews,
workflows, Workspace settings and deletion are owner-only in M1.
- Clients with the MCP Tasks extension get a task handle instead. A returned call does not
report later changes: poll, or keep a subscription.
Scheduled runs
schedule_run (workspace_id, prompt, delay_seconds or an RFC3339 fire_at) returns
status: "awaiting_confirmation" and a confirm_url. Show the human the prompt, the time
and the confirm_url. The run is queued only after the owner confirms in the web app.
Run several agents yourself
Only for a client that manages the agents itself. Each agent works on its own copy of the
files. Plori submits changed files when a run completes normally and accepts a clean comparison.
create_workspace_worker (workspace_id, task, idempotency_key) returns
agent_id and task_group_id at once; the agent queues while capacity is busy. Pass
task_group_id to later calls to group their costs and stop request;
get_workspace_costs reports cost. Worker agents do not count against the agent limit.
- Poll
get_workspace_worker or list_workspace_workers until save_state is ready.
get_run_result (run_id, workspace_id) reads the reply and approval requests.
steer_workspace_worker messages a running turn (409 run_not_running if it has not
started, is paused or has ended). cancel_run stops one agent,
stop_workspace_task_group a group.
- Check
get_workspace_worker (change_status, changeset_id), then get_workspace_changeset.
Use submit_workspace_changeset only for saved, unsubmitted work after an error, cancellation
or stop, or after recompare_required.
- Poll
get_workspace_changeset: accepted with result_revision confirms the files landed.
needs_resolution: ask the Workspace's agent to combine files with send_workspace_message,
or reject and start another worker.
- For
review_ready, accept_workspace_changeset completes the merge (expected_current_revision = the
comparison_current_revision; validation_evidence = 1-32 short statements of the
checks you made). reject_workspace_changeset discards it. After accept, poll until
state is accepted and result_revision is set.
Accept errors:
- 409
current_revision_conflict: another merge landed first. Submit again, then repeat
steps 4 and 5.
- 409
workspace_changeset_unresolved: not computed yet, or it has conflicts. A merge with
conflicts cannot be completed through MCP. To have conflicts fixed, send the task to the
Workspace with send_workspace_message; its agent fixes conflicts.
- 409
workspace_changeset_busy: a run or file operation is active. Accept after it ends.
These agents pause before outward actions like other runs. Workflows, usage and disk
reports, trash and connected accounts are not on MCP; use the web app, REST or the CLI.
Workspace CLI commands
The CLI also covers what MCP does not. Use exact IDs; there is no implicit active Workspace.
Groups: workspace, independent-agent, copy, revision, workspace-files,
worker, task-group, changeset, operation; plori GROUP --help lists actions and
flags. Commands that create something take --idempotency-key KEY. To complete a merge:
plori changeset accept WORKSPACE_ID CHANGESET_ID --current-revision REVISION_ID --evidence TEXT --idempotency-key KEY with the comparison_current_revision. Writes to a
copy need the --if-match ETag you read. Use --yes (agent-retire,
workspace delete) only when the human authorized the action. Examples:
https://plori.ai/docs/cli
Long runs
Use the default wait. If the result is running, call get_run_result after
poll_after_seconds, until the run completes or is awaiting_input.
Troubleshooting, optional: if your client drops the results of long calls, pass
wait_seconds with a shorter hold, or wait=false. In Codex, tool_timeout_sec on the
plori entry in config.toml sets how long a call can last. plori watch in a background
shell prints run endings and input requests.
CLI commands
Agents are addressed by name or ID. Every command accepts --json.
plori run <name> "message" waits for the reply; --no-wait returns a run ID.
plori result <name> <run-id> --wait (bounded by --wait-seconds) reads the result.
plori watch prints run endings and input requests as JSON lines. plori inbox lists
what ended and what waits on you.
plori inputs <name>; plori answer <run-id> <tool-call-id> --approve|--deny|--value <v>.
Add --always-allow only on the human's explicit instruction.
plori schedules create <workspace> "prompt" --in <seconds> (or --at <rfc3339>).
plori attach is for a human at the keyboard; an agent uses --read-only to tail.
Exit codes of run, result --wait and watch: 0 succeeded, 1 API or runtime failure,
2 usage error, 3 credentials missing, rejected or expired, 4 control plane unreachable, 10
awaiting human input, 20 run error, 30 cancelled, 40 wait ran out with the run still going.
Costs and limits
Runs spend credits. The plan sets included credits, disk, agent count, workflow limits and
the length of one run. Registered accounts have no limit on concurrent agent runs.
Anonymous trials allow at most 2 concurrent agent runs across their agents.
A third run makes send_workspace_message return 429 with advice to register free.
Registered accounts have no token ceiling per turn unless max_turn_tokens sets one.
max_turn_seconds sets a turn's time budget.
More
1---2name: plori3description: Runs tasks on Plori cloud agents that continue after the chat ends, such as background or parallel builds, scheduled automations, long jobs and research saved as files. Not for quick tasks.4metadata:5 source: https://skillmd.com/skills/hashgraph-online/plori6---78# Using plori from an agent910If you were asked to set up plori, follow Connect below: add the plori MCP server to this11client, have the account owner sign in, and confirm the tools respond before you report12success.1314Plori runs AI agents in cloud Workspaces. Several agents can work on one project at once, and15Plori merges their changes back into the Workspace. A Workspace holds a project's files under16`/workspace`, saved versions of those files, a main conversation and the run history.1718## Connect1920If this client already lists Plori tools and `list_workspaces` answers, skip this section.2122MCP: Streamable HTTP at `https://api.plori.ai/mcp`.2324- OAuth 2.1: an unauthenticated request returns 401 with the discovery chain (RFC 972825 metadata at https://api.plori.ai/.well-known/oauth-protected-resource, dynamic client26 registration, authorization code + PKCE). The account owner signs in with an email code.27- API key: the account owner creates one at https://plori.ai. Send28 `Authorization: Bearer plori_sk_...`.2930### Claude Code: connect from this conversation3132Read these instructions in the current conversation before starting authentication.33Installing a skill or plugin is optional. Use this flow only in interactive Claude Code34when its Plori MCP client exposes both `authenticate` and `complete_authentication`.35Other clients use their ordinary OAuth or API-key setup above.3637If this Claude Code build does not expose both `authenticate` and38`complete_authentication`, use `/mcp` instead. Pick plori, choose Authenticate, then39sign in with the emailed code. If the browser cannot reach the localhost callback,40Claude Code prompts for it directly in its own dialog, never in chat. Then verify with41`list_workspaces`.42431. Check the current MCP configuration and active tools. Reuse an existing Plori server44 at `https://api.plori.ai/mcp`; do not add duplicate entries or replace a different45 server with the same name. If missing, configure it once with46 `claude mcp add --transport http plori https://api.plori.ai/mcp`.47 Confirm the server is available in this conversation before authenticating. Saving48 configuration alone does not prove that it loaded. If its tools are missing, ask49 the user to type `/reload-plugins` in this Claude Code conversation, then resume50 these steps in the same session. This also refreshes MCP configuration when no51 plugins are installed. It is a user command; do not try to invoke it through the52 Skill tool. Confirm the authentication tools are available before proceeding. If they53 are still missing, use `/mcp` instead (above).542. If Plori tools already work, the connection is complete. Otherwise, call the55 client's Plori `authenticate` tool using its exposed schema. Keep the returned56 authorization URL intact. Do not construct a new OAuth request or change its state,57 redirect URI, or PKCE challenge.583. POST JSON `{"authorization_url":"<the exact client URL>"}` once to59 `https://api.plori.ai/oauth/pair`. The response contains `user_code`,60 `verification_uri`, `verification_uri_complete`, `device_code`,61 `expires_in` (seconds), and `interval` (seconds). Keep `device_code` private.62 If a permission rule, hook, or tool denies this request, stop and use the fallback below.634. Tell the user: "Open <verification_uri> and enter <user_code>. Sign in and approve64 the connection; I will continue when you finish." The user can open the page on65 their phone. Display the short address and code, not the authorization or callback66 URL. Do not ask the user to copy a callback URL into chat.675. Poll `https://api.plori.ai/oauth/pair/poll` with JSON68 `{"device_code":"<device_code>"}`. Keep only one request in flight, allow each69 request at least 30 seconds to finish, and wait at least `interval` seconds70 between requests. The server can hold a pending request for 25 seconds.71 Read pending and failure responses from the JSON `error` field, not `status`.72 On `error: "authorization_pending"`, continue. On `error: "slow_down"`, use the73 larger of your previous delay plus five seconds and the response's `interval`74 for all subsequent requests. Honor `Retry-After` when present on HTTP 429.75 On HTTP 503 with `error: "temporarily_unavailable"`, preserve this pairing and76 the pending client authentication. Wait at least the larger of your poll interval77 and `Retry-After` (five seconds), then retry the same device code. A temporary78 failure does not extend `expires_in`; retry only within the original four-minute79 window while the client authentication remains pending.80 If a permission rule, hook, or tool denies a poll request, stop and use the fallback below.816. On `status: "approved"`, pass the returned `callback_url` directly to the same client's82 `complete_authentication` tool using its exposed schema. Do not navigate to the83 loopback URL or exchange the code yourself: the client owns the PKCE verifier.84 Then discover Plori tools and call `list_workspaces` to confirm the connection before85 reporting success. This verification does not create a Workspace or start paid work.8687#### Fallback when a pairing request is denied8889Use this fallback after the first permission, hook, or tool denial of either pairing90POST. Do not make another request to `/oauth/pair` or `/oauth/pair/poll`, and do not91try curl, wget, WebFetch, Python, a shell script, or another generic network92tool.93941. Show the user the exact authorization URL returned by the current `authenticate`95 call. Ask them to open it in their browser, sign in, and approve the connection.96 Do not edit the URL.972. After approval, the authorization server redirects the browser to a localhost98 callback. If that99 redirect connects, let the client finish authentication. If the browser cannot100 connect to localhost, ask the user to copy the final localhost callback URL from101 the browser address bar and paste it into this conversation. It contains one-time102 authorization data, so tell the user not to paste it anywhere else. Do not ask for103 that URL before the redirect has failed.1043. Pass a pasted callback URL only to the same client's `complete_authentication`105 tool. Do not open, fetch, rewrite, log, or exchange it yourself.1064. Discover Plori tools and call `list_workspaces` before reporting success. This check107 does not create a Workspace or start paid work.108109If the authorization URL or pending client authentication expires during this110fallback, discard it and call `authenticate` again. Use only the new authorization111URL. Never reuse an expired URL.112113Stop on `access_denied`; do not retry a denied request automatically. On114`expired_token`, an already-consumed pairing, or a client authentication timeout,115start a fresh client authentication before creating another pairing. Never reuse the116old authorization URL. Pairing lasts four minutes to fit within the client's pending117login. If the approved response is lost, restart the whole flow; the callback is118returned only once. Keep approval polling active while the user signs in.119120Remote Control can use this flow only when it controls that same interactive Claude121Code process and the two authentication tools are available. A separate hosted122Claude.ai connector or Agent SDK session needs its own supported authentication flow.123URLs can still appear in client tool results; do not promise to hide tool transcripts.124125#### Switch accounts or sign out126127To connect a different Plori account or sign out, use `/mcp`. Pick plori, choose Clear128authentication, then Authenticate again with the new account's email code.129`claude mcp remove` does not clear the stored token.130131### CLI and REST132133CLI: `curl -fsSL https://plori.ai/install.sh | sh` (Windows: `irm https://plori.ai/install.ps1 | iex`),134`npm i -g @plori/cli`, or `npx -y @plori/cli`. The shell installer writes to135`~/.local/bin` and edits no rc file, so run `export PATH="$HOME/.local/bin:$PATH"` first.136`plori login` signs in through the browser; headless callers use137`plori login --key plori_sk_...` or set `PLORI_API_KEY`. Piped output and `--json` give138JSON.139140REST: `https://api.plori.ai/v1` with the same bearer token. Detail: https://plori.ai/auth.md141142## Tools143144The MCP server has 24 tools. Invitees use their own login, API keys and OAuth145sessions. Workspace calls resolve access to the owning account from the resource.146147### Workspaces148149- `list_workspaces` lists your own and shared Workspaces with `account`150 (`user_id`, `email`) and your `role` (`owner`, `member` or `viewer`).151 Pass `workspace_id` for one. `storage_readiness` is present while its storage starts.152- `create_workspace` (`name`, `idempotency_key`) returns `id` and `default_agent_id`,153 the Workspace's agent. Without `default_manager_agent_id` it creates that agent, which154 counts against the agent limit. Optional `account` selects a shared account by user id.155 Omit it for your own account. Members can create there. Viewers cannot. The result156 includes `account` and `role`. Names are not unique: reuse a Workspace.157- `delete_workspace` permanently deletes its files, saved versions, copies and158 conversations.159- `get_credits` returns the balance. Check it before long work.160161### Send a task162163`send_workspace_message` (`workspace_id`, `message`) runs a task in the Workspace's main164conversation, or in the one named by `session_id`. Use it for most work, including work165that can be split: the Workspace's own agent splits it between several agents, merges their166changes and fixes conflicts.167168- For a new or continued run, the call holds until the run ends, pauses for input,169 or the hold ends. The server picks a hold that fits your client. Use that default.170- If the result is `running`, call `get_run_result` (`workspace_id`, `run_id`) after171 `poll_after_seconds`. Repeat until the run completes or is `awaiting_input`.172- `get_run_result`, `cancel_run`, `list_runs`, `list_pending_inputs` and173 `schedule_run` take the `workspace_id`.174- Reuse `session_id` to keep context. An idle conversation starts a run. While running,175 plain text returns `status: "steering"` or `"queued"` with `steer_id`.176- If the paused run has exactly one ordinary question assigned to you, your message177 answers it. Otherwise it queues, and `pending_inputs` names the request and assignee.178 A message never cancels a pending request. If the result has `status: "answered"`179 and `continuation_pending: true`, read the paused run until it reports180 `continuation_run_id`. Do not submit the answer again.181- A queued or steering receipt returns immediately, regardless of `wait`. It includes182 `run_id`, `session_id`, `agent_id`, `workspace_id`, `url` and `poll_after_seconds`.183 Its `run_id` is the running or paused run, not a result for this message. Use184 `list_runs` to find a later queued turn. No lookup connects `steer_id` to that run.185- 409 `conversation_busy` still applies to attachments or run options in a busy186 conversation, and to working-copy conflicts. Send attachments and options when idle.187- A retry with the same `idempotency_key` returns the original run or message receipt for 24 hours.188 `max_turn_tokens` sets an optional token ceiling for the turn. `cancel_run` stops a run.189190### Files191192- Only files under `/workspace` persist between runs. Software installed elsewhere and193 processes a run starts do not. Use `TMPDIR` for temporary files.194- A completed run does not prove its files are saved: wait for `file_source.state`195 `ready` with no `save_failure`.196- A completed run's `files` are signed URLs that need no other credential.197 They expire about 10 minutes after the result. Call `get_run_result` again for fresh links.198 `read_workspace_file` reads a saved version: `current_revision`, an agent's199 `saved_revision_id`, or a changeset's `base_revision`, `incoming_revision` or200 `result_revision`. A path such as `/workspace/a.md` is not a URL.201- `upload_workspace_file` writes a file into the Workspace's current files. Pass text up202 to 262144 bytes as `content`. For a larger or binary file (up to 32 MiB), omit203 `content` and run the returned `curl` command in a shell within 10 minutes. Its URL204 accepts one upload.205206### Approvals and questions207208- A run started through MCP or a schedule pauses before each action outside the Workspace209 (connected-account and MCP writes, outbound HTTP writes, git push, publishing, deploys,210 email, public tunnels, irreversible browser actions, workflow activation) until the211 account owner approves that one action in the Plori web app.212- `awaiting_input` is an approval or a question. Show it to the human, with the approval's213 `approve_url`.214- You cannot approve or grant `always_allow`. `answer_pending_input` can only deny a215 request or answer a question. Never send secrets through it.216- Then follow the `continuation_run_id` from `get_run_result`. `answer_pending_input`217 returns the continuation's `run_id`, or `continuation_pending: true` while files save;218 then poll the paused run until `continuation_run_id` is set.219- `list_pending_inputs` is the current queue; an old run can keep `awaiting_input`. A220 `consent_tool` row is an outward write: only the human approves it or grants standing221 consent, in the web app.222- Requests go to the worker's creator, or to the owner for the manager. The owner can223 also answer a worker's request. Other members can read it and may answer after the224 account's timeout, 30 minutes by default. Viewers never answer. Standing grants and225 secret answers stay owner-only. `list_pending_inputs` includes `assigned_to`,226 `open_to_members_at` and `can_act` for the caller. Credential restrictions still apply.227- A member's monthly spend cap can refuse a new run with 402. Schedules, previews,228 workflows, Workspace settings and deletion are owner-only in M1.229- Clients with the MCP Tasks extension get a task handle instead. A returned call does not230 report later changes: poll, or keep a subscription.231232### Scheduled runs233234`schedule_run` (`workspace_id`, `prompt`, `delay_seconds` or an RFC3339 `fire_at`) returns235`status: "awaiting_confirmation"` and a `confirm_url`. Show the human the prompt, the time236and the `confirm_url`. The run is queued only after the owner confirms in the web app.237238### Run several agents yourself239240Only for a client that manages the agents itself. Each agent works on its own copy of the241files. Plori submits changed files when a run completes normally and accepts a clean comparison.2422431. `create_workspace_worker` (`workspace_id`, `task`, `idempotency_key`) returns244 `agent_id` and `task_group_id` at once; the agent queues while capacity is busy. Pass245 `task_group_id` to later calls to group their costs and stop request;246 `get_workspace_costs` reports cost. Worker agents do not count against the agent limit.2472. Poll `get_workspace_worker` or `list_workspace_workers` until `save_state` is `ready`.248 `get_run_result` (`run_id`, `workspace_id`) reads the reply and approval requests.249 `steer_workspace_worker` messages a running turn (409 `run_not_running` if it has not250 started, is paused or has ended). `cancel_run` stops one agent,251 `stop_workspace_task_group` a group.2523. Check `get_workspace_worker` (`change_status`, `changeset_id`), then `get_workspace_changeset`.253 Use `submit_workspace_changeset` only for saved, unsubmitted work after an error, cancellation254 or stop, or after `recompare_required`.2554. Poll `get_workspace_changeset`: `accepted` with `result_revision` confirms the files landed.256 `needs_resolution`: ask the Workspace's agent to combine files with `send_workspace_message`,257 or reject and start another worker.2585. For `review_ready`, `accept_workspace_changeset` completes the merge (`expected_current_revision` = the259 `comparison_current_revision`; `validation_evidence` = 1-32 short statements of the260 checks you made). `reject_workspace_changeset` discards it. After accept, poll until261 `state` is `accepted` and `result_revision` is set.262263Accept errors:264265- 409 `current_revision_conflict`: another merge landed first. Submit again, then repeat266 steps 4 and 5.267- 409 `workspace_changeset_unresolved`: not computed yet, or it has conflicts. A merge with268 conflicts cannot be completed through MCP. To have conflicts fixed, send the task to the269 Workspace with `send_workspace_message`; its agent fixes conflicts.270- 409 `workspace_changeset_busy`: a run or file operation is active. Accept after it ends.271272These agents pause before outward actions like other runs. Workflows, usage and disk273reports, trash and connected accounts are not on MCP; use the web app, REST or the CLI.274275### Workspace CLI commands276277The CLI also covers what MCP does not. Use exact IDs; there is no implicit active Workspace.278Groups: `workspace`, `independent-agent`, `copy`, `revision`, `workspace-files`,279`worker`, `task-group`, `changeset`, `operation`; `plori GROUP --help` lists actions and280flags. Commands that create something take `--idempotency-key KEY`. To complete a merge:281`plori changeset accept WORKSPACE_ID CHANGESET_ID --current-revision REVISION_ID282--evidence TEXT --idempotency-key KEY` with the `comparison_current_revision`. Writes to a283copy need the `--if-match` ETag you read. Use `--yes` (`agent-retire`,284`workspace delete`) only when the human authorized the action. Examples:285https://plori.ai/docs/cli286287## Long runs288289Use the default wait. If the result is `running`, call `get_run_result` after290`poll_after_seconds`, until the run completes or is `awaiting_input`.291292Troubleshooting, optional: if your client drops the results of long calls, pass293`wait_seconds` with a shorter hold, or `wait=false`. In Codex, `tool_timeout_sec` on the294plori entry in `config.toml` sets how long a call can last. `plori watch` in a background295shell prints run endings and input requests.296297## CLI commands298299Agents are addressed by name or ID. Every command accepts `--json`.300301- `plori run <name> "message"` waits for the reply; `--no-wait` returns a run ID.302 `plori result <name> <run-id> --wait` (bounded by `--wait-seconds`) reads the result.303- `plori watch` prints run endings and input requests as JSON lines. `plori inbox` lists304 what ended and what waits on you.305- `plori inputs <name>`; `plori answer <run-id> <tool-call-id> --approve|--deny|--value <v>`.306 Add `--always-allow` only on the human's explicit instruction.307- `plori schedules create <workspace> "prompt" --in <seconds>` (or `--at <rfc3339>`).308- `plori attach` is for a human at the keyboard; an agent uses `--read-only` to tail.309310Exit codes of `run`, `result --wait` and `watch`: 0 succeeded, 1 API or runtime failure,3112 usage error, 3 credentials missing, rejected or expired, 4 control plane unreachable, 10312awaiting human input, 20 run error, 30 cancelled, 40 wait ran out with the run still going.313314## Costs and limits315316Runs spend credits. The plan sets included credits, disk, agent count, workflow limits and317the length of one run. Registered accounts have no limit on concurrent agent runs.318Anonymous trials allow at most 2 concurrent agent runs across their agents.319A third run makes `send_workspace_message` return 429 with advice to register free.320Registered accounts have no token ceiling per turn unless `max_turn_tokens` sets one.321`max_turn_seconds` sets a turn's time budget.322323## More324325- Integration entry point: https://plori.ai/agents.md326- MCP connect guide: https://plori.ai/mcp327- CLI on npm: https://www.npmjs.com/package/@plori/cli328- Authentication detail: https://plori.ai/auth.md329- Site map for agents: https://plori.ai/llms.txt