Files and artifacts

A live file belongs to the Environment. An Artifact is a stored copy of a deliverable from a completed Turn. Updating the live file later does not change an existing Artifact.

Available on the Rebyte API: shared Environments add explicit file sharing and per-Session output directories. The shared behavior below is available on the public API.

Supply input files

Include base64-encoded inline files when creating the Environment:

const environment = {
  type: 'openai_hosted',
  files: [{
    type: 'inline', path: '/workspace/notes.txt',
    data: Buffer.from('Summarize these notes.').toString('base64'),
  }],
};

Use the Environment files endpoint to write additional inline files or list live files. Upload requests use inline bytes; references to an external Files API are not supported.

Files remain in the Environment. Using the same saved Agent does not share them. With explicit sharing, Sessions referencing the same Environment can read and change the same live files.

Read documents and images

Hosted Sessions include two file tools automatically. list_files returns registered uploads with their Environment file IDs, paths and sizes. The agent calls read_file with one of those IDs to inspect a document or image. This interface is shared across models; applications do not need to parse documents themselves.

// These are agent tool arguments, not separate SDK methods.
// Read the first PDF page as text:
{ file_id: 'file_...', page: 1, offset: 0, view: 'text' }
// Inspect a scanned page or chart visually:
{ file_id: 'file_...', page: 1, view: 'image' }

read_file supports PDF, DOC, DOCX, UTF-8 TXT/Markdown/CSV/JSON and JPEG/PNG/WebP/GIF, up to 10 MiB per file. Text results include next_offset for chunks of at most 20,000 UTF-16 code units. PDF results include page and total_pages; request the next page explicitly. Word extraction includes body text and notes, without embedded images or layout.

Images and rendered PDF pages become typed visual content. Rebyte translates their base64 data URLs into the selected model's provider protocol. Merely returning base64 text would not supply image input. The selected model must still support vision; Rebyte does not switch models or run a separate OCR model. Images use their first frame and are normalized to JPEG at up to 1600 pixels per side. Original environment files remain unchanged.

Parsing runs in a disposable process with a 30 second deadline. Unsupported, damaged, encrypted or overly complex files return tool errors. File contents are untrusted reference data and must not override the agent's instructions.

The Session resource's environment.files contains registered file IDs. Additional uploads also return an id; overwriting a registered path retains that ID. IDs are scoped to the Environment. In the shared preview, another Session attached to that same Environment can use them; Sessions on different Environments cannot. list_files accepts an offset and returns next_offset for lists longer than 100 files; generated workspace files remain accessible through the existing environment and shell tools.

Produce Artifacts

Private inline Sessions publish deliverables from /workspace/outputs. In the shared preview, instruct the Agent to use $REBYTE_OUTPUT_DIR, supplied to every shell command alongside REBYTE_SESSION_ID. At Turn completion, Rebyte copies files from that Session's output directory into private storage and exposes them as Session Artifacts.

These directories prevent accidental cross-publication; they are not filesystem access controls. A private Environment retains its existing output collection behavior, including any existing sessions/ subtree.

const artifacts = await client.beta.agents.sessions.artifacts.list(sessionId);
for (const artifact of artifacts.data) {
  const content = await client.beta.agents.sessions.artifacts.content(
    artifact.id, { session_id: sessionId },
  );
  console.log(artifact.path, artifact.size_bytes);
  // Use content.arrayBuffer() for binary files.
  console.log(await content.text());
}

Wait for the Turn outcome before expecting final deliverables. List results support cursor pagination.

Rebyte scans the current contents of the Session's output directory on every completed Turn. A file left there can produce a new Artifact ID in a later Turn even if its bytes are unchanged. path is therefore not an Artifact identity or a deduplication key. Use artifact.id for downloads and turn_id to group deliveries. An older Artifact keeps its original bytes when the live path changes. If your application wants one latest version per path, make that a display policy rather than overwriting stored Artifact records.

Environment file operations enter the lazy Sandbox guard. Creating an Environment configuration with inline files alone does not allocate a VM; the first operation that needs the filesystem does. A text-only Turn does not create a Sandbox merely to scan outputs.

Delete and retain

Deleting an Artifact removes its stored copy, not the live file. Deleting a Session removes its Artifacts and its private Environment. In the shared preview, Session deletion preserves the shared Environment and live files; delete that Environment explicitly after all Sessions detach. Download Artifacts before Session deletion if your application needs those immutable versions. Sharing an Environment does not grant access through another Session's Artifact endpoint.

Artifact reads require organization authorization and the matching Session ID. Current limits are 10 MiB per inline file, 50 MiB per HTTP request and 50 MiB per Artifact. Upload multiple large files through separate requests to stay within the HTTP limit.