Architecture
Understand how your application, the managed runtime, and an environment work together.
On this page
The piecesStart without an environmentAdd a managed environmentConfiguration and ownershipReceive progress and resultsYour application submits work. Rebyte runs the agent loop and retains the Session. An optional Environment supplies compute and files. These responsibilities follow the Agents API's public architecture.
The pieces
| Component | Responsibility |
|---|---|
| Agent | Reusable model, instruction and tool configuration. It does not own a Sandbox. |
| Session | Resolved Agent configuration, independent conversation history, Turns and execution state. |
| Harness | Calls the model, executes tools or requests function results, and advances the Session's Turn. Rebyte provides this managed runtime. |
| Environment | Runs commands and holds working files. Each Environment owns one fixed Sandbox. A Session has at most one Environment; explicit references can share it with explicit sharing. |
| Application server | Authenticates requests, submits input, consumes events, and executes application-side function tools. |
Your application
│ input / function results
▼
Rebyte managed runtime ──────► Model
│ │
│ └─────────────────────► Service MCP servers
▼
Environment / Sandbox
├── Commands and working files
├── Environment MCP servers
└── Deliverables → immutable Artifacts
Events, Items, and Artifacts → Your application
Start without an environment
Choose environment: { type: 'none' } for tasks that need a model, service MCP connections, or application functions without a filesystem. Supply initial input when creating this kind of Session.
Your application still receives events and can continue the Session. There is no Sandbox to provision and no environment shell or working files.
Add a managed environment
Choose environment: { type: 'openai_hosted' } when the agent needs to run commands, install dependencies, or produce files. Against Rebyte, this selects Rebyte compute, allocated lazily on the first environment operation.
Configure the Environment's files, packages, skills, setup commands, and network policy when you create the Session. Rebyte runs commands there; your application continues to handle any function tools.
Configuration and ownership
An Agent is reusable configuration. Creating a saved Agent does not provision compute. Creating a Session resolves that configuration and stores a snapshot, including explicit overrides.
Two Sessions created from the same Agent have independent conversation state. Inline openai_hosted configuration creates a separate Environment for each Session. The shared Environment API also lets a new Session reference an existing Environment. The HTTP API and SDK 0.6.0 npm package are available. Updating the saved Agent affects future Sessions. Existing Sessions keep their resolved configuration.
Working files belong to the Environment and persist across Turns and Sandbox pause/resume. Completed deliverables are copied into Session/Turn-scoped immutable Artifacts. Deleting a saved Agent does not delete existing Sessions. Session deletion removes its Artifacts and its private Environment. In the shared preview, deletion removes the Session's attachment and Artifacts while preserving the shared Environment; explicit Environment deletion is required after all Sessions detach. Shared stdio MCP processes can remain alive, while HTTP MCP cleanup can affect reused upstream connections.
Rebyte checks Environment ownership against the authenticated organization. Developers decide which application users share compute and coordinate files, processes, MCP configurations and cleanup. Separate Session histories do not isolate resources inside a shared Sandbox. See the developer responsibility boundary.
Receive progress and results
Use live streaming for progress and the Items, Turns, and Artifacts endpoints for durable results. The application must return results for function calls before the waiting Turn can continue.
Rebyte provides one managed Sandbox for compute — there is no self-hosted or customer-supplied alternative. Webhooks deliver signed lifecycle notifications; Multi-agent execution is not implemented. Rebyte owns the agent loop. The Sandbox uses Codex exec-server as its command/process executor; it does not delegate the managed model loop to OpenAI.