Shared environments

Available on the public API since October 15, 2026. SDK 0.6.0 provides typed methods as a source preview. npm publication is pending; published 0.3.0 packages do not include these methods. You can use the HTTP API directly without installing the preview package.

A Session owns its Agent configuration, conversation history and Turns. An Environment owns one fixed Sandbox, working files and setup configuration. Multiple Sessions can explicitly reference that Environment.

Session A: history, Turns, Artifacts ──┐
                                     ├── Environment → one Sandbox and shared files
Session B: history, Turns, Artifacts ──┘

Using the same saved Agent does not share compute. Sharing requires an explicit Environment reference and does not create a parent/child agent relationship. Native Multi-agent orchestration remains unsupported.

Developer responsibility

This API gives your application control over shared compute. Rebyte authenticates your organization key, checks its scopes and verifies that each Environment belongs to that organization. The organization comes from the validated key. Supplying an Environment ID from another organization returns 404; knowing the ID does not grant access.

Every Session on the Environment can access its files, processes and VM-visible credentials. The API does not prevent shared-file overwrites, conflicting services or one program stopping another. Your application chooses and manages those effects. Separate histories and output directories are not VM isolation.

Choose how to create a Session

An existing Environment ID is optional:

Only the reference form shares an existing Environment. The attachment is fixed when the Session is created. To use a different Environment, create a new Session.

HTTP example

Create a standalone Environment, then attach two Sessions with the returned ID. Use an organization API key with tasks:write and tasks:read:

curl https://api.rebyte.ai/v1/agents/environments \
  -H "Authorization: Bearer $REBYTE_API_KEY" \
  -H 'OpenAI-Beta: agents=v1' -H 'Content-Type: application/json' \
  -d '{"environment":{"type":"openai_hosted"}}'

# Set ENVIRONMENT_ID to the returned id. Run this request for each Session.
curl https://api.rebyte.ai/v1/agents/sessions \
  -H "Authorization: Bearer $REBYTE_API_KEY" \
  -H 'OpenAI-Beta: agents=v1' -H 'Content-Type: application/json' \
  -d "{\"agent\":{\"model\":\"gpt-6-luna\"},\"environment\":{\"type\":\"reference\",\"environment_id\":\"$ENVIRONMENT_ID\"}}"

Delete each Session, then explicitly delete the Environment when finished: DELETE /v1/agents/sessions/{session_id} followed by DELETE /v1/agents/environments/{environment_id}.

Create a Session that shares compute

Build the v0.6.0 tag in rebyte-agent-sdk. The official openai Session input type does not include Rebyte's reference variant; use rebyte.sessions.create for it.

import OpenAI from 'openai';
import { RebyteExtensions } from '@rebyteai/agent-extensions';

const client = new OpenAI({
  apiKey: process.env.REBYTE_API_KEY,
  baseURL: 'https://api.rebyte.ai/v1',
  maxRetries: 0,
});
const rebyte = new RebyteExtensions(client);

const main = await rebyte.sessions.create({
  agent: { model: 'gpt-6-luna', instructions: 'Coordinate the assigned work.' },
  environment: { type: 'openai_hosted' },
});
if (main.environment.type !== 'openai_hosted') throw new Error('Expected a managed Environment');
const environmentId = main.environment.id;

const helper = await rebyte.sessions.create({
  agent: { model: 'gpt-6-luna', instructions: 'Investigate the assigned question.' },
  environment: { type: 'reference', environment_id: environmentId },
});

The response contains the resolved openai_hosted Environment, with the same id in both Sessions. Send input and read results through each Session's normal events, Turns and Items endpoints. Your application supplies the helper's task and passes its findings back; Rebyte does not copy the main Session's history.

A reference contains only type and environment_id. It cannot override files, packages, setup commands, Skills, network policy or environment credentials. The attachment is fixed at Session creation; an existing Session cannot switch Environments.

Create an Environment before creating Sessions

const environment = await rebyte.environments.create({
  environment: {
    type: 'openai_hosted',
    files: [{
      type: 'inline', path: '/workspace/input.txt',
      data: Buffer.from('Shared input').toString('base64'),
    }],
  },
});

Use environment.id in later Session references. Creation returns 201 with an agent.environment resource and status: 'pending'. It reserves identity and configuration without starting compute. The first environment operation initializes the Sandbox once, even when multiple attached Sessions need it concurrently. Setup does not repeat when another Session attaches or the Sandbox resumes.

Retrieve and file methods reuse the official client. Create/delete and Session references are Rebyte extensions. Raw HTTP requests need the organization key and OpenAI-Beta: agents=v1 header. Store the Environment ID in your application; this change adds no Environment list endpoint.

Lifetime and cleanup

