Opencomputer

OpenComputer Documentation Audit

The platform docs read confidently and the surface area is broad (sandboxes, managed agents, reserved capacity, secrets, signed URLs, CLI, two SDKs). But once you cross-read the pages, the foundational contracts — networking, memory tiers, base URL, env-var names — disagree with each other, and the single most consequential gotcha (no egress without a SecretStore) is buried in a guide instead of stated up front.

1. Outbound networking contradicts itself across three pages (critical)

Location: /how-it-works, /quickstart, /sandboxes/overview, /guides/browser-automation

Problem: How It Works says: "Every sandbox gets full outbound internet access via a TAP device with NAT. No firewall or allowlist to configure." The Sandboxes overview shows await Sandbox.create() with no secret store. But the Browser Automation guide states: "This is the single most common gotcha. A sandbox without a secretStore attached has no outbound egress at all — every HTTPS request gets a 407 from the internal proxy."

Consequence: A developer follows the Quickstart or Introduction snippet, creates a sandbox, runs curl https://example.com or any package install, and gets a 407 they cannot diagnose from the docs they were just reading. The "no firewall to configure" claim is actively false for the default code path.

The fix: Pick one model and state it everywhere. If the egress proxy is mandatory, say so in How It Works and Sandboxes overview, make secretStore required (or default-attached) in the SDK examples, and add the 407 symptom to Troubleshooting. Don't hide a platform-level networking gate inside a browser-automation guide.

2. Memory/CPU tier table contradicts itself between API, SDK, and CLI (critical)

Location: /api-reference/sandboxes/create, /sandboxes/elasticity, /reference/python-sdk/scaling, /reference/cli/scaling

Problem: The Create Sandbox API reference and the Elasticity page both list four tiers, ceiling at 16 GB / 4 vCPU. But the Python SDK scaling page says: "Memory tiers are fixed: 1024, 4096, 8192, 16384, 32768, 65536 MB." The CLI scaling page repeats the same six-tier list, including 32 GB and 64 GB tiers that don't exist in the API tier table.

Consequence: An agent (or a human) reads the SDK page, requests memory_mb=32768, and the API rejects it because the documented allowed values are 1024 | 4096 | 8192 | 16384. Or worse: the SDK accepts it, the API doesn't, and the failure path is undocumented. Either way the contract is broken.

The fix: Reconcile to a single source of truth — most likely a tiers.json-style include rendered into every page. If 32/64 GB are gated beta tiers (parallel to the disk-sizing closed beta), say so explicitly and mark them as such on every page that lists tiers, not just the SDK reference.

3. The API Reference base URL is never stated (critical)

Location: /api-reference/overview

Problem: The page is literally titled "Base URL" and the scraped content under that heading is empty. Elsewhere the docs use two different host shapes: sandbox endpoints render as POST /api/sandboxes (no host, no version) while the Telegram channel example uses https://api.opencomputer.dev/v1/agents/my-agent/channels/telegram (versioned, fully qualified).

Consequence: Developers can't construct a single API request from the reference without guessing the host. Agents trying to discover the API surface have no canonical base URL to anchor to. Is it https://api.opencomputer.dev/api/... or https://api.opencomputer.dev/v1/...? Both appear, neither is declared.

The fix: Put the canonical base URL in the API Reference overview as the first thing on the page. If sandbox endpoints and agent endpoints live on different bases or different versions, state that explicitly with both URLs side by side and explain why.

4. secretStore Python availability is contradicted (significant)

Location: /sandboxes/overview vs /reference/python-sdk/sandbox

Problem: The Sandboxes overview says: "cpuCount, memoryMB, and secretStore are not available in the Python SDK. Use the HTTP API directly for custom resources from Python." But the Python SDK reference for Sandbox.create(...) says only: "cpuCount and memoryMB are not available in the Python SDK." — secretStore is omitted from the unavailable list. Meanwhile the Secrets quickstart shows secretStore: 'my-agent-secrets' in TypeScript with no Python equivalent.

Consequence: Combined with finding #1 (no egress without a SecretStore), a Python developer reading the SDK reference believes they can pass secretStore but can't — and a sandbox without one can't even reach pypi.org. This is the worst-case combination: the most consequential platform contract is silently unavailable in one of the two officially supported SDKs.

The fix: Update the Python SDK reference to explicitly list secretStore as unsupported and link to a documented HTTP fallback. Better: ship Python parity, because requiring HTTP API calls to enable basic outbound networking from a Python SDK is a non-starter for production usage.

5. API key env var name varies between Troubleshooting, CLI, and the Telegram example (significant)

