Skip to content

Add sandbox template support across Python and Node SDKs - #12

Merged
aniketmaurya merged 4 commits into
mainfrom
codex/update-sdk-for-sandbox-templates
Jun 7, 2026
Merged

Add sandbox template support across Python and Node SDKs#12
aniketmaurya merged 4 commits into
mainfrom
codex/update-sdk-for-sandbox-templates

Conversation

@aniketmaurya

@aniketmaurya aniketmaurya commented Jun 7, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • Add template-aware computer creation to the Python and Node SDKs, including template_id / templateId, template_version, and disk_size_mb / diskSizeMb support.
  • Stop hardcoding create-time defaults so the backend can apply template defaults, and add template listing helpers in both clients.
  • Update the Python CLI, OpenAI Agents hosted integration, docs, and SDK tests to reflect the new computer and template contract.

Testing

  • uv run ruff check .
  • uv run pytest
  • npm run lint
  • npm test

Summary by CodeRabbit

Release Notes

  • New Features

    • Added template-based computer creation with template selection and optional version pinning
    • Added ability to list available sandbox templates and their default resources
    • Added disk size configuration support for computers
    • New computer status states: "restoring" and "restorable"
  • Documentation

    • Updated examples across README files to use template-based creation workflow

@coderabbitai

coderabbitai Bot commented Jun 7, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Warning

Review limit reached

@aniketmaurya, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 22 minutes and 44 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 12b114f1-50d5-4a3b-878b-eeda87ff7088

📥 Commits

Reviewing files that changed from the base of the PR and between 54ff5dc and 5eabe3f.

📒 Files selected for processing (8)
  • AGENTS.md
  • README.md
  • js/README.md
  • js/src/computers/client.ts
  • js/tests/computers.test.ts
  • src/celesto/computer.py
  • src/celesto/integrations/openai_agents/hosted.py
  • src/celesto/sdk/client.py
📝 Walkthrough

Walkthrough

This PR introduces sandbox template support across the Celesto SDK. Computer creation now uses template_id selection with optional disk sizing instead of explicit CPU/memory inputs. New SandboxTemplateInfo types and listTemplates() methods enable template discovery. The CLI gains --template flags and a new templates subcommand. OpenAI Agents integration forwards template parameters during provisioning. Comprehensive tests validate request/response contracts and alias conflict rejection.

Changes

Sandbox Template Support

Layer / File(s) Summary
Type System: New Template Types and Extended Computer Metadata
js/src/computers/types.ts, src/celesto/sdk/types.py
SandboxTemplateInfo interface introduced with template defaults and experimental flag. ComputerStatus gains "restoring" and "restorable" states. ComputerInfo expands with diskSizeMb, templateId, templateVersion. CreateComputerParams refactored to support CPU/RAM aliases (cpus/vcpus, memory/ramMb) and template targeting.
SDK Core: Refactored create() with Templates and Alias Validation
src/celesto/sdk/client.py, js/src/computers/client.ts
Both Python and JavaScript Computers.create() now accept optional template and disk parameters with alias consistency validation. New buildCreateComputerBody (JS) and equivalent Python logic rejects conflicting aliases and builds request payloads containing only explicitly provided fields.
SDK Core: Template Discovery via listTemplates()
src/celesto/sdk/client.ts, src/celesto/sdk/client.py
Public listTemplates() method added to Computers client in both SDKs, calling GET /computers/templates endpoint and mapping wire response to SandboxTemplateInfo.
Module Exports: Type Surface Updates
js/src/computers/index.ts, js/src/index.ts, src/celesto/sdk/__init__.py
SandboxTemplateInfo added to public re-exports in all SDK entrypoints.
CLI: Template and Disk Sizing Arguments
src/celesto/computer.py
create_computer command now accepts optional --template, --disk-size-mb, --template-version, --image flags replacing fixed defaults. New "restorable" status added to color mapping.
CLI: New templates Subcommand
src/celesto/computer.py
New celesto computer templates command calls list_templates(), renders table with template id/name, defaults, version, and experimental status; supports --json output.
CLI: Updated list and create Output Formatting
src/celesto/computer.py
create output now shows CPUs, memory, disk size, and template id. list command table gains Disk and Template columns. Minor message formatting adjustments in run and ssh commands.
OpenAI Agents: Template-Driven Sandbox Provisioning
src/celesto/integrations/openai_agents/hosted.py
CelestoSandboxClientOptions and CelestoSandboxSessionState make CPU/memory/image optional and add disk_size_mb, template_id, template_version fields. Provisioning now forwards template parameters to computers.create().
Documentation: Main README Examples
README.md
Python, JavaScript, and CLI quick starts updated to use template_id="coding-agent". Computers API section revised with template example and guidance on omitting resource fields. CLI command table and JSON examples updated.
Documentation: JavaScript README and Template Listing
js/README.md
Quick start and lifecycle examples switch to templateId. New documentation and example showing listTemplates() usage.
Tests: JavaScript Computers Client Coverage
js/tests/computers.test.ts
create() tests verify explicit fields sent, aliases rejected, empty body on no-args. list() and other operation fixtures updated with new wire fields. New listTemplates() test validates endpoint and response mapping.
Tests: Python SDK Behavior Coverage
tests/test_sdk.py
New DummySession HTTP stub enables request capture. Test coverage for create() explicit field forwarding, no-args empty body, conflicting alias rejection, and list_templates() endpoint verification.
Minor Cleanup
tests/test_celestoignore_spec.py
Removed unused tarfile and tempfile imports.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

  • CelestoAI/sdk#5: Prior refactor of Computers.create() mapping for cpus/memoryvcpus/ram_mb that this PR builds upon.
  • CelestoAI/sdk#10: Introduction of CelestoSandboxClientOptions and CelestoSandboxSessionState in OpenAI Agents integration; this PR extends those classes with template parameters.

