Docs rewrite: full content for 17 pages (Bands A+B) by ZIJ · Pull Request #59 · diggerhq/opencomputer

ZIJ · 2026-03-11T16:56:36Z

Summary

Complete docs rewrite — 17 pages with full content covering the entire OpenComputer platform, sourced from API handlers, SDK types, CLI commands, and Dockerfile.default.

Band A (Foundations): how-it-works, reference/api (35 endpoints), reference/cli (every command/flag), agents/overview, sandboxes/overview
Band B (Entity + SDK Reference): 3 agent pages (events, tools, multi-turn), 7 sandbox entity pages (running-commands, files, terminals, checkpoints, templates, patches, preview-urls), 2 SDK reference pages (TypeScript + Python)
Scaffolding (prior commits): 29 page stubs, mint.json nav, cross-links, docs plan

Key decisions

Contracts sourced from code (internal/api/*.go, sdks/*/src/*.ts, sdks/python/opencomputer/*.py)
Two-tier connection model documented centrally (control plane vs worker-direct)
Python SDK gaps called out explicitly (no hibernate/wake, no exec streaming, no agent resume, no public Template constructor)
sandbox.commands deprecated in favor of sandbox.exec everywhere
Default template contents derived from Dockerfile.default
Cross-linking triangle: entity page ↔ CLI guide ↔ reference

What's left (Band C)

introduction.mdx, quickstart.mdx (onboarding rewrites)
7 CLI guide pages (cli/overview, cli/sandbox, cli/exec, cli/shell, cli/checkpoint, cli/patch, cli/preview)
troubleshooting.mdx
Delete old sdks/ pages and root-level pages

Test plan

mintlify dev renders all pages without errors
Cross-links resolve (entity → CLI → reference triangle)
Code examples match actual SDK API surface
No deprecated sandbox.commands usage in examples
HTTP API field casing matches live handlers

🤖 Generated with Claude Code

Outlines restructuring from 30-page tab-based layout to 23-page single-sidebar structure. Eliminates SDK tab duplication, adds concept pages, and documents undocumented API surface. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sandboxes and Agents are the two top-level navigation groups. Sub-entities (checkpoints, templates, patches, preview URLs) are self-contained pages under Sandboxes — each opens with what the entity is, then shows the API. Eliminates abstract "Concepts" and "Features" groups in favor of concrete entity names. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Agents group moves right after Getting Started (primary use case) - Agents expands to 4 pages: overview, events, tools, multi-turn - Sandboxes keeps 8 pages for sandbox operations and sub-entities - Both groups get proper directories (agents/, sandboxes/) - Folder structure mirrors navigation groups Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- New Reference group: API (HTTP), TypeScript SDK, Python SDK - API reference covers all 35+ endpoints from router.go - SDK references are exhaustive: every class, method, type, param - Entity pages (Agents/Sandboxes) teach; Reference pages are lookup - All code examples now use tabs: TypeScript / Python / HTTP API where applicable (streaming ops can omit HTTP tab) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Corrects sandbox status states, auth headers, Python SDK gaps (hibernate/wake, exec streaming, resume), CLI patch separation, and adds WebSocket protocol spec to API reference. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove redundant Content Gaps table (all items already in page specs). Consolidate audit findings into three clean sections: SDK parity notes, intentionally omitted items, and items folded into specs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- New how-it-works.mdx: architecture, Firecracker VMs, hibernation, checkpoints, templates, networking — concise technical overview - Quickstart narrowed to single agent example (2-min goal) - Changelog removed (stub doesn't earn its place) - API ref: removed omitted params from create sandbox endpoint - Intro: pin OPENCOMPUTER_API_KEY env var name - Agents overview: cross-link to sandboxes for context Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Progressive JPEG pass 1: every page has frontmatter, section headings, and placeholder comments describing planned content. New directory structure (agents/, sandboxes/, reference/), CLI merged into Reference group, tabs removed from mint.json. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add bidirectional cross-links between entity pages, CLI guides, and reference pages so readers never hit a dead end. Restructure CLI nav group as guide-like pages with exhaustive reference in reference/cli.mdx. Update plan: cross-linking pattern, missing cli/checkpoints.mdx rename, cli/sandbox killing section, quality bar. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Each page stub is now the source of truth for its own content: GOAL, ABSORBS (old pages to merge), SOURCE (code files), KEY NOTES. Plan slimmed from ~886 to 341 lines — now a high-level execution doc: principles, structure, patterns, execution order, quality bar, audit notes. Per-page details removed from plan (nothing lost, all in stubs). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Five pages expanded from stubs to complete content, sourced from API handlers, SDK types, and CLI command definitions: - how-it-works: architecture, Firecracker VMs, connection model, hibernation, checkpoints, templates, networking, agent sessions - reference/api: 35 endpoints with request/response schemas, route availability matrix, WebSocket binary protocol, error format - reference/cli: every command, subcommand, and flag - agents/overview: entity page with TS+Python examples, start params, AgentSession methods, attach, list - sandboxes/overview: entity page with TS+Python+curl examples, create params, lifecycle, hibernation, methods, properties Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

12 pages expanded from stubs, sourced from SDK types, API handlers, CLI commands, and Dockerfile.default: Agent pages: - events: 10 event types, lifecycle, filtering, error surfaces - tools: default tools, MCP server config, system prompt, permissions - multi-turn: follow-ups, resume (TS-only), attach vs resume, reconfigure Sandbox entity pages: - running-commands: exec.run + exec.start, TS streaming vs Python gaps - working-with-files: read/write/list/mkdir/remove/exists, EntryInfo - interactive-terminals: PTY create/send/recv, resize HTTP-only - checkpoints: create/fork/restore, vs hibernation, parallel exploration - templates: Dockerfile build, default template contents, Python gap noted - patches: static Sandbox methods, on_wake strategy, execution order - preview-urls: create/list/delete, persistence, custom domains SDK reference pages: - typescript-sdk: every class, method, type across all subsystems - python-sdk: same coverage with gaps clearly marked Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vercel · 2026-03-11T16:56:41Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
opensandbox	Ready	Preview, Comment	Mar 11, 2026 9:42pm

Band C pages (10 new/rewritten): - introduction: what is OpenComputer, features, install, quick example - quickstart: working agent in 2 minutes, single focused example - cli/overview: install, configure, key workflows, scripting patterns - cli/sandbox: create, list, hibernate/wake, common patterns - cli/exec: --wait vs session mode, JSON capture, shell vs exec - cli/shell: interactive PTY, what works, tips - cli/checkpoint: create, fork, restore, checkpoint vs hibernate - cli/patch: create from file/stdin, layering, inspecting - cli/preview: expose ports, multiple ports, custom domains - troubleshooting: common errors, debugging tips, getting help Guide fix: - build-a-lovable-clone: sandbox.commands → sandbox.exec, update "Coming Soon" to reflect features that now exist (agent sessions, checkpoints, templates, preview URL auth) Deleted old pages (23): - 16 SDK tab pages (sdks/typescript/*, sdks/python/*) - 3 root-level pages (agents, running-commands, working-with-files) - 4 old CLI pages (commands, checkpoints, patches, previews) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

@anthropic-ai/opencomputer → @opencomputer/sdk Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

… 201 - Set timeout: response 200 → 204, clarify worker-direct only - Hibernate: show full response shape (sandboxID, hibernationKey, sizeBytes, status) - Fork from checkpoint: response status 200 → 201 - Kill exec session: response 200 → 204 - Kill PTY session: response 200 → 204

breardon2011

Approved, I pushed some small changes, and in my tests I didn't find any big deltas, i did uncover some bugs which I'll put in a separate

ZIJ and others added 15 commits March 11, 2026 14:12

Add comprehensive docs rewrite plan

67313b0

Outlines restructuring from 30-page tab-based layout to 23-page single-sidebar structure. Eliminates SDK tab duplication, adds concept pages, and documents undocumented API surface. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add audit findings: plan vs code surface analysis

84d87b2

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Tighten docs rewrite plan and stub contracts

c403096

Refine docs plan for agent-driven execution

9ea8abc

mintlify bot deployed to staging - docs March 11, 2026 16:57 View deployment

vercel bot deployed to Preview March 11, 2026 17:01 View deployment

mintlify bot deployed to staging - docs March 11, 2026 17:02 View deployment

Fix incorrect import path in agents and sandboxes overview

79149ec

@anthropic-ai/opencomputer → @opencomputer/sdk Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vercel bot deployed to Preview March 11, 2026 17:07 View deployment

mintlify bot deployed to staging - docs March 11, 2026 17:08 View deployment

breardon2011 self-requested a review March 11, 2026 20:26

vercel bot deployed to Preview March 11, 2026 21:29 View deployment

mintlify bot deployed to staging - docs March 11, 2026 21:30 View deployment

address further discrepancies discovered

5455052

vercel bot deployed to Preview March 11, 2026 21:42 View deployment

mintlify bot deployed to staging - docs March 11, 2026 21:43 View deployment

breardon2011 approved these changes Mar 12, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs rewrite: full content for 17 pages (Bands A+B)#59

Docs rewrite: full content for 17 pages (Bands A+B)#59
ZIJ wants to merge 19 commits intomainfrom
docs/rewrite-plan

ZIJ commented Mar 11, 2026

Uh oh!

vercel bot commented Mar 11, 2026 •

edited

Loading

Uh oh!

breardon2011 left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

ZIJ commented Mar 11, 2026

Summary

Key decisions

What's left (Band C)

Test plan

Uh oh!

vercel bot commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

breardon2011 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel bot commented Mar 11, 2026 •

edited

Loading