Location: /troubleshooting, /reference/cli/overview, /agents/channels/telegram

Problem: Troubleshooting tells users to check OPENCOMPUTER_API_KEY ("Check that OPENCOMPUTER_API_KEY is set: echo $OPENCOMPUTER_API_KEY"). The CLI reference also documents the env var as OPENCOMPUTER_API_KEY. But the Telegram channel REST example uses a totally different name: -H "X-API-Key: $OC_API_KEY". There is no note that OC_API_KEY is just a shell-local alias the doc author chose — it reads as authoritative.

Consequence: A developer copies the Telegram snippet, exports OC_API_KEY, gets a 401, opens Troubleshooting, and Troubleshooting tells them to check a variable name that isn't the one any prior page set. Agents scraping the docs for the canonical env var name will pick one or the other arbitrarily.

The fix: Standardize on OPENCOMPUTER_API_KEY everywhere examples reference an env var, or explicitly document OC_API_KEY as an alias in one canonical place and link to it from every example.

6. Two different CLI install methods, neither cross-referenced (significant)

Location: /introduction vs /cli/overview

Problem: Introduction promotes: curl -fsSL https://raw.githubusercontent.com/diggerhq/opencomputer/main/scripts/install.sh | bash (installs to ~/.local/bin, no sudo). The CLI overview install snippet is a direct binary download to /usr/local/bin/oc (requires sudo, no checksum, only the macOS Apple Silicon variant shown). Neither page mentions the other method.

Consequence: Developers get inconsistent installs across docs entry points — one ends up on PATH only if ~/.local/bin is in PATH, the other requires sudo. The CLI overview also implies macOS-arm64 is the only target; nothing is said about Linux or x86 macOS binaries that the install script presumably resolves.

The fix: Standardize on the install script as the recommended path, list the direct-download URLs for every platform as the "manual" fallback, and cross-link the two pages.

7. diskMB is documented in the SDK but absent from the Create Sandbox API reference (significant)

Location: /sandboxes/overview vs /api-reference/sandboxes/create

Problem: The Sandboxes overview documents diskMB with a default of 20480 and a range of "20GB–256GB" (closed beta). The Create Sandbox API reference enumerates template, timeout, cpuCount, memoryMB — but does not list diskMB as a parameter. An agent reading the OpenAPI-style endpoint reference cannot discover the disk-sizing parameter at all.

Consequence: API consumers and AI agents that scrape the endpoint reference for the canonical parameter set won't know diskMB exists. The closed-beta caveat also means failures from oversize requests come back without the docs anchor to explain them.

The fix: Add diskMB to the Create Sandbox API reference parameter list with the same range and closed-beta note. If the parameter is hidden behind an org-level gate, document the gate and the rejection error.

8. Reserved capacity pricing table is rendered without column headers (significant)

Location: /reserved-capacity/overview

Problem: The scraped pricing table reads: | Rate | $0.060/GB-hour | $0.012/GB-hour | — the header row is missing the columns that label which rate is "reserved" vs "on-demand." The prose below clarifies, but the table itself is unlabeled.

Consequence: Developers scanning the table for a price comparison cannot tell which rate is which. AI agents parsing the table for structured pricing data will associate the wrong number with the wrong product. Pricing pages are the one place ambiguity is most expensive.

The fix: Restore the header row (| On-demand | Reserved |) and label the rate row explicitly. Consider adding a small example calculation so the 5× ratio is unambiguous.

9. Hermes "LLM key configured" is undefined (significant)

Location: /agents/cores/hermes

Problem: Hermes setup says: "This boots a sandbox with Hermes pre-installed, an LLM key configured, and the gateway running." The doc never says which LLM provider, whose key it is, where it comes from, what model it points at, how to override it, or how billing for that key works.

Consequence: A developer creating their first Hermes agent doesn't know if they're spending OpenComputer credits, their own API balance, a free trial allotment, or nothing at all. Cost is opaque, override mechanics are undocumented, and prod readiness can't be assessed.

The fix: Spell out the default LLM provider/model on the Hermes page, document who pays for inference, show the env var or config field to bring your own key, and link to where Hermes consumes that key inside its YAML config.

10. Tag retroactive rewriting is documented but buried as ordinary prose (significant)

Location: /api-reference/sandboxes/set-tags

Problem: The Set Sandbox Tags page admits: "a sandbox re-tagged from team=payments to team=growth will appear under growth in every subsequent /usage query, including for time before the retag." This is a major billing-attribution default — historical spend reports will literally produce different answers next month than this month — but it's tucked into a single paragraph at the bottom of a low-traffic endpoint page, not surfaced on /api-reference/usage/get-usage or in any cost/billing overview.