Poem

By the grace of templates, the old way dies—
No more haggling over CPU skies.
One template_id to rule them all,
Shelby's SDK answers every call. 🎩
Disk and version flow like whiskey neat,
A proper provisioning, tidy and fleet.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 32.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the primary change: introducing sandbox template support across both Python and Node SDKs, which is the main objective reflected throughout the changeset.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/update-sdk-for-sandbox-templates

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@aniketmaurya
aniketmaurya marked this pull request as ready for review June 7, 2026 12:15

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@js/src/computers/client.ts`:
- Around line 107-113: The error messages in buildCreateComputerBody are
misleading: instead of saying "Pass either cpus or vcpus, not both." and
similarly for memory/ramMb, update the validation error text to reflect the
actual rule — allow both when equal but require equality when both provided;
e.g., change the cpus/vcpus error to state that "cpus and vcpus must have the
same value when both are provided" and likewise change the memory/ramMb error to
"memory and ramMb must have the same value when both are provided" so the thrown
Error in buildCreateComputerBody accurately describes the validation.

In `@src/celesto/computer.py`:
- Around line 122-123: The CLI is defaulting missing metadata to misleading
values by using result.get('disk_size_mb', 0) and result.get('template_id',
'scratch') in the console.print lines (and the same pattern later), so change
those prints to detect absence and show a clear "N/A" or omit the field instead
of inventing values: update the console.print calls that use
_format_memory(result.get('disk_size_mb', 0)) and result.get('template_id',
'scratch') to check for the key (e.g., 'disk_size_mb' and 'template_id') on the
result dict and print a neutral placeholder when absent (or skip printing),
leaving _format_memory only for real numeric values. Ensure both occurrences
(the ones around the two reported line groups) are fixed.

In `@src/celesto/integrations/openai_agents/hosted.py`:
- Around line 91-97: The code starts the hosted machine but doesn’t wait for it
to finish booting, causing races; modify the logic around
self._client.computers.get / self._client.computers.start (using
self.state.computer_id) to poll the machine status after calling start until it
becomes "running" (or until a configurable timeout/attempts elapses), sleeping
briefly between polls, and raise/return a clear error if the machine fails to
reach "running" within the timeout; ensure the polling path also handles
transient API errors from get and includes a short backoff.

In `@src/celesto/sdk/client.py`:
- Around line 835-838: Update the validation error messages in the block that
checks cpus/vcpus and memory/ram_mb (where CelestoValidationError is raised) to
state the actual rule: when both values are provided they must be equal. Replace
the current "Pass either cpus or vcpus, not both." with a message like "cpus and
vcpus must have the same value when both are provided." and similarly replace
the memory error message with "memory and ram_mb must have the same value when
both are provided." to match the JS behavior and clarify the true validation
rule.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e153768b-92ec-43a9-85b9-caeb1b78c0a4

📥 Commits

Reviewing files that changed from the base of the PR and between 522c7d9 and 54ff5dc.

📒 Files selected for processing (14)
  • README.md
  • js/README.md
  • js/src/computers/client.ts
  • js/src/computers/index.ts
  • js/src/computers/types.ts
  • js/src/index.ts
  • js/tests/computers.test.ts
  • src/celesto/computer.py
  • src/celesto/integrations/openai_agents/hosted.py
  • src/celesto/sdk/__init__.py
  • src/celesto/sdk/client.py
  • src/celesto/sdk/types.py
  • tests/test_celestoignore_spec.py
  • tests/test_sdk.py
💤 Files with no reviewable changes (1)
  • tests/test_celestoignore_spec.py

Comment thread js/src/computers/client.ts
Comment thread src/celesto/computer.py Outdated
Comment thread src/celesto/integrations/openai_agents/hosted.py
Comment thread src/celesto/sdk/client.py Outdated
@aniketmaurya
aniketmaurya merged commit 9ddd266 into main Jun 7, 2026
7 checks passed
@aniketmaurya
aniketmaurya deleted the codex/update-sdk-for-sandbox-templates branch June 7, 2026 12:53
@mintlify

mintlify Bot commented Jun 7, 2026

Copy link
Copy Markdown

Docs PR opened: CelestoAI/mintlify-docs#100

Documented sandbox templates, the new list templates helper, disk size configuration, and added restoring and restorable statuses.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant