Code Sandbox & Secrets

The Code Sandbox gives your agent the ability to execute Python code and shell commands in a secure, isolated cloud environment. It is natively enabled on all agents with no configuration required.

What the Sandbox Can Do

Run Python Code

Data analysis, visualizations, computations, file processing, API calls, and more.

Execute Shell Commands

File operations, package installation, running scripts, and system commands.

Read & Write Files

Create, modify, and organize files within the sandbox filesystem.

Upload & Download

Move files between your Gumloop storage and the sandbox environment.

How It Works

Each conversation runs in its own secure cloud sandbox (an isolated VM). The files your agent creates while working stay with that conversation, so if you reopen the chat later they are restored automatically. Anything that should outlive a single chat lives in one of two durable layers that carry over across all conversations with the same agent: the shared package environment and the agent’s workspace folders.

Persistence Model
Isolation

Scope	What Persists	Lifetime
Per-conversation	Working directory, variables, and files the agent generates while working	Saved when the chat ends and restored when you reopen that same conversation
Shared package environment	Installed packages (`pip install`, `npm install`), cached dependencies	Shared across every chat on the agent. Members with edit access add packages once and they become available to everyone
Team workspace (`.workspace/agent/`)	Skills and files saved to the shared workspace	Shared across all conversations and all members of the agent
Personal workspace (`.workspace/personal/`)	Files you save to your private workspace	Private to you, persists across all your conversations with that agent

Starting a new conversation gives you a fresh working directory, but your installed packages and workspace files are already available from previous sessions.

Pre-installed Packages

The sandbox comes with 80+ Python packages ready to use, so your agent can start working immediately without installing anything.

Data Science & Analysis

pandas, numpy, scipy, scikit-learn, statsmodels

Visualization

matplotlib, seaborn, plotly, bokeh

AI & Machine Learning

openai, anthropic, google-generativeai, mistralai, llama-index-core, gensim

Web & APIs

requests, aiohttp, beautifulsoup4, scrapy, selenium, playwright

File Processing

openpyxl, PyMuPDF, python-docx, Pillow, opencv-python, imageio

Media Processing

moviepy, librosa, ffmpeg-python, yt-dlp, soundfile

Natural Language Processing

nltk, spacy, textblob

Database & Cloud

psycopg2-binary, pymongo, PyMySQL, pyodbc, boto3, google-cloud-storage

Need something that isn’t pre-installed? Your agent can install it with pip install package-name. Installed packages are shared across every chat on the agent, so you only need to install once. Members with edit access to the agent can add packages for everyone; if you only have view access, your own installs are temporary and last for the current session.

Execution Limits

Resource	Limit
Command timeout	30 minutes per command
File ingestion	Up to 300 MB per file
Network access	Full internet access (API calls, pip installs, web requests)
GUI	Headless only. Visualizations must be saved to files (e.g., `plt.savefig()`)

The sandbox is designed for data analysis, scripting, and automation tasks. It is not intended for training large ML models or running persistent servers.

Examples

Here are some common ways to use the Code Sandbox:

Data Analysis
API Integration
File Processing
Custom Scripts

Ask your agent to analyze data:

Analyze this CSV file and create a summary with charts showing
monthly revenue trends and top-performing products.

The agent will use pandas to load the data, perform analysis, and generate visualizations with matplotlib or plotly.

Use secrets to call external APIs:

Pull all open support tickets from our Pylon API and create
a spreadsheet grouped by priority level.

The agent accesses your configured secrets as environment variables and makes authenticated API calls.

Transform and process files:

Take this PDF report, extract all tables, and convert them
into a clean Excel spreadsheet with proper formatting.

The agent uses libraries like PyMuPDF and openpyxl to read PDFs and generate spreadsheets.

Run complex multi-step scripts:

Scrape all product listings from this website, clean the data,
remove duplicates, and export as a CSV with price comparisons.

The agent writes and executes Python scripts, using the shell for any system-level operations needed.

Workspace Files

The agent has two persistent workspace folders that carry over across conversations:

