Sandbox lifecycle

An Environment owns one fixed Sandbox identity. Inline openai_hosted creation initially gives it a private Session lifetime.

Available on the Rebyte API: shared Environments let multiple independent Sessions attach to that identity and add standalone Environment creation/deletion. Shared behavior is available on the public API.

Provisioning

Rebyte records Environment configuration and reserves its binding at inline Session creation or, with explicit sharing, standalone Environment creation. It does not allocate a Sandbox yet. The first environment tool, file operation, or environment-origin MCP operation enters a guard that initializes its Sandbox, packages, files, setup commands and Skills. With explicit sharing, initialization is coordinated by Environment ID, so concurrent attached Sessions initialize it once. Creating a saved Agent or merely sending a chat message does not allocate compute.

Retrieve the Session and its Environment to inspect state. The Environment resource is available at GET /v1/agents/environments/{environment_id}. Failed initialization is reported on the Session.

Persistence

Working files persist across Turns on the same Environment. Inline environments remain separate even when Sessions use the same Agent. Explicit references with explicit sharing share the live filesystem and registered file IDs; conversation history remains separate. A reference cannot change setup configuration or trigger another setup run.

When a Sandbox pauses, later connection resumes the same Sandbox. Initialization and Skill installation do not repeat on resume. A connection error does not replace the environment or discard its files. Applications should surface the failure and retain the Session and Environment IDs for diagnosis.

Ending a Turn

Completion, failure, and cancellation end a Turn without deleting the Session. A Session whose initialization succeeded can accept subsequent input. Disconnecting from the event stream also leaves execution running.

Cancellation does not undo side effects or guarantee termination of background processes returned by earlier calls. In the shared preview, initialization belongs to the Environment. Cancelling a waiting Turn leaves setup running for peers, including when provisioning has not started yet. See cancellation and recovery for cancellation behavior and explicit recovery after initialization failure.

Deliverables are published as immutable Artifacts when a Turn completes. Private inline Sessions retain /workspace/outputs. The shared preview supplies a per-Session $REBYTE_OUTPUT_DIR and keeps publication scoped to that Session. See Files and artifacts.

Deletion

Session deletion removes its stored Artifacts. If its inline Environment has never been shared, deletion also removes that Environment and Sandbox.

With explicit sharing, the first reference permanently gives the Environment shared lifetime. Session deletion removes its attachment and Artifacts while preserving shared compute, including when the last Session is deleted. Stdio MCP processes can remain alive; initialized HTTP MCP cleanup still runs and can affect a reused upstream connection. The developer coordinates these effects. Delete all attached Sessions before calling DELETE /v1/agents/environments/{environment_id}; active bindings return 409 environment_in_use. Initialization must finish before explicit deletion. Deleting a saved Agent does not delete existing Sessions or Environments.

See shared lifetime and cleanup for the SDK calls and failure cases.