feat(sandbox): add server-managed expiration leases
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 8.7k
- Forks
- 1.3k
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 253
Description
Problem Statement
A client that creates a persistent sandbox is currently responsible for eventually deleting it. Process traps handle graceful exits, but a hard process termination, deleted workload pod, node loss, or disconnected orchestrator can leave the logical sandbox and its compute resources running indefinitely.
External reapers can encode expiry in labels and call the gateway later, but every orchestrator must then implement authorization, pagination, race handling, and lifecycle semantics independently. OpenShell should remain the owner of sandbox deletion and provide a first-class bounded lifetime for callers that need it.
Proposed Design
Add an optional server-managed expiration lease to sandbox creation.
CreateSandboxaccepts either an absolute expiration time or bounded TTL. The default remains no expiration for backward compatibility.- The gateway persists the absolute expiry with sandbox metadata and returns it from get/list/watch APIs.
- An authorized renewal operation extends the lease using optimistic concurrency so a stale client cannot shorten or overwrite a newer lease accidentally.
- A gateway lifecycle reconciler selects expired sandboxes and invokes the existing
DeleteSandboxlifecycle path. It must not delete driver resources directly. - Expiration is idempotent, bounded per reconciliation pass, observable through structured lifecycle events, and retried when driver cleanup fails.
- Authorization to renew or remove an expiry follows existing workspace authorization.
- A final re-read or resource-version precondition prevents stale expiry observations from deleting a renewed sandbox.
- Driver-specific orphan cleanup remains responsible for resources that exist after the logical sandbox record is already lost.
The initial API can remain sandbox-scoped. Session-level TTL from #1884 and operator-owned lifecycle from #1719 can build on the same expiration primitive later.
Alternatives Considered
- External label-based reaper. It works without API changes but duplicates lifecycle logic, requires broad administrative access for cross-workspace cleanup, and cannot guarantee consistent semantics across clients.
- Kubernetes TTL or owner references. These are useful for Kubernetes-only deployments but bypass OpenShell's gateway lifecycle and do not cover Docker, Podman, or VM drivers.
- Delete the Task-owned compute resources directly. This can leave gateway state, provider records, and workspace resources inconsistent.
- Model only session expiry through #1884. A sandbox still needs a bounded lifetime when one orchestration invocation maps directly to one sandbox.
Agent Investigation
- Inspected OpenShell
mainat736e431dand latest release v0.0.96. - Reviewed current sandbox protobuf, CLI create options, gateway create/delete handlers, persisted labels, list selectors, workspace authorization, and compute-driver deletion paths.
- Found expiry fields for credentials and SSH sessions, but no sandbox-level TTL or absolute expiration in the create API.
- Reviewed related issues: #1719 discusses possible operator lifecycle fields; #1884 proposes session/conversation TTL; #2352 covers driver resources orphaned after a Podman container disappears. None provides a gateway-owned expiration lease for the current sandbox API.
- Searched open and closed issues for sandbox expiration, TTL, leases, garbage collection, and orphan cleanup. No exact duplicate was found.
Checklist
- I've reviewed existing issues and the architecture docs
- This is a design proposal, not a "please build this" request
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the current sandbox protobuf, CLI create options, gateway create/delete handlers, persisted labels, list selectors, workspace authorization, and compute-driver deletion paths mentioned in the investigation. Map how an optional lease would flow through creation and get/list/watch APIs before defining the reconciler and renewal behavior. Done requires an agreed implementation plan covering authorization, optimistic concurrency, retries, observability, and backward compatibility.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- api, backend, distributed-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100