Skip to main content
Upload project inputs before the first Run. Uploaded files become workspace inputs; they are not automatically complete model context or exported artifacts. Create a Session with no submitted Runs first. The snippets below continue with an initialized client and session from the first Session guide.

Upload files

Python accepts workspace-relative paths mapped to bytes:
TypeScript accepts base64-encoded file entries:
Prepare a local 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:
This two-file selection demonstrates path preservation, not a complete runnable project. Use the project task tutorial and its complete fixture for the read/modify/test/export journey. Empty directories, symlink identities and executable modes have no fields in this upload contract. Reading a local symlink with the filesystem calls above follows its target; inspect your allowlist before reading it. Paths must be relative. Absolute paths, backslashes, empty segments, ., .., 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. Session context.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-8 brief.md you have reviewed as reference material.
These are alternative snippets, not code to append to the earlier Session example. Submit through the durable backend flow. The reference digest is pinned: uploading a changed 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 fresh workspace.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

Use env / 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.

Verify completion

Check stored input hashes, prove that a real Run can read the file and execute a fixed check, then explicitly export and download required deliverables. Stored inputs, live workspace files, and final artifacts are separate verification targets. Retain the Session ID on failure. Correct invalid input paths before execution; uploads cannot overwrite a started workspace. Explicitly close unused Sessions and confirm cleanup. Next: Continue across turns, export artifacts, understand persistence. Review scope: the local review record covers source inspection, schema rejection cases and snippet syntax/transpilation. It does not execute PostgreSQL upload transactions or prove cloud workspace delivery. Contract references: Session files API, limits, input storage, submission context validation, initialization compiler.