Skip to main content
When you write a prompt for a runtime (claude or codex), it’s useful to know exactly what the agent can do. Both runtimes act through the same fixed set of tools against the session’s sandbox — the agent has no direct filesystem, shell, or network of its own. The runtime’s built-in local tools are disabled; only these remote tools are available.

​
Sandbox tools

bash is the only place commands run. Each call is a fresh shell, so use absolute paths or cd /workspace && .... A run surfaces as an exec.completed event ({ command, exit_code, summary }), with large output available via content_ref. To work on a public repo, the agent git clones it via bash — the sandbox has open outbound internet (below). For private repos, register a Repo and reference it in the session’s sources: it’s checked out before the first turn and the GitHub credential never enters the sandbox.
Network: the sandbox has open outbound internet by default (so git clone, package installs, and API calls just work), with private, loopback, link-local, and cloud-metadata addresses blocked.

​
User-facing tools

The agent’s final say is the session result. ask ends the turn with yield_reason: "needs_input"; answer by steering a reply, which wakes the session.

​
GitHub tools

github_publish_pull_request lets the agent open a PR without ever holding a GitHub credential. The agent edits files in /workspace/sources/<source> and makes local commits as usual; calling the tool hands the requested outcome to the platform, which commits the agent’s edits to an oc/<session>/<source>-<id> branch and opens the PR with a just-in-time, write-scoped token — outside the agent sandbox. It returns the PR URL.
github_publish_pull_request requires a configured GitHub App (the OpenComputer App or a bring-your-own App). It does not work with inline (risky_short_lived_token) auth, which is checkout-only — see Repos & GitHub.
add_source(repo, ref, name?) checks out an additional repo into /workspace/sources/<name> mid-session. repo is "owner/repo" (or a repo_… id), ref a branch or refs/pull/N/head, name defaults to the repo name. Same zero-credential model as the initial checkout — a Git operations sandbox mints a just-in-time, read-only token; the agent never sees it. Connected-App (oc_app) repos only. watch_pull_request(wake_on?, repo?, pr?, intent?) subscribes the session to a PR it opened; OpenComputer wakes the session when the wake condition is met. It does not block — call it, then finish the turn. Watches cover PRs the same session opened, on Connected-App (oc_app) repos only. unwatch_pull_request(repo?, pr?) stops watching; both args default to the session’s only active watch. Full flow, statuses, and delivered events: Watches.

​
External systems

These tools never hand the agent raw credentials for GitHub, Slack, Jira, or other external systems — the agent opens PRs through github_publish_pull_request above (platform-mediated, no token in the sandbox), and other actions go through the platform too. To move a session’s output into your product, register a webhook destination and handle the delivered events in your backend.

​
Prompt guidance

  • Tell the agent to do all work in the sandbox via bash/read/write — it can’t touch your machine.
  • Public repo: include the URL + branch/commit in the task text and have the agent git clone it with bash. Private repo: register a Repo and list it in the session’s sources — checked out before the first turn, no credential in the sandbox.
  • Opening a PR: have the agent edit a source under /workspace/sources/<name> and call github_publish_pull_request with that source and a title — the platform commits and opens the PR (requires a configured GitHub App; inline tokens are checkout-only).
  • Have it say a clear final result — that’s what GET /sessions/:id/result returns.
  • Have it ask only when it genuinely needs a decision; otherwise it should proceed.