Working in the sandbox workspace

The code interpreter (code_interpreter) runs Python for your agents. Every conversation, and every assignment run, has a sandbox workspace: a directory that keeps its files from one code interpreter call to the next, across the turns of the conversation, and across a turn that was interrupted and resumed. An agent can download a repository once, then lint it, fix it and test it over as many calls as it needs, instead of rebuilding everything in one giant call.

What persists and what does not

	Kept between calls	Notes
Files under `workspace/`	Yes	The directory is `workspace/` in the code's working directory; its absolute path is in the `WORKSPACE_DIR` environment variable.
Packages installed into `workspace/.venv`	Yes	See Packages.
Variables and imports, `session=false` (the default)	No	Every call runs in a fresh, isolated process, as before.
Variables and imports, `session=true`	Yes, while the kernel lives	See Keeping variables.
Files written elsewhere in the working directory	No	Kept as downloadable files of the conversation, as before.
`attachments/`	No	The conversation's files, copied in for the call, as before.

The process stays isolated on every call: the workspace adds files, not privileges. The sandbox has no network access and holds no credential; the workspace only ever contains the files of its own conversation.

Every code interpreter result starts with one line saying how the call ran: a fresh process or the kernel, whether the workspace was mounted, what was read and written, and which files were added, changed or removed. The tool description the agent reads lists what the workspace holds (the most recent files first, the rest counted).

Putting content in without passing it through the conversation

Reading a 20-file repository through a chat model costs every file twice: once when the tool returns it, once when the agent pastes it into code. Content can go straight to the workspace instead:

to_workspace_path: the tools that return a file or text from outside (read_file_content, web_fetch, the GitHub file tools and the integration download tools) accept it. The content is written to the workspace on the server, and the agent gets back the path, the size and the sha256 instead of the content.
sandbox_put_file: copies a file of the conversation (an upload, a download, a generated file) into the workspace.
materialize_repository: checks a repository out into the workspace through a connected integration (GitHub today), on the server, with that integration's credential and repository scope. Choose a branch, tag or commit and, optionally, sub-paths. The tree is written, never a git clone: no .git directory and no credential reach the workspace. Running it again replaces what it checked out before.
sandbox_get_file: the other way, a workspace file becomes a conversation file the agent can hand to you or to another tool.
sandbox_list_files and sandbox_remove_files list and clean it.

materialize_repository downloads content like the download tools it uses, so when tool approvals are on for an agent it asks for approval; the other sandbox_* tools follow code_interpreter.

Keeping variables: session=true

code_interpreter(session=true) runs the code in the conversation's kernel, a long-lived Python process where variables and imports persist from one session=true call to the next. reset=true starts a new one. The result says which kernel ran: a new one, the same one as before, or a new one because the previous kernel was gone.

A kernel is gone, and its variables with it, when it was idle past its timeout (15 minutes by default), when a cell ran past the call's timeout, or when the call reached another server process (local sandbox). Files under workspace/ are kept either way, so keep in files what a later step must not lose.

Packages

When the administrator has set a package allow-list, code_interpreter(packages=["name==version"]) installs packages into workspace/.venv before the code runs, where they stay. The server downloads the package from the configured index, as a wheel checked against the index's sha256, and the sandbox stays offline. Only listed packages (and their listed dependencies) are installed; the result names what was installed, what already was, and what was not and why.

Quotas and clean-up

A workspace holds at most 2 GB and 20,000 files by default. A call that would go past either saves nothing it wrote under workspace/ that time, and the result says so. Remove files and run it again.
A workspace is deleted when its conversation is archived or deleted, when its assignment run is deleted, and after 7 days without use.

When a turn is interrupted

A deployment or a restart can stop the server while an agent is working. The tool calls the turn completed are kept: a graceful stop lets the call in flight finish, keeps every completed result, and marks the turn interrupted_resumable. Continue where you left off (or any message) starts a turn that receives those calls and their results in order, followed by a short note that names the last completed call, how many results were replayed, what the workspace holds, and which long results were shortened for the replay and the file each one is kept whole in. The agent continues from there instead of starting again, and the workspace is exactly as the interrupted turn left it.

Resuming is always your choice: nothing restarts on its own.