Team workspace (.workspace/agent/) — shared by everyone with access to the agent. Files saved here by one member are visible to all other members, which makes it ideal for reference data, configuration, or ongoing project assets. Members with edit access can write to it; members with view access can read it but not change it.
Personal workspace (.workspace/personal/) — private to you. Files you save here persist across your own conversations with the agent and are never visible to other members.

Your agent chooses the right folder automatically based on whether a file should be shared or kept private, so you can simply ask it to save something for later. Workspace files follow the same artifact system as other agent-generated files: they are versioned, previewable, and shareable.

For more details on file management, versioning, and sharing, see Agent Artifacts.

Integration with Apps

The sandbox has access to your connected apps via the pre-installed gumloop SDK. Your agent can call any of its configured integrations directly from Python code:

from gumloop import Gumloop

client = Gumloop()
result = client.mcp.execute(
    server_id="slack",
    tool_name="send_message",
    arguments={"channel": "#general", "text": "Hello from the sandbox!"}
)

This means your agent can combine code execution with any integration, for example: query a database, process the results in Python, then post a summary to Slack.

Agent Secrets

Agent Secrets let you inject encrypted credentials into the sandbox as environment variables, so your agent can authenticate with external services (APIs, databases, etc.) without ever exposing the raw values. A secret is the stored credential, either personal or owned by a team. A binding maps an environment-variable name on an agent to a secret. Binding scope controls who gets that mapping; it does not change who owns the secret.

Adding a Secret to Your Agent

Open Settings and add a secret

Navigate to your agent and click the Settings tab. Scroll down to the Secrets section, expand it, and click + Secret.

Select from your personal secrets, or create a new one directly from the picker.

Confirm the secret is configured

Once added, the secret appears by name in the Secrets section. Your agent now has access to it at runtime.

You can add multiple secrets by clicking + Secret again, or remove one via the three-dot menu.

Prompt the agent to use the secret

In the agent chat, ask it to perform a task that requires the credential. The agent accesses the secret as an environment variable (e.g. os.environ["PYLON_API_KEY"]) and uses it in code, but it can never read or expose the actual value.

If you share an agent that uses personal secrets, other users will be prompted to provide their own values. Your secrets are never exposed.

Two Types of Secrets

Personal Secrets

Private to you. No other user can access them. Managed from your personal secrets settings.

Team Secrets

Shared across all team members. Available when an agent is in a team space.

Team Secrets

For agents in a team space, you can use shared secrets that all team members can access.

Move agent to a team space

Move your agent into a team (or create it there).

Add a team secret

In agent Settings > Secrets, click + Secret. The dropdown shows both Personal Secrets and Team Secrets.

Select a team secret

Pick from the Team Secrets section. All team members will share this value.

Binding Scopes

Bindings can be saved for User or Team scope in the agent’s Settings > Secrets section:

Scope	Who it applies to	Requirement
User	You only. The binding is saved to your own row.	Anyone who can read and use the agent can save their own user bindings.
Team	Everyone on the agent’s home team who uses the agent.	The agent must have a home project/team, and you must have permission to manage the project’s variables. Team bindings can reference only secrets owned by that home project.

The scope toggle offers Team and User. The panel describes them as:

Team scope: “Anyone in your team who uses this agent can use these secrets. A user binding with the same name overrides these.”
User scope: “Only you can use these secrets. User secrets override matching team secrets.”

If you can read team bindings but cannot manage team secrets, you can see the Team list but are prompted to request the required permission instead of adding a binding. A personal agent with no home team can only have user bindings, so the Team option is not offered.

Runtime Resolution

Secrets resolve based on the running user, not the agent owner. A user who runs an agent without a binding of their own is prompted to configure one. For each run, the authorized home-team bindings are merged with the running user’s bindings. If the same environment-variable name exists in both, the user binding wins. Team bindings are skipped when the running user does not have permission to read the home project, so users outside that team do not get them. Permissions are checked again when bindings are used, not only when they are saved. When a user encounters a secret they haven’t configured, the chat prompts them to configure it:

