Sandbox

The Sandbox node runs real code as a workflow step: a Bash or Python script you write, or an agent that reaches a goal by running commands. It runs on a small Linux machine with internet access, Python and common command-line tools, and can install packages as it goes. Every sandbox step in one run shares the same machine and working folder, so a file one step writes (or a package it installs) is there for the next. Nothing carries over to the next run.

---

​

When to use it

Use the Sandbox node for work no connector or transform can do:

• Build a binary file no connector makes: a zip, an Excel spreadsheet, an image or chart.
• Read a format no connector reads, such as an Excel file or a zip that arrived as an attachment.
• Speak a protocol there is no connector for: a database command-line tool, a legacy SOAP or raw TCP endpoint.
• Run a shell pipeline, or Python with packages.

For a simple reshape, filter or calculation, use a Transform node or the Code connector, which start instantly. If a connector does the job, use the connector.

---

​

Script or agent

Choose what the step Runs: Prefer a script whenever you know the steps: it is faster, cheaper and does the same thing every run. Use an agent when the steps cannot be known in advance, such as an unfamiliar file format or an API you need to explore. An agent reads its inputs from the machine rather than from its instructions, but text it reads (a web page, a file, an email) could still steer it. Avoid giving an agent step connections; use a script step for work with credentials.

---

​

Inputs

Values from earlier steps reach the sandbox only as inputs, never inside the script or goal. A {{ }} reference written in a script or goal is not filled in. Add an input with a name and a value (a literal or a {{ }} reference). The step reads it:

• Python: from the data dictionary, for example data["orders"].
• Bash: from $INPUT_<NAME>, for example $INPUT_BATCH_DATE for an input named batch_date (text, number and true/false values).
• Either: from the JSON file at the path in $STEP_INPUT.

This keeps an upstream value such as "; rm -rf / as data, never code. Files: map a file (an attachment’s content, a File Store Get step’s content, or an earlier sandbox step’s files[0]) to its own input. The step gets it on disk: data["orders"]["path"] in Python, $INPUT_ORDERS in Bash.

---

​

Connections

A sandbox step can use credentials through connections assigned to it, never through values typed into the script. Only the connections listed on the step reach it.

1. Under Connections, click Add connection and pick a connection.
2. Give it a short name. The name prefixes the variables: a connection named FTP gives FTP_HOST, FTP_USERNAME, FTP_PASSWORD and so on, one for each of the connection’s settings (in upper case, with words split by _). Token connections also give <NAME>_AUTHORIZATION, the header value.
3. Read them in the script: os.environ["FTP_HOST"] in Python, $FTP_HOST in Bash.

​

Secret values

For credentials no connector holds, such as a database password or a vendor API key, create a Secret connection: on the Connections page, add Secret and enter key/value pairs. Assign it to the step like any connection; a Secret named VENDOR with the key API_KEY arrives as $VENDOR_API_KEY. Saved values are never shown again. The form lists the saved keys: leave a value blank to keep it, type a new value to replace it, or delete its row to remove it.

​

How credentials are protected

• Values are passed to the step’s environment only, and never written to its input file or to the run’s history.
• Secret values (passwords, keys, tokens) are shown as *** in the step’s output and logs.
• Each connection has a Sandbox allowed switch on the Connections page, on by default. Anyone who can edit the connection can turn it off; a step assigned that connection then fails with a message naming it.
• Private connections are never given to sandbox steps: make a connection visible to the organization to use it in one.
• A connection under a governance policy (approval or blocks for changes, limited tools or hosts), or in a workspace with such a policy, is never given to sandbox steps either: a script holding the raw credentials would be outside those rules.
• Steps of the same run share the machine, so treat every connection on any sandbox step of a workflow as available to all of that run’s sandbox steps.

---

​

Output

A script step’s output: The result follows the Code connector’s rule: in Python, the value of the script’s last bare expression; in Bash, the last line printed when it is JSON. Writing JSON to $STEP_OUT/result.json also sets it, and wins. An agent step’s output is result ($STEP_OUT/result.json when written, otherwise the model’s final answer), answer, files and durationMs. Pass a file on with {{ <output>.files[0] }}: to a File Store Save step, another sandbox step’s input, or an email attachment through the SMTP connector. Up to 20 files and 50 MB per step. A non-zero exit fails a script step unless you turn off Fail on a non-zero exit, so a later step can read exitCode and decide.

---

​

Limits

• One sandbox at a time per workspace. When another run is using the workspace’s sandbox, a sandbox step waits for it (up to 10 minutes) before failing.
• 15 minutes of sandbox time per run, across all its sandbox steps.
• Sandbox time counts towards your plan’s monthly execution time like any step.
• If a run waits more than an hour (for example at a Human Approval step), files earlier sandbox steps left on the machine are gone. Pass files on through outputs instead.
• In a test run, sandbox steps are not run; they return a placeholder.
• An administrator can turn sandbox steps off for a workspace.

---

​

Example

Build an Excel file from the rows of an earlier step and save it:

1. Sandbox (Python), input payments = {{ fetched.rows }}, output variable payments_xlsx:
   import os, subprocess, sys
   subprocess.run([sys.executable, "-m", "pip", "install", "-q", "openpyxl"], check=True)
   from openpyxl import Workbook
   
   book = Workbook()
   sheet = book.active
   sheet.append(["Account", "Amount"])
   for p in data["payments"]:
       sheet.append([p["account"], p["amount"]])
   book.save(os.path.join(os.environ["STEP_OUT"], "payments.xlsx"))
   {"rows": len(data["payments"])}
   
2. File Store: Save a file, name payments.xlsx, content {{ payments_xlsx.files[0] }}.