Skip to main content
OAO accepts files on both the initial session request and every later session turn. A file is submitted inline as canonical base64, uploaded byte-for-byte to the project’s default S3-compatible storage provider, integrity-bound to the run by its SHA-256 digest, and copied into the thread’s sandbox before the model runs. PostgreSQL stores only the run manifest and object-storage binding; it does not store attachment bytes or extracted text. The current file input supports:
  • Files declared as text/*, JSON, JSON-LD, NDJSON, XML, YAML, JavaScript, and TypeScript.
  • PNG, JPEG, WebP, and GIF images.
  • PDF and RTF documents.
  • Microsoft Word .doc, .dot, .docx, .docm, .dotx, and .dotm.
  • Microsoft Excel .xls, .xlt, .xla, .xlsx, .xlsm, .xlsb, .xlam, .xltx, and .xltm.
  • Microsoft PowerPoint .ppt, .pot, .pps, .pptx, .pptm, .ppsx, .ppsm, .potx, and .potm.
  • Zipped and flat OpenDocument text, spreadsheet, presentation, drawing, template, and formula variants: .odt, .ott, .fodt, .ods, .ots, .fods, .odp, .otp, .fodp, .odg, .otg, .fodg, and .odf.
  • Apple iWork .pages, .numbers, and .key documents.
  • RFC 822 .eml and Outlook .msg email files.
  • Up to 8 files per turn, 10 MiB per file, and 20 MiB combined.
OAO does not decode, extract, OCR, summarize, or otherwise preprocess file contents. A malformed, encrypted, password-protected, or text-free document is still admitted as raw bytes; the agent’s sandbox tools decide how to inspect it. Standalone archives, audio, video, executables, Microsoft Access/Publisher/OneNote/Visio/Project files, and other arbitrary binaries remain unsupported by the upload contract. The selected agent version must enable a sandbox. Text inputs require either filesystem_read or shell; binary inputs require shell. Choose a Daytona snapshot with the software needed for the formats the agent will receive. New sandbox-enabled agent versions cannot be published without selecting an active snapshot returned by Daytona. OAO does not substitute or build an image. The project must also have a default S3-compatible storage provider. OAO rejects a file submission before queueing the run when object storage or its credential-encryption configuration is unavailable. Message-only runs do not require object storage.

API file contract

Each item in files has this shape:
name is a plain filename, not a path, and must be unique within the message. The API normalizes the media type, verifies that known document extensions and declared types agree, computes the digest itself, and never accepts a caller-supplied storage reference or checksum as proof of content. It does not parse the bytes. application/octet-stream is accepted for a recognized document extension and normalized from that extension.

Start a session with files

Encode files on a trusted server and send them with initialMessage:
The equivalent JSON request is:
initialMessage may be omitted when at least one file is present. OAO then records a neutral Review the attached file(s). user message.

Continue a session with files

Use the same file contract after the latest run settles:
The same files field is accepted by POST /projects/{projectId}/sessions/{sessionId}/runs and POST /projects/{projectId}/runs/{runId}/resume. A turn may contain only files.

Inspect an Excel file with pandas

The runtime places every file under a deterministic per-run path. An agent with the shell capability can use pandas directly:
The model receives the exact path, filename, content type, byte size, and SHA-256. It does not receive a parsed preview, so reading the file produces a normal visible read or bash tool call.

Use the console

In Sessions, select Create session and choose files under Files before submitting. On an existing settled session, use Attach files under the message composer. Both surfaces share the same attachment control: pick files with Choose files or drag and drop them onto it, review the listed names and sizes, and remove any file before sending. Selected files are read in the browser and sent through the authenticated API request; the browser never receives an S3 credential. The transcript shows the filename, normalized content type, and size next to the user message. It never returns the stored base64 or raw bytes. If the selected agent lacks the required sandbox capability, the API rejects the run before queueing it. The session sidebar lists each uploaded attachment from the run’s durable manifest. After a successful workspace backup it shows Uploaded + backed up when the exact sandbox path is also present in the archive’s object-storage manifest. This is an authoritative path comparison rather than an inference from shell command text. Every Backed up file also has a download action. It calls the authenticated session Files API, not Daytona and not a provider-specific public URL. The API reads the latest verified workspace archive from the persistent storage provider bound to that workspace.

Retrieve model-created files

For the complete list, download, authentication, and error contracts, see the dedicated Files API reference. Ask the model to return the relative path of the file it created, for example output/result.csv. After the run completes and its workspace backup succeeds, the caller can use the known session ID:
The route is GET /projects/{projectId}/sessions/{sessionId}/files/{relativePath} and requires session:read. The session, its shared workspace owner, and the storage-provider object are resolved inside the caller’s organization and project. The API verifies the persistent archive and streams the requested regular file without writing it to the API host filesystem. It never reaches back into the live or stopped Daytona sandbox.

Runtime and event behavior

Before the first model turn, the runtime downloads the original object from the storage provider bound at upload time, verifies its content type, size, and SHA-256, and writes it to .oao/attachments/{runId}/{filename} relative to the sandbox’s writable working directory. Re-running the same intake hook safely overwrites the same path with the same verified bytes. Later turns use their own run directory, while earlier attachment paths remain available in the persistent thread workspace. The model-visible message contains only paths and safe metadata. The runtime does not read the files on the model’s behalf. The agent must call its sandbox tools, so those reads and commands appear in the normal tool timeline. File bytes are not copied into PostgreSQL, runs.inputPublic, product events, SSE, audit details, or ordinary transcript responses. The run manifest contains only IDs, the bound storage provider and logical object key, safe metadata, size, and SHA-256. Consume the normal resumable project event stream and re-fetch the session when a relevant message or run event arrives.
Treat every uploaded file as untrusted user input. OAO does not execute it, but a shell-capable agent can choose tools that do. Agent instructions should inspect data files without executing embedded macros, scripts, or binaries, and must never let file content override execution-time authorization.