Code Node

The Code Node lets you write and run custom Python or TypeScript code directly inside a Stack AI workflow, with the help from an AI code assistant.

Differences between Code Node and Python Node

Code Node

• Supports Python and Typescript

• Allows importing custom libraries

• Allows custom expressions

• Reads input data from all upstream nodes

Python Node

• Supports Python

• Restricted to pre-imported libraries

• Does not allow unsafe expressions

• Reads data from the most immediate proceeding nodes

How the Code Node Works

The Code Node offers a fullscreen editor with an AI code assistant.

Set Dependencies

The Dependencies field is a list of package names that get installed into the sandbox before your code runs.

Dependencies are optional. When no dependencies are declared, the sandbox will run your code directly, which is a faster startup.

Reference Input Variables

Select a specific field within a variable

The left panel lists all upstream variables connected to the Code Node.

You can select a variable by hovering over the field and click "+Insert". The value selected will automatically populate in the code editor. The advanced expression gives the flexibility to select specific fields within a nested JSON, such as the "value" field in the example above.

Write Code

You can ask the code assistant to help you update the code. Changes proposed by the assistant are highlighted.

The code must include a main(args) function, which is pre-populated in the template. This function is where the logic lives. The output returned by main() becomes the output of the node, available to all downstream nodes.

The output of the Code Node must be returned in JSON format.

You can format the output in two ways:

• Returning a Python dictionary that represents a JSON object

Return {"Result":result_variable}

• Explicitly serializing the result using json.dumps()

Return json.dumps(result_variable)

Test Code

Testing code is easy. You can run the code directly from the editor.

The test run will use the most recent values. This means that you need to run the upstream nodes at least once in the Builder view for the code editor to have access to test values.

Error Handling

If something goes wrong, the Code Node will surface an error message. Common errors include:

• Dependency install failed: a declared package couldn't be installed. Check the package name/version.

• Sandbox timed out: the environment took too long to start. Try again.

• Code execution failed: an unhandled exception in your code. Check the Error output for details.

If you've connected a failure branch to the node, errors will automatically route there instead of stopping the workflow.

How to Generate a File with the Code Node

The Code Node can produce files as outputs. Anything you write to the sandbox's /home/user directory during execution is automatically captured, uploaded, and exposed as a pre-signed download URL in the node's output. This is the recommended way to generate CSVs, PDFs, and any other files via the code node.

How it works

Every Code Node run executes inside an isolated sandbox with /home/user as the working directory. When main() returns, Stack AI:

1. Scans /home/user for any files you created or modified during the run.

2. Uploads each file to secure object storage.

3. Issues a short-lived, pre-signed download_url for each file.

4. Appends them to the node's output under files.elements[].

You don't need to return the file from main() — saving it to disk is enough. The return value is still passed through as result, so you can return structured metadata alongside the file (row counts, summaries, the file name, etc.).

Minimal example

def main(args):
    file_path = "/home/user/sample_download_test.txt"

    with open(file_path, "w") as f:
        f.write("Hello! This is a sample file for testing download_url.")

    return {} # Note: no need to return anything

After the node runs, its output looks like this:

{
  "result": {},
  "exit_code": 0,
  "logs": "",
  "error": "",
  "files": {
    "elements": [
      {
        "id": "db6d004a-e43e-448b-b755-ac2328...",
        "name": "sample_download_test.txt",
        "download_url": "https://sb.stack-ai.com/storag..."
      }
    ]
  }
}

Using the file downstream

Reference the URL or file metadata from any downstream node using an "advanced expression", e.g. { code-0.files.elements[0].download_url }. Common patterns:

• Email: paste the download_url directly into a attachments field of an Outlook / Gmail Send Email node.

• Output node: surface the URL to the end user as part of the workflow's response in the chat / form UIs.

• Loop / merge nodes: when generating multiple files, each element in files.elements[] gets its own download_url, and you can iterate over them just like any other array.

Generating multiple files

You can drop multiple files into /home/user. They all show up as separate entries in files.elements[], in the order they were written:

import csv

def main(args):
    for region in ["us", "eu", "apac"]:
        with open(f"/home/user/sales_{region}.csv", "w", newline="") as f:
            writer = csv.writer(f)
            writer.writerow(["product", "units"])
            writer.writerow(["widget", 42])

    return {"generated": 3}

Binary files

Write binary files the same way — open in binary mode and the upload step will preserve content type:

from PIL import Image

def main(args):
    img = Image.new("RGB", (256, 256), color=(73, 109, 137))
    img.save("/home/user/swatch.png")
    return {}

PDFs, Excel files, ZIPs, audio, and any other binary format work identically.

Notes

• Only /home/user is scanned. Files written to /tmp, /var, or any other path are discarded when the sandbox terminates. Always write to /home/user/....

• Pre-signed URLs are short-lived. They're suitable for immediate downstream consumption or sharing with end users in the moment, but they're not permanent storage links — re-run the node to regenerate them, or persist the file to your own storage (S3, Google Drive, etc.) via a downstream node if you need long-term access.

• TypeScript works the same way. Use fs.writeFileSync("/home/user/output.csv", ...) (or any other Node.js file API) and the same auto-capture behavior applies.