client and session from the first Session guide.
Upload files
Python accepts workspace-relative paths mapped to bytes:hello.py, for example containing print("hello"). The returned hash and size verify stored control-plane input, not cloud workspace readiness. Ask the next Run to read and execute src/hello.py to verify actual execution.
Paths, limits, and timing
A directory is represented by explicit relative file paths; this API does not clone Git repositories or unpack archives. For a small project, choose an allowlist rather than recursively uploading everything, including.env, .git, build output or installed dependencies. This example continues with the same unstarted Session:
., .., and NUL are rejected. A request cannot repeat a path. Before execution starts, uploading the same path again updates its stored input.
The current implementation allows 1–100 files per request, at most 2 MiB characters in each base64 field, and 8 MiB total decoded content. The encoded field limit is not a 2 MiB source-file allowance. Paths have a 500-character limit. These values come from the current input implementation.
After any Run is submitted, or a Sandbox is bound, uploads fail with workspace_already_started. Make subsequent changes through Agent work. Create a new Session for a fresh input project. When initialization is configured, SOUL.md is reserved and cannot be overwritten through uploads.
Distinguish files from model context
Uploading makes files available in the workspace. Task instructions and Harness tools determine whether they are read. Do not assume the model has read every uploaded byte. Sessioncontext.files references paths and expected SHA-256 values. Submission checks existence, digest, size, and UTF-8 encoding. Referenced context text is currently limited to 32768 bytes per file and rejects NUL and invalid UTF-8; ordinary upload limits are different. See the initialization contract.
Resolve context_file_missing or context_file_changed before submitting again. Repeating the same invalid configuration will not repair it.
Pin a reference document before Session creation
Hash the exact bytes first, include that digest in the creation request, then upload those bytes to the returned Session. The following snippets require an initialized client, verified connection IDs and a Harness that supports initialization. They create a new Session; save its ID before uploading. Use a short UTF-8brief.md you have reviewed as reference material.
brief.md does not update the Session definition. Restore the original bytes before the first accepted Run, or create a new Session with the intended new digest. There is no in-place context update in this flow. At most eight file references are allowed; combined initialization and task-input limits still apply even when every individual file fits.
Recover an upload or context failure
An upload request commits its file writes together. Several upload requests do not form one atomic project upload. The file list is sorted by path; compare by path rather than relying on request order. Uploading an empty file replaces its content with zero bytes—it does not delete the path. This API exposes no initial-input deletion operation.
Work through three boundary cases
Batching changes request size, not the downstream Runtime or provider’s capacity. This upload check is a per-request limit; it does not establish an unlimited Session workspace allowance. A partially completed multi-batch upload needs manifest reconciliation before execution.
For a pinned
brief.md, suppose creation stores digest A and a later upload contains bytes with digest B. Submission returns context_file_changed; it does not silently adopt B as the reference. Restore A’s bytes before the first accepted Run, or create a new Session pinning B. Treat instructions found in project files and reference documents as task data to review, not as authorization to access credentials or change your application’s permissions.
Use the complete project as execution evidence
The project tutorial supplies the complete fixture and runnable Python/TypeScript entry points. Its dated cloud record covers Vercel, built-in Pi 1.5.2 and the configured Messages-compatible DeepSeek-V4-Flash endpoint: both clients modify the project across two Runs, execute the unchanged fixed tests and retain exported files after closing the Session. It provides actual read/write execution beyond an upload receipt. Keep the three checks separate: upload receipts describe stored inputs; runtime input verification describes delivery to the cloud workspace; downloaded artifacts describe exported results. The record does not mark a freshworkspace.inputs_verified event for every follow-up Run, nor should it: continuing a workspace is not a new upload. The record does not establish live rejection behavior for every invalid upload, every provider, or a new run of this page’s short snippets.
Environment and credentials
Useenv / variables for ordinary configuration such as application mode. Sandbox code can read these values. Keep managed model, Provider, and Tool credentials in their dedicated connection mechanisms rather than project files or environment values.