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.