Skip to content

What's new in 0.9.0

Published on 2026-10-07: Python SDK rayito 0.9.0, TypeScript SDK rayito 0.9.0 and rayd 0.9.0.

0.9.0 is a cleanup and fixes release. It removes what was not worth maintaining (the agent fast-start option D and some gateway exceptions that nothing raised), lets another process use a sandbox's agent with Sandbox.connect() and aligns the Python SDK with the TypeScript one on the AWS region. There are no new features with a cost and no new AWS calls.

There are breaking changes, all with their migration in How to upgrade from 0.8.x.

At a glance

Change Python TypeScript Type
Option D is removed (pool with a resident opencode serve) serve=, attach=, RunRequest.attach serve, attach, RunRequest.attach breaking
The gateway exceptions that were never raised are removed GatewayException GatewayError, GatewayErrorOptions breaking
The E2B shim's BuildException and TemplateException are the native ones rayito.e2b.BuildException, rayito.e2b.TemplateException — breaking
AWS_REGION wins over AWS_DEFAULT_REGION and the profile the whole SDK already did fix that changes behavior
connect() recovers sbx.gateways Sandbox.connect(), AsyncSandbox.connect() Sandbox.connect() fix

Breaking changes

The agent fast-start option D is removed

The pool with a resident opencode serve disappears with no deprecation period: it barely gained a few tenths over option C and cost more memory and more per slot. The following disappear:

  • Python: agent_pool_warmup(..., serve=), sbx.agent.prepare(serve=), attach= of sbx.agent.run()/stream() (sync and async) and RunRequest.attach.
  • TypeScript: the serve option of agentPoolWarmup() and of sbx.agent.prepare(), attach of AgentRunOptions and RunRequest.attach.
  • The rayito.agent.run span stops carrying rayito.agent.attached, and OPENCODE_SERVE_PORT disappears.
  • For those who write their own runtime: the AgentRuntime port loses abort_command / abortCommand (no runtime used it anymore) and warmup_steps() / warmupSteps() no longer takes arguments.

Migration: remove serve=True and attach=. For a fast first message use agent_pool_warmup(runtime) / agentPoolWarmup(runtime) (option C) or the normal start (Sandbox.create(...) and sbx.agent.run(...)); the What do I use? table compares the remaining options. A custom runtime deletes abort_command and the warmup_steps parameter.

GatewayException and GatewayError are removed

They were never raised. What the secret gateway rejects per request reaches the sandbox process as an HTTP response (403, 429, 502, 504), and a configuration that rayd rejects is SandboxException / SandboxError. In TypeScript GatewayErrorOptions also disappears.

Migration: remove the import and any except GatewayException or instanceof GatewayError. If you were catching gateway failures on creation or refresh, catch SandboxException / SandboxError (Errors).

Python: the E2B shim's BuildException and TemplateException

rayito.e2b.BuildException and rayito.e2b.TemplateException were the shim's own classes that nothing raised, so except rayito.e2b.BuildException did not catch a failed Template.build(). They are now rayito.BuildException and rayito.TemplateException.

Migration: except rayito.e2b.BuildException now catches real failed builds. Keep two differences with E2B in mind:

  • BuildException inherits from SandboxException (in E2B it inherits from Exception): isinstance/issubclass checks that assumed the opposite change.
  • It has the native constructor, BuildException(message, *, reason=..., step=..., command=..., exit_code=..., log_tail=...): code that raises or inherits it must pass a single message; BuildException() or BuildException(a, b) fail with TypeError.

Python: AWS_REGION wins over AWS_DEFAULT_REGION and the profile

Before, boto3 only read AWS_DEFAULT_REGION or the profile's region, and the Python SDK ignored AWS_REGION, unlike the TypeScript one and the CLI. Now every boto3 session of the SDK (control plane, S3 staging, secrets, DynamoDB index, events, EFS, CloudFormation...) resolves the region in a single place with this priority:

region= > caller's session > AWS_REGION > AWS_DEFAULT_REGION > profile

A caller's session without a region follows that same chain. Anyone who only exports AWS_DEFAULT_REGION notices no change.

Migration: if you export AWS_REGION with a value different from AWS_DEFAULT_REGION or from your profile's region, the SDK starts operating in AWS_REGION's region. To keep the previous one, remove AWS_REGION from the environment or pass an explicit region=.

Fixes

  • connect() recovers sbx.gateways (Python sync and async, and TypeScript). Another process (a worker, an API, a scheduled task) can now use sbx.agent on a sandbox created with gateways= without recreating it: connect() reads rayd's ConfigureStatus once (name, port and last error of each route; never the upstream or the headers). On a recovered handle, refresh() only rereads the state; rotating the key remains the job of the handle that called create(gateways=), and on a recovered one reincarnate() raises. If rayd rejects the access token on that read, connect() does not fail: the error surfaces on the first authenticated call, as before (Using the agent from another process).
  • Docstrings, TSDoc, CLI help and messages aligned with the documentation: exceptions without a docstring now have one, the codes of MountException / MountError and AgentException / AgentError say what really happens, reincarnate() lists everything it reapplies, and the no-region errors of the index and of Template.build ask for AWS_REGION.
  • rayito doctor knows the 0.9 series: it requires the rayd from the rayd-v0.9.0 tag for SDK 0.9 (Compatibility).

rayd 0.9.0: no changes in the agent. Recovering sbx.gateways uses the ConfigureStatus that already existed, and the version goes up in step with the SDKs.

How to upgrade from 0.8.x

  1. Upgrade the SDK.

    pip install -U "rayito[cli]"

    pnpm add rayito@latest

  2. Republish your image on rayd 0.9.0 (Images). The compatibility series moves to 0.9: rayito doctor requires the rayd from the rayd-v0.9.0 tag for SDK 0.9 and gives FAIL on the compatibility check with a 0.8 image. If you use the agent, also rebuild its image with AgentTemplate or rayito agent template build.

  3. Review the breaking changes:
What Up to 0.8.x Since 0.9.0
serve= / serve in agent_pool_warmup() and prepare(), attach= / attach in run()/stream(), RunRequest.attach option D: a resident opencode serve in each pool slot TypeError / type errors; use option C (agent_pool_warmup(runtime))
GatewayException (Python), GatewayError and GatewayErrorOptions (TypeScript) exported, never raised they do not exist; catch SandboxException / SandboxError
rayito.e2b.BuildException / TemplateException (Python) the shim's own classes that nothing raised the native ones; BuildException is a SandboxException with the native constructor
AWS_REGION different from AWS_DEFAULT_REGION or from the profile (Python) ignored wins; pass region= to pin another one

Outside those rows, there are no incompatible changes in the public API from 0.8.x.