The first reference permanently changes a private Environment to shared lifetime. It does not become private again when only one Session remains. Deleting the last Session also leaves it available through the Environment endpoints.

For the two Sessions created above, cleanup is explicit:

await rebyte.sessions.delete(main.id);
// helper still uses the same Environment and files.
await rebyte.sessions.delete(helper.id);
await rebyte.environments.delete(environmentId);

Environment deletion returns { id, object: 'agent.environment.deleted', deleted: true }. Deleting a saved Agent does not delete Sessions or Environments. Stdio MCP and other background processes in a shared Environment can outlive Session deletion. Deleting a Session also attempts to terminate its initialized HTTP MCP connections; cleanup of a reused environment-origin connection can affect other Sessions. Your application coordinates service and Environment cleanup.

MCP names and reuse

Environment-origin MCP servers, including stdio and environment-origin HTTP, share a server_label namespace within the Sandbox. The first configuration to start a live broker selects its command, process environment or HTTP endpoint and headers. A later Session using the same label connects to that broker; it does not replace the running service with its own configuration.

For example, A starts reader configured to return A. B references the same Environment and configures reader to return B. B can receive A from the already-running service. Rebyte does not compare these configurations, reject the conflict or isolate B's server. Incompatible definitions can also cause errors. Concurrent first startup does not guarantee which configuration wins.

Your application owns that choice. Use different labels for different managed MCP services, and separate Environments when you need separate compute. Different labels still share the Sandbox's files, ports and credentials.

Deleting a Session leaves its stdio MCP process running if the process and shared Environment are still alive. That process retains its launch-time credentials. Stop it explicitly when needed, or delete the Environment after all Sessions detach. A dead established broker is not automatically restarted with a later Session's configuration. HTTP MCP cleanup can terminate the upstream connection used by peers sharing the same broker.

Service-origin HTTP MCP runs outside the Sandbox and does not use this namespace. Sharing an Environment alone does not merge those Session connections or their authentication. See MCP connections.

Cancellation and recovery

Turn cancellation requests that the active Turn and its in-flight tool work stop. It does not delete the shared Sandbox, undo writes or external side effects, or guarantee that background processes from earlier calls stop. Code and services can still affect other tasks sharing the Environment.

Initialization belongs to the Environment, using its ID allocated at creation. All attached Sessions and direct file requests join the same initialization. Cancelling the Turn that first requested setup stops that Turn's wait; setup continues, even if provisioning has not started yet. Other Sessions can continue waiting and use the same Sandbox when it is ready. The cancelled Session can submit another Turn against that Environment. A direct file operation can also initialize the Environment before submitting Turns.

If initialization itself fails, Rebyte records the failure and preserves the original identity. There is no reset or rebind API in this preview. Your application can inspect the failure, delete its attached Sessions, explicitly delete the unused Environment when allowed, and create a new Environment and Sessions. Rebyte does not automatically discard the old files or choose a replacement for you.

Files, outputs and credentials

Live files and registered file IDs belong to the Environment. All attached Sessions see the same environment.files metadata. Coordinate writes to shared paths in your application; the filesystem does not merge concurrent edits.

Use $REBYTE_OUTPUT_DIR for deliverables. Shell commands receive this variable and REBYTE_SESSION_ID from Rebyte. The original inline owner uses /workspace/outputs; referencing Sessions use /workspace/outputs/sessions/<session_id>. Every Session on a standalone Environment uses its own subdirectory. Once sharing begins, the original owner's collector excludes the reserved sessions/ subtree. Existing private output collection remains unchanged.

Each Session publishes its own directory into its Session/Turn-scoped Artifact store. Shared files do not grant access through another Session's Artifact endpoint. See Files and artifacts.

Sessions sharing a Sandbox share a trust boundary. They can access the same files, processes and VM-visible credentials. Output directories prevent accidental publication; they are not filesystem permissions. Share only between tasks and users that may access those resources.

Environment setup and its Vault selection belong to the Environment. A referencing Session's vault_ids does not replace the Environment's credential selection. Service-origin MCP configuration and conversation history remain Session-owned. Organization ownership is checked on every Environment operation; your application must enforce end-user access before using its organization key.

Errors and current limits

Pending Environments accept references before initialization begins. If setup is already running, wait for it to finish before creating another Session. Existing attached Sessions join the same initialization operation. A setup or connection failure preserves the original Sandbox binding; it does not create a replacement. Do not blindly retry Session or Environment creation after an ambiguous timeout; these creation operations do not provide idempotency guarantees.

This preview adds references to model Session creation only. Workflow Agent and Schedule definitions retain their existing none / openai_hosted inputs. It does not add native subagent spawn, wait, result delivery, shared conversation history, or a self-hosted Sandbox attachment API.