When the agent asks you to bind secrets mid-chat, the prompt asks Who should use these bindings? Options:

Skip: proceed without the secret
Only me: the binding applies to you
My team: the binding applies to everyone on the agent’s home team; offered only when the agent has a home team and you can manage the team’s variables

If the question goes unanswered, the binding is saved for you only, so access is never widened by accident.

Users can also manage their active secrets during a conversation using the Secrets button in the chat composer:

Comparison

Secret Ownership

	Personal Secrets	Team Secrets
Visibility	Only you	All team members
Where managed	Personal settings	Team settings
Use case	Private API keys, personal tokens	Shared service accounts, org-wide keys
Agent location	Personal or team space	Team space only
Resolution	Per-user (each provides their own)	Shared (one value for all)

Binding Scope

	User binding	Team binding
Visibility	Only the user who saved it	Users on the agent’s home team who can use the agent and read the home project
Where managed	Agent Settings > Secrets, User scope	Agent Settings > Secrets, Team scope
Who can write	Anyone who can read and use the agent	Users with permission to manage the home project’s variables
Agent location	Personal or team space	Home project/team required
Secret picker	Personal secrets available to the user	Secrets owned by the home project only
Precedence	Overrides a team binding with the same environment-variable name	Used when no user binding with the same name exists

FAQ

Can the agent see my secret values?

No. Secrets are injected as environment variables at runtime. The agent can reference them by name (os.environ["MY_KEY"]) but never sees the actual value. Values are encrypted and never shown to the agent.

Can I use both personal and team secrets on the same agent?

Yes. An agent can use personal and team secrets, and it can have both user and team bindings. Team bindings require a home team and the appropriate project access. If you run an agent with a binding you haven’t configured, the chat prompts you to bind your own (see Runtime Resolution).

Which binding wins when both bind the same environment-variable name?

Your user binding wins. The running user’s bindings override authorized team bindings with the same environment-variable name.

Who can see or use a team binding?

Anyone on the agent’s home team who can use the agent and has read access to the home project can use the binding. Permissions are checked again when the binding is used.

Why is the Team option missing?

The agent may not have a home team, or you may not have permission to manage the project’s variables. Personal agents with no home team offer user bindings only.

What about an agent with no home team?

It can use user bindings only. Team scope is not available without a home project/team.

Do secrets persist across conversations?

Yes. Secrets are bound to the agent configuration. They are available every time the agent runs code.

How do I create a new personal secret?

Go to gumloop.com/settings/profile/secrets and add one. It will then appear in the secret picker when configuring agents.

Get Started

Core Concepts

Enterprise Features

Nodes

Common Errors

Code Sandbox & Secrets

What the Sandbox Can Do

Run Python Code

Execute Shell Commands

Read & Write Files

Upload & Download

How It Works

Pre-installed Packages

Execution Limits

Examples

Workspace Files

Integration with Apps

Agent Secrets

Adding a Secret to Your Agent

Two Types of Secrets

Personal Secrets

Team Secrets

Team Secrets

Binding Scopes

Runtime Resolution

Comparison

Secret Ownership

Binding Scope

FAQ

​What the Sandbox Can Do

Run Python Code

Execute Shell Commands

Read & Write Files

Upload & Download

​How It Works

​Pre-installed Packages

​Execution Limits

​Examples

​Workspace Files

​Integration with Apps

​Agent Secrets

​Adding a Secret to Your Agent

​Two Types of Secrets

Personal Secrets

Team Secrets

​Team Secrets

​Binding Scopes

​Runtime Resolution

​Comparison

​Secret Ownership

​Binding Scope

​FAQ

What the Sandbox Can Do

How It Works

Pre-installed Packages

Execution Limits

Examples

Workspace Files

Integration with Apps

Agent Secrets

Adding a Secret to Your Agent

Two Types of Secrets

Team Secrets

Binding Scopes

Runtime Resolution

Comparison

Secret Ownership

Binding Scope

FAQ