Consequence: Finance or platform teams who build dashboards against /api/usage get a silent contract that retags rewrite history. There is no opt-in for immutable tagging and no warning on the usage endpoint itself. A reader who lands on /api/usage first won't see this caveat at all.

The fix: Cross-link the rewriting behavior from the /api/usage endpoint reference and any billing overview. Consider an opt-in immutableTags mode, or at minimum document tagsLastUpdatedAt as a required join key for historical attribution.

11. The docs site uses two different URL trees for the API reference (significant)

Location: /troubleshooting, /how-it-works, /sandboxes/overview, /api-reference/overview

Problem: Troubleshooting closes with: "API Reference: HTTP API · TypeScript SDK · Python SDK · CLI" — and the HTTP API link points to /reference/api. How It Works references /reference/api#base-url--authentication. The Sandboxes overview links /reference/api#sandbox-lifecycle. But the actual API reference lives under /api-reference/overview with per-endpoint pages under /api-reference/sandboxes/.... Top-of-funnel pages (How It Works, Sandboxes overview, Troubleshooting) all link into a URL tree that doesn't match the live reference tree.

Consequence: If /reference/api is a redirect, anchor links like #sandbox-lifecycle and #base-url--authentication break silently because anchors don't survive route changes. If it isn't a redirect, every one of those links 404s. Either way, the developer's first three reading paths into the API reference land somewhere broken, and agents scraping the docs see two divergent canonical reference URLs.

The fix: Standardize on one URL tree (/api-reference/... is the more specific one). Replace every /reference/api link in How It Works, Sandboxes overview, and Troubleshooting. Either preserve the anchors as /api-reference/...#... targets or rewrite them to point at the per-endpoint pages now in use.

12. oc exec attach is documented as not implemented (minor)

Location: /reference/cli/exec

Problem: The CLI reference for oc exec attach <id> <session-id> says: "Not yet implemented. The command exists but prints guidance to use the SDK or a WebSocket client (websocat)."

Consequence: A documented command that exists but doesn't work is a footgun for shell scripts and agent callers. Listing it in the reference at all (rather than omitting until shipped) trains users to discover it and then bounce off.

The fix: Either hide the command from the reference until it ships, or replace the section with a clear "Not available — use sandbox.exec.attach() in the SDK" pointer and add a tracking issue link.

13. gbrain install flow doesn't surface its known runtime prerequisites (minor)

Location: /agents/packages/gbrain

Problem: The Debugging section names three failure modes that are install-time invariants, not debugging trivia: (1) "the MCP config needs absolute paths (e.g., /home/sandbox/.bun/bin/bun), not bare bun"; (2) "gbrain uses OpenAI for vector embeddings. If OPENAI_API_KEY is missing from the MCP env config, pages are stored but semantic search won't work"; (3) the workaround command hermes gateway run --replace for a gateway that didn't pick up MCP — which is not documented on /agents/cores/hermes or anywhere else in the evidence. The Install section's five phases (Allocate / Provision / Initialize / Wire / Verify) mention none of these.

Consequence: Developers run the documented one-line install, semantic search silently doesn't work because no one told them to set OPENAI_API_KEY, or the gateway didn't reload and they have to discover an undocumented command to fix it. The Wire phase should be the place these prerequisites are surfaced.

The fix: State in the Install section whether oc agent install gbrain writes absolute paths automatically and whether OPENAI_API_KEY is required. Add hermes gateway run --replace to the Hermes core reference as a documented recovery command, not a debugging hint.

What they do well

• llms.txt exists — an actual content index is published, which most platforms still skip.
• Severity-aware exit codes — oc agent's class-based exit code scheme (3/4/5 for upstream-4xx, conflict, transient) is exactly what agent callers need to branch on, and it's documented.
• The Secrets security-properties table is concrete: AES-256-GCM, env-time sealing, host-only plaintext, allowlists. That's the level of specificity the rest of the docs should match.

Top 3 recommendations

1. Resolve the egress contract. State on Quickstart, Sandboxes overview, and How It Works whether outbound networking requires a SecretStore. This is the single largest "works on my machine" trap in the docs.
2. One tier table, rendered everywhere. Whether 32 GB and 64 GB tiers exist needs to be answered identically on the API reference, Elasticity, Python SDK scaling, and CLI scaling pages.
3. Pick one URL tree and one env-var name. Fill in /api-reference/overview with the canonical base URL and auth header, redirect or rewrite every /reference/api* link, and standardize on OPENCOMPUTER_API_KEY in every example. These are the anchors agents and humans both need before any other reference page is useful.