Sandbox and skills
The sandbox is an isolated computer that Genie gets for each conversation. In it, Genie runs code to analyse the Excel or CSV files people attach, calculate, draw charts and produce Word, Excel or PDF files. Skills are packages of instructions and scripts that teach Genie and your agents a specific task, such as producing a report in your company template. System administrators manage each workspace's sandbox configurations and decide whether code may run at all. A workspace's Admins and Owners manage skills and can turn running code off for their workspace, and every member can store their own keys under Sandbox secrets.
What the sandbox does for users
There is no switch per conversation. Genie runs code when all of these hold:
- a system administrator has set up a working sandbox configuration for the workspace, or your deployment provides a system default sandbox;
- running code is on for the workspace: allowed by the system administrators and not turned off under Run code in the workspace's Features (see Turn code execution off);
- the person is signed in to Genie with their own account. People who chat through Microsoft Teams, Zalo or the website widget, and calls made with API keys, never get code execution.
Genie, the default assistant, picks a sandbox configuration of the workspace by itself (the system default only when the workspace has none it can use), and a conversation keeps the sandbox it started with. An agent uses the sandbox chosen in its editor under Skills → Sandbox. With no sandbox selected (Disabled), the agent does not run code, unless your deployment provides a system default: the option then reads Not selected (system default), and the agent runs code there.
Files people attach are copied into the conversation's sandbox. People see the steps of the answer and the files Genie produced, which they can preview and download; if the configuration asks for approval, they also see an approval card before risky commands. The sandbox panel next to the conversation shows the files, a terminal and, where available, a desktop. See Code and sandbox and Files and artifacts.
Sandbox configurations
A sandbox configuration says where sandboxes run and what they may do. Your Genie provider usually creates the first one and connects it, because it needs the details of the sandbox service they run. A system administrator then reviews and adjusts what it allows people to do (see System administration). Workspace Admins and Owners do not see these settings: they pick a configuration for each agent and ask their system administrator for changes.
To review or change a configuration:
- Open Settings → Sandbox in the System administration group.
- Under Workspace, pick the workspace. The configurations below it apply to that workspace only; you do not need to switch into the workspace first. (Vector database and Storage in the same group have the same picker.) Each configuration is a card, grouped by sandbox type.
- Click the card (or open its menu and choose Edit).
- Go to the Runtime step and adjust Execution settings, Network policy and Environment variables (see the table below).
- Click Save. Changes apply to new sessions; a sandbox that is already running keeps its old network policy until it is replaced.
website-docs/public/screenshots/en/sandbox-settings.pngTo add a configuration, click Add sandbox, choose the Sandbox type, enter a Config name and the connection details your Genie provider gives you, then click Connect and continue. On the Template step, keep the Genie standard template (marked Recommended). Finish the Runtime step and save. Test connection checks that the service answers; Full verification also creates a throwaway sandbox, runs a script, checks outbound access and deletes it. Some sandbox types appear only when your Genie provider has enabled them.
| Setting | What it does for users |
|---|---|
| Execution timeout (s) | The longest a single skill script may run before it is stopped. Empty means 60 seconds |
| Sandbox TTL (s) | How long until the sandbox is paused. A paused sandbox keeps its files and wakes up on the next message |
| Delete paused sandboxes after (h) | A sandbox paused longer than this is deleted. The next message starts a fresh sandbox: attachments are copied in again, and earlier files stay downloadable in the chat |
| Terminal / desktop idle disconnect (s) | Closes an open terminal or desktop after this much inactivity, so the sandbox can pause. Empty means 900 seconds |
| Persistent workspace | Keeps each conversation's files when its sandbox is freed. See Persistent workspace |
| Default egress | Deny by default (recommended) blocks everything except the Allowed destinations (and, on CubeSandbox, the HTTP access rules (L7)). New configurations start with it and let code only download from the Python package index (pypi.org, files.pythonhosted.org). Allow public network lets code reach the whole internet |
| Allowed destinations, Denied destinations | Allowed destinations are domains (such as *.contoso.test), IP addresses or ranges that code may reach even when the default denies. Denied destinations are IP addresses or ranges it may never reach. An allowed domain only takes effect together with Deny by default (recommended) |
| CPU cores, Memory limit (MB), Process limit, Idle reclaim (seconds) | Resources of one sandbox, shown for sandbox types that run on a single server. Network mode replaces the egress settings there: bridge (egress allowed) or none (no egress) |
| Environment variables | Values added to every sandbox created from this configuration. Every script in the sandbox can read them, so do not put personal secrets here; use Sandbox secrets |
| How the new skill image takes effect | After a skill is installed or removed: Rebuild open sessions on the next chat turn, or Keep open sessions on their current sandbox; only new sessions use the new image |
The card menu also has Running instances, which lists the conversations that still hold a sandbox of this configuration and the agents that use it. While conversations still hold its sandboxes, a configuration cannot be deleted and its connection cannot be changed; Genie shows you which conversations to end first. Agents that use a deleted configuration stop running code.
System default sandbox
Your deployment can come with a sandbox that every workspace gets without any setup. It is set up for all workspaces when Genie is installed, and appears on Settings → Sandbox, whichever workspace you pick, as a card named System default, marked Read-only.
- Read-only. The card has no edit, delete, skills or template actions, and it never shows the connection details, the key or environment variables. Nobody can change or delete it from the workspace. You can still see its sandboxes, which belong to your workspace's own conversations.
- No skills. Skills cannot be installed on it. To use skills, add a sandbox configuration of your own (see above) and install them there.
- Who uses it. Unless this was turned off when Genie was installed, agents with no sandbox selected run code in the system default; the agent editor also lists System default as a choice. An agent that selects one of your configurations keeps using that one. Genie uses your workspace's own configurations first, and the system default only when the workspace has no configuration it can use.
- What it allows. By default, code may only download from the Python package index (pypi.org, files.pythonhosted.org) and cannot reach anything else. A system administrator can change this for every workspace, or for one workspace, under Settings → Network & antivirus → System default sandbox network. Commands run without asking for approval, and that cannot be changed. Commands that would wipe the sandbox, and network commands after an answer has read protected documents, are still refused, and every command is audited.
- Shared capacity. All workspaces of the deployment share its capacity. When it runs short, a paused or idle sandbox may be deleted sooner; the conversation's next message then starts a fresh sandbox, with its attachments copied in again.
To stop using it, select one of your workspace's configurations on each agent (Skills → Sandbox), ask a system administrator to add a configuration of your own so that Genie uses it instead, or turn running code off for the workspace (see below), which applies to the system default too.
Turn code execution off
Two switches decide whether code runs in a workspace, and the stricter one wins:
| Where | Setting | Effect |
|---|---|---|
| Company | Run code under Running code in every workspace, at the top of Settings → Sandbox in the System administration group (on by default) | When off, no conversation or agent in any workspace runs code, and workspace admins cannot turn it on. Under Workspaces with their own setting, a system administrator can give one workspace its own value |
| Workspace | Run code under Settings → Features in the Workspace group (Admins and Owners) | When off, nobody in this workspace runs code. While the system administrators have it off, the switch is greyed out and reads Turned off by your system administrators. |
When running code is off, Genie and every agent in the workspace stop running code and skill scripts; they can still read skill instructions. Sandboxes already running are released when their sessions end. Turn the switch on again to restore it.
Persistent workspace
Without it, a sandbox that has been paused too long is deleted, and the conversation's working files go with it (files Genie delivered stay downloadable in the chat). With Persistent workspace on, each conversation's working folder (attachments, outputs and the files Genie created) is kept on separate storage. The sandbox can then be freed a few minutes after the conversation goes quiet, and the next message starts a new sandbox with the same files.
| Setting | What it does for users |
|---|---|
| When the sandbox is idle | Destroy (default) frees the sandbox entirely; the files stay and the next message starts a fresh sandbox. Pause keeps memory and running programs, and resumes on the next message |
| Idle time before that (s) | Counted from the last message, command, file transfer, terminal or desktop use. Empty means 180 seconds |
| Idle time for the desktop (s) | Used instead when people work in a sandbox desktop. Empty means 900 seconds |
- The next message after an idle period takes a few seconds longer to start.
- Packages installed by hand and programs that were running are not kept. Tools people always need belong in the template or in a skill.
- Conversations with many small files are a little slower than on the sandbox's own disk.
- The stored files are deleted with the conversation.
- Only some sandbox types offer this option. If you do not see it, ask your Genie provider.
Skills
A skill is a package with a SKILL.md description plus scripts, templates and reference files. Skills live in the workspace catalog, and each one must be installed into a sandbox before it can run there. Admins and Owners add, install and remove skills; anyone who may edit an agent can choose which installed skills it uses.
To add a skill:
- In the sidebar, open Toolbox → Skill Management.
- Click Add skill.
- Under Install from a source, paste a link to the skill (for example a GitHub repository or folder, or a skill registry page). Or, under Upload a local bundle, upload a zip that contains
SKILL.md. Click Next: the skill is added to the catalog. - On the Install step, tick the sandboxes under Install onto sandboxes, pick an Installer model (a chat model that supports tool calls) and click Install onto sandbox. To install later, click Done instead.
- Follow the progress. The status goes from Installing to Ready, or to Failed with the reason. Installing can take several minutes.
If an install fails, open it to read the reason. You can add guidance for the installer (for example a command-line tool the skill needs) and choose Reinstall with guidance, or simply Reinstall. Stop install aborts a run in progress.
To use a skill:
- Genie can use every enabled skill that is ready on the sandbox it runs in.
- An agent: in the agent editor, open Skills, choose the Sandbox, and set Skill list to All, Selected (then tick the skills) or Disabled. Only skills that are ready on that sandbox can be ticked.
- People can type
@in the chat box and pick a skill to ask for it by name. See Code and sandbox.
To manage an installed skill, open it in Skill Management and choose the sandbox it is installed on:
| Action | Effect |
|---|---|
| Enable (switch) | When off, agents and Genie no longer see the skill; its files stay installed |
| Environment variables | The keys the skill declares, with Workspace-wide values (see Sandbox secrets) |
| Upgrade | Installs the catalog's newer version. The sandbox keeps running the current version until the upgrade succeeds, and keeps it if the upgrade fails |
| Uninstall from sandbox | Removes the skill from that sandbox. It stays in the catalog for other sandboxes |
| Remove from catalog | Deletes the skill once it is uninstalled from every sandbox |
Each sandbox needs its own install: a skill installed on one configuration is not available on another.
Sandbox secrets
Some skills need keys, for example an API token for an internal system. Genie passes them to the skill when it runs and never shows a saved value again.
For each person. Everyone sets their own values in Settings → Sandbox secrets (in the Account group):
- Keys a skill needs lists, per skill, the keys it declares. Fill them in ahead of time, or provide them in the conversation when Genie asks.
- Always passed in a chosen sandbox holds values passed to every command you run in that sandbox. Most people never need it.
Other members cannot see your values, and theirs never replace yours.
For the whole workspace. Admins and Owners can fill in shared values: open Toolbox → Skill Management, open the skill on its sandbox, expand Environment variables and fill in Workspace-wide values. Members who have not set their own value use these.
When a skill runs, a person's own value for that skill comes first, then their own value for the sandbox, then the workspace-wide value. Removing a personal value makes the workspace value apply again; disabling a skill does not delete anyone's values.
Security notes
- Each conversation runs in its own isolated sandbox. Code in one conversation cannot see the files of another.
- Commands can wait for approval. By default Genie runs commands without asking. Under Command approval in a sandbox configuration, a system administrator can choose Ask before installing packages, using the network, deleting files or writing outside the workspace, or Ask before every command; the person then sees an approval card, and a request left unanswered is refused. Commands that would wipe the sandbox are always refused.
- Protected documents keep code offline. After an answer has read documents whose protection level does not allow external services, network commands are refused for the rest of that answer.
- The network policy is the real boundary. On most sandbox types, new configurations deny the network by default and allow only downloads from the Python package index, so code cannot send files out; add only the destinations your skills need. Configurations created before keep their policy: switch them to Deny by default (recommended) the same way.
- Every command is audited as Code run in a conversation sandbox: the beginning of the command, its result, duration, files produced and the approval decision, never its output. See Usage, analytics and audit.
- Install only skills you trust. A skill's scripts run with full rights inside the sandbox, and its setup runs while it is installed. Read its files with View files before you install it. Links must be publicly readable; for a private skill, upload a zip.
- Configuration environment variables are not secret from scripts. Anything under Environment variables of a configuration can be read by every script in that sandbox.
Good to know
- Only system administrators see and change sandbox configurations, on Settings → Sandbox for the workspace they pick. A workspace's Admins and Owners can only turn running code off, or back on, under Settings → Features. They open Toolbox → Skill Management; its link to the sandbox settings, like the one in the agent editor, tells anyone else to ask their system administrator. Every member can open Sandbox secrets.
- Installing or removing a skill builds a new sandbox image. With Rebuild open sessions on the next chat turn, open conversations get a fresh sandbox on their next message, and their unsaved working files are lost.
- A paused sandbox keeps its files. How long it stays paused depends on Delete paused sandboxes after (h) and on the capacity of the sandbox service.
- A desktop in the sandbox panel is only available with the Genie desktop template. Ask your Genie provider if your people need one.
- If code never runs, check that the workspace has a configuration (or the deployment provides a system default), that Run code is on both for the company and in the workspace's Features, and that the agent has a Sandbox selected (unless it relies on the system default). If the configuration cannot connect, ask your Genie provider.