Secure code execution and credential management for your AI agents.
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.
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 files
Files the agent saves in its working directory
Saved with the conversation and restored when you reopen it
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
Python variables and imports remain available while the conversation’s Python kernel is running. They are not archived with files and may be lost if the kernel or sandbox is restarted. Save important intermediate results to files so the agent can reload them.
Starting a new conversation gives you a fresh working directory, but your installed packages and workspace files are already available from previous sessions.
Conversations are isolated from one another:
Each chat runs in its own sandbox, so one conversation can never see another conversation’s in-progress working files.
Sharing across chats happens only through the workspace folders and the shared package environment described above.
Your personal workspace is private to you. Other members of the same agent cannot see it.
Subagents spawned by your agent run in their own sandboxes but mount the same workspace folders and package environment, so they can reach the same shared files and packages.
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.
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.
Yes. Ask your agent, “Create a short animated product explainer from this outline.” It can render the video programmatically, show you a draft, and export the result as an artifact. Rendering uses ordinary Computer execution credits.
Yes. Your agent can use a model inside a script to process many items, such as labeling tickets in a CSV. You ask for the result in chat; the agent handles the code.For classification, it can use Jev 1.13 by TypeSafe. Jev answers yes/no questions, chooses categories, or scores items. Chat models are useful for text tasks, such as summaries. This is separate from choosing the model that replies in chat.
For a ticket-classification CSV, the agent writes a Python script that uses the Gumloop SDK to:
Read the file and collect the ticket text.
Call Jev with that text, your classification question, and the allowed categories.
Receive structured answers, such as a category for each ticket, with probabilities when provided.
Save the results in a new column and export the spreadsheet for you to download.
Jev handles the classification; the script handles reading the file and organizing the results. These model calls are separate from the model writing the chat reply.
Use Jev 1.13 from your Computer to label each ticket in this CSVas billing, product, or account access. Export the results as a spreadsheet.
2
Review the approval, if prompted
Check the script’s Purpose and Models, then approve or reject it. One approval covers the script, not each row.
A real approval card for a Computer script using Jev.
What access do I need?
Model access on Computer, granted by an Admin or Security role holder under Custom roles → Features. Your model restrictions still apply; approving a script does not bypass them.
Where are these calls billed?
Under Chat & Reasoning in the current task. Your model and BYOK pricing policy applies. See Credits.
What does Don't ask again for this tool mean?
It can allow later model-calling scripts using the same Computer tool, not just this script. Restrictions still apply. The card’s model list is a preview, not an exhaustive allowlist.
This supports permitted chat and decision models, not image-generation or transcription models. An unavailable or restricted concrete model returns an error, rather than silently switching models. See AI models and Create decision for details.
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.
Your agent can use the pre-installed gumloop SDK to combine Python processing with connector actions. These calls require the same tool permissions and approvals as other connector actions; adding a connector does not bypass those checks.This example totals the revenue column in sales.csv, then posts the summary. Replace YOUR_SLACK_CHANNEL_ID with the internal channel ID returned by Slack’s channel tools, not a name such as #general. Use a channel where you intend to send the message.
summarize_sales.py
import csvfrom decimal import Decimalfrom gumloop import Gumloopchannel_id = "YOUR_SLACK_CHANNEL_ID"if channel_id == "YOUR_SLACK_CHANNEL_ID": raise ValueError("Replace the placeholder with the intended Slack channel ID.")with open("sales.csv", newline="") as source: revenues = [Decimal(row["revenue"]) for row in csv.DictReader(source)]summary = f"{len(revenues)} sales rows; total revenue: ${sum(revenues, Decimal('0')):,.2f}"client = Gumloop()result = client.mcp.execute( server_id="slack", tool_name="send_message", arguments={"channel": channel_id, "text": summary},).results[0]if result.status != "success": raise RuntimeError(result.error)data = result.decoded_contentif isinstance(data, dict) and data.get("error"): raise RuntimeError(data.get("message") or data["error"])print(data)
Your agent uses sandbox integration calls when it needs custom processing, such as querying a database, transforming the results in Python, and posting a summary. Simple one-off connector actions use the agent’s integration tools directly.
Why did a sandbox integration call return tool_not_allowed?
Sandbox integration access is checked for each code execution. Write the server ID and tool name as literal strings in the same code cell that makes the call. Argument values can be dynamic, but the tool’s identity cannot come from a variable or loop.A helper defined only in an earlier cell does not establish access for a later cell. Put the literal call or helper in the current cell, or directly import the helper from an attached skill in that same execution. Keep tool-calling imported files inside the skill. Run saved scripts with python <script.py> from the shell; do not load tool-calling code through runpy, subprocess, or exec. If a call returns tool_not_allowed, fix how the call is declared instead of retrying the same code. Check both the SDK result status and any error returned in its decoded content.
An interrupted command may already have taken effect even when its output is incomplete. Before repeating a command that writes a file or changes an external resource, ask the agent to check the result. For example, verify that the output file exists or that the requested change completed before trying it again.
Agent secrets store encrypted credentials in your Vault and provide them to sandbox code as environment variables. This lets the agent authenticate without putting the credential in your prompt. Only bind credentials the agent needs, because its code can use them to act on your behalf.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.Secrets live in your Vault: at gumloop.com/personal/vault for your own credentials, and in the team’s Vault for shared ones. A secret is one credential type in the Vault, alongside website logins, browser profiles, and 1Password connections that the agent browser uses.You can also reuse a saved secret in a browser handoff. Choose Existing > Select a secret in a sensitive field. The picker includes Vault secrets, not website logins or connector credentials, and Gumloop types the answer only on the host shown in the handoff.
Open the agent, go to the Agent tab, expand Secrets, and click + Add.
2
Name it and pick a source
In Add personal secret to agent, set Name to the environment-variable name the agent should use (for example PYLON_API_KEY). Under Source, choose Existing secret or New secret, then pick or create the stored credential.
Click Add. The secret appears by name in the Secrets section. Gumloop supplies the value to code at runtime as an environment variable, rather than adding it to the agent’s instructions.
3
Prompt the agent to use the secret
In the agent chat, ask it to perform a task that requires the credential. The agent uses the environment-variable name (for example os.environ["PYLON_API_KEY"]) in its code. Do not ask it to print the value or copy it into a file.
A personal binding applies only to you. To let everyone who can use a custom agent run with one secret, configure an Agent-owned binding. This grants use through the agent, not direct Vault access.
Use a Team binding to make a home-team secret available to people who can use the agent and access that team. You need permission to manage the team’s variables.
1
Move agent to a team space
Move your agent into a team (or create it there).
2
Add a team secret
On the Agent tab, expand Secrets, choose Team, and click + Add.
3
Select a team secret
Pick a secret owned by the agent’s home team. Eligible team members use this binding unless a personal or agent-owned binding overrides it.
In Secrets on the Agent tab, choose who should use each binding. The stored secret keeps its personal or team owner regardless of the binding scope.
Scope
Who it applies to
Requirement
Personal
You only.
Anyone who can use the agent can save their own personal bindings.
Team
People who can use the agent and read its home team.
You must have permission to manage the home team’s variables. Team bindings can reference only secrets owned by that home team.
Agent-owned
Everyone who can use the custom agent, including people outside its home team.
You need permission to edit the agent and access to the secret you select. Your organization must allow Agent-owned credentials, and the agent cannot be shared with Anyone.
To pin a shared secret, choose Agent-owned, add the binding, and select a personal or team secret you can access. Gumloop checks your permissions when you save. Running the agent does not give others direct Vault access.If you cannot add a team binding, ask for permission to manage the team’s variables. Agents without a home team cannot use Team bindings, but custom agents can still use Personal and Agent-owned bindings.Agent-owned bindings are removed when an agent moves to a different workspace. Moving within the same workspace keeps them. Set up the bindings again in the destination workspace if the agent still needs them.
For the same environment-variable name, Agent-owned overrides Personal, which overrides Team. A personal binding is also called a user binding.Personal and team bindings require the running user’s access. Team bindings are skipped if that person cannot access the agent’s home team. Agent-owned bindings let people outside the team use the pinned secret through the agent, based on the permissions checked when it was saved. If a required secret has no usable binding, the chat asks you to configure one.
The mid-chat prompt asks Who should use these bindings? It offers personal and team bindings. Configure Agent-owned bindings in the agent’s settings, not this prompt.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:
Gumloop provides secret names to the agent and supplies the values to code at runtime, rather than placing them in chat or binding labels. This is not a guarantee that code cannot expose a credential. Never ask the agent to print or export secret values, and bind only the credentials it needs.
Can I use both personal and team secrets on the same agent?
Yes. Personal and team secret ownership is separate from binding scope. A custom agent can have personal, team, and agent-owned bindings. Team bindings require a home team and the appropriate access; agent-owned bindings require permission to edit the agent and pin the secret. See Which secret does the agent use?.
Which binding wins when both bind the same environment-variable name?
The order is Agent-owned > Personal > Team. Without an agent-owned binding for that name, your personal binding overrides an authorized team binding.
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 team’s variables. You can still configure agent-owned bindings on a custom agent if you have the required edit and organization permissions.
What about an agent with no home team?
It can use personal bindings and, for a custom agent, agent-owned bindings. Team scope requires a home team.
Do secrets persist across conversations?
Yes. Saved bindings are available in later conversations, subject to the access and scope rules above.
