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 user gets their own persistent sandbox per agent. The sandbox is a secure cloud VM that persists across conversations, so your installed packages, files, and workspace state carry over between chats.

Persistence Model
Isolation

Scope	What Persists	Lifetime
Cross-conversation	Installed packages (`pip install`, `npm install`), cached dependencies	Survives across all chats with the same agent
Agent-wide	Skills, workspace files (saved to `.workspace/`)	Shared across all conversations with that agent
Per-conversation	Working directory, variables, generated files	Scoped to a single chat session

Starting a new conversation creates 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 persist across conversations, so you only need to install once.

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

Files saved to the .workspace/ directory persist across all conversations with the same agent. This is useful for reference data, configuration files, or ongoing project assets that should always be available.

Project members share a common workspace. Files saved by one member are visible to other members of the same project.
Non-members get an isolated workspace. Their files are private.

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="slack",
    tool="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.

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.

Agent Settings page showing the Secrets section expanded with No secrets configured and an arrow pointing to the + Secret button

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.

Agent Settings Secrets section showing Pylon API Key configured

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.

Agent chat showing it has access to PYLON_API_KEY and using it to query the Pylon API for tickets created today

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.

Secret picker showing Personal Secrets and Team Secrets sections with Pylon API Key under Team Secrets

Runtime Resolution

Secrets resolve based on the running user, not the agent owner:

Personal secret configured: other users are prompted to provide their own value
Team secret configured: all team members share the same value

When a user encounters a secret they haven’t configured, the chat prompts them to configure it:

Chat showing Configure secrets prompt with PYLON_API_KEY needed, a dropdown to select from Personal Secrets or add new, and buttons for Skip, Save for me, and Save to agent

Options:

Skip: proceed without the secret
Save for me: map a personal secret for this user only
Save to agent: update the agent’s default binding

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

Chat composer Secrets popover showing Your secrets with Pylon API Key mapped to PYLON_API_KEY

Comparison

	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)

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 in a team space can use both types. Team secrets share one value for all members. Personal secrets require each user to provide their own value. If you run an agent that has a personal secret you haven’t set up yet, the chat will prompt you to bind your own (see Runtime Resolution).

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.

​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

​Runtime Resolution

​Comparison

​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

Runtime Resolution

Comparison

FAQ