Skip to content

Default sandbox timeout to 0 (persistent, never hibernate)#130

Open
motatoes wants to merge 2 commits intomainfrom
feat/no-timeout-default
Open

Default sandbox timeout to 0 (persistent, never hibernate)#130
motatoes wants to merge 2 commits intomainfrom
feat/no-timeout-default

Conversation

@motatoes
Copy link
Copy Markdown
Contributor

@motatoes motatoes commented Apr 14, 2026

Summary

  • Changes the default idle timeout from 300s to 0 across TS SDK, Python SDK, CLI, server API, and worker gRPC. 0 now means persistent — never auto-hibernate; callers opt into auto-hibernate by passing an explicit timeout.
  • The router already supported `timeout == 0` as "no auto-hibernate timer" — this PR stops the API/worker layers from coercing `0 → 300` so the semantic actually reaches the router.
  • Adds a new docs page `sandboxes/timeout.mdx` explaining the default, how to opt in, idle-based behavior, and auto-wake on SDK invocation.

Motivation

Users running always-on agents (e.g. a Claw that listens for Telegram messages) currently get hibernated every 5 minutes, defeating the purpose. Exposing a `timeout=0` semantic and making it the default matches the mental model of "my sandbox stays alive until I kill it."

Behavior

timeout Behavior
omitted / 0 Persistent. Sandbox runs until explicitly killed or hibernated.
> 0 Auto-hibernates after N seconds of idleness (rolling timer).
< 0 Normalized to 0.

Any SDK operation transparently wakes a hibernated sandbox — no caller changes needed.

Files

  • TS SDK (`sdks/typescript/src/sandbox.ts`): `create()` and `wake()` default `timeout` to `0`; added JSDoc.
  • Python SDK (`sdks/python/opencomputer/sandbox.py`): `create()` and `create_from_checkpoint()` default `timeout=0`; updated docstrings.
  • CLI (`cmd/oc/internal/commands/{sandbox,checkpoint}.go`): `--timeout` flag defaults to `0` with "(0 = never hibernate)" in help text.
  • Server API (`internal/api/sandbox.go`): `createSandbox`, `wakeSandbox`, `createFromCheckpointCore` stop coercing `timeout == 0 → 300`. `setTimeout` endpoint now accepts `0` (rejects only negative).
  • Worker gRPC (`internal/worker/grpc_server.go`): same coercion fix on `CreateSandbox`, `ForkFromCheckpoint`, `WakeSandbox` paths so the new semantic works in multi-worker deployments.
  • Docs: new `docs/sandboxes/timeout.mdx` page + mint.json nav entry.

Breaking change

Clients that relied on the implicit 300s default will now get persistent sandboxes by default. They should either:

  • Upgrade and explicitly pass `timeout: 300` where the old default was intended, or
  • Accept the new persistent default and rely on manual `kill()`.

Other reference docs still say "default 300" in ~20 files (param tables, examples). Left as a follow-up since most of them are param tables rather than code-correctness issues.

Test plan

  • `go build ./...` on Linux CI (darwin build was verified locally for the packages touched — firecracker/qemu pre-existing failures on darwin are unrelated)
  • `go vet` and `go test ./internal/api/... ./internal/sandbox/...` pass
  • `tsc --noEmit` passes on the TS SDK
  • Manual: create a sandbox with default settings, leave idle 10 minutes, confirm `status=running`
  • Manual: create a sandbox with `timeout: 60`, leave idle, confirm `status=hibernated` after ~1 min
  • Manual: `sandbox.setTimeout(0)` on a running sandbox disables its timer

🤖 Generated with Claude Code

motatoes added 2 commits April 13, 2026 19:59
@motatoes
default sandbox timeout to 0 (persistent, never hibernate)
39436aa 
Change the default idle timeout across SDKs, CLI, and backend from 300s to
0, where 0 now means "persistent — never auto-hibernate". Callers who want
auto-hibernate opt in by passing an explicit timeout.

- TS SDK: `Sandbox.create` and `sandbox.wake` default to 0.
- Python SDK: `Sandbox.create` and `create_from_checkpoint` default to 0.
- CLI: `oc sandbox create`, `oc sandbox wake`, `oc checkpoint spawn`
  `--timeout` flag defaults to 0 with updated help text.
- Server API: create / wake / from-checkpoint / setTimeout endpoints stop
  coercing `timeout == 0` to 300 and pass 0 through to the router, which
  already handles `timeout == 0` as "no auto-hibernate timer".
- Worker gRPC: CreateSandbox / ForkFromCheckpoint / WakeSandbox paths do
  the same, so 0 flows through multi-worker setups too.
- setTimeout endpoint now accepts 0; only negative values are rejected.

Negative values are normalized to 0 (persistent) for safety.
@motatoes
docs: add sandboxes/timeout page
5f448f7 
Explains the new default (persistent, `timeout=0`), how to opt into
auto-hibernate, idle-based semantics, that hibernation snapshots the VM
and costs nothing, and that any SDK operation transparently wakes a
hibernated sandbox. Added to the Sandboxes group in mint.json.
@mintlify
Copy link
Copy Markdown

mintlify bot commented Apr 14, 2026 •
edited
Loading

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
opencomputer 🟢 Ready View Preview Apr 14, 2026, 3:09 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

@vercel
Copy link
Copy Markdown

vercel bot commented Apr 14, 2026

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

Project Deployment Actions Updated (UTC)
opensandbox Ready Ready Preview, Comment Apr 14, 2026 3:08am

Request Review

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@motatoes