What Files Persist Between Messages in the Sandbox?

Last updated: March 21, 2026

Within a single conversation (one chat thread with your agent), the sandbox persists visible files and Python variable state across every back-and-forth message. When you start a new conversation, the sandbox is completely fresh — nothing carries over.

How Sandbox Persistence Is Scoped

Each conversation with an agent (what you see as one chat thread) has its own isolated sandbox. Here's how it works:

  • Same conversation, multiple messages: You send a message, the agent responds and creates files or variables. You send another message — those files and variables are still there. This continues for the entire conversation.

  • New conversation: You click "New Chat" or start a fresh thread. The sandbox starts from scratch. Files, variables, and installed packages from the previous conversation are gone.

In other words, persistence lives and dies with a single conversation thread. It does not carry across conversations, even with the same agent.

What Persists Across Messages (Within the Same Conversation)

What Persists

Details

Files in /home/user/

✅ Yes

Any non-hidden file you create or modify (CSVs, scripts, images, text files, etc.) is saved after each agent turn and restored before the next one.

Python variables

✅ Yes*

Data variables are automatically pickled and restored between turns. See limitations below.

Skills

✅ Yes

Skills in /home/user/skills/ have their own persistence system and are always restored.

What Does NOT Persist (Even Within the Same Conversation)

What

Why

Hidden files (.env, .config, .hidden/)

Dotfiles are explicitly excluded from workspace saving. You can create and use them within a single agent turn (one message-response cycle), but they're gone by the next turn.

Installed packages (pip install, apt install)

The sandbox environment is recreated between turns. Over 80 packages come pre-installed and are always available, but anything you install yourself only lasts for the current turn.

Running processes

Background processes, servers, and long-running scripts are terminated when the sandbox resets between turns.

Environment variables

Any export or os.environ changes are lost between turns.

Python Variable Limitations

Python state is saved via pickling. This means only data survives — not code constructs. Specifically, these are silently dropped (no error, they just won't be there on the next turn):

  • Functions you defined

  • Classes

  • Modules you imported (e.g., import pandas as pd) — the agent will reimport them automatically

  • Variables starting with _ — treated as private/internal and excluded

  • Unpicklable objects — database connections, file handles, generators, sockets, threads

If the total pickled state exceeds 200 MB, none of it will be saved.

What works well

Strings, numbers, booleans, lists, dicts, sets, tuples, and data science objects (pandas DataFrames, numpy arrays, etc.) all persist fine across turns within the same conversation.

What to do if a variable is missing

If state restoration fails for any reason, all variables silently reset — you won't see an error, just a NameError when you try to use the variable. Ask the agent to redefine it or re-run the code that created it.

File Size Limits

  • 200 MB per file — any single file larger than this is silently skipped during saving

  • 200 MB total workspace — once the cumulative size of all files hits this limit, additional files are silently skipped

There is no error message when these limits are exceeded. The files simply won't be there on the next turn. If you're working with large files, use sandbox_download to export them before the conversation ends.

Common Gotchas

"My .env file disappeared between messages"

Dotfiles are excluded from persistence by design. Store configuration in a regular file like config.txt instead, or have the agent set values inline in each script.

"My pip package is gone on the next message"

Installed packages don't survive between turns. If a package isn't in the 80+ pre-installed list, the agent will need to pip install it again each turn. A common pattern in skill scripts is to add the install command at the top of the script.

"My helper function vanished"

Functions and classes can't be pickled across turns. If you need a reusable function, put it in a file (e.g., /home/user/helpers.py) and import it — files persist across turns, functions in memory don't.

"I started a new chat and everything is gone"

This is expected. Each conversation has its own sandbox. If you need data to survive across conversations, download it from the sandbox and re-upload it in the new conversation, or store it in an external service (Google Drive, Google Sheets, etc.) using the agent's connected tools.

Related Docs

Still Need Help?

If this didn't resolve your issue, reach out to support at support@gumloop.com.