---
title: Python Actions
description: Actions whose code is a Python script that Roboto runs on a managed runtime, with no Docker image to build.
sidebar:
  order: 14
---
## Overview

A **Python action** is an [action](/docs/learn/actions) whose code is a Python script rather than a Docker image. You write the source, and Roboto runs it on a managed Python runtime with the [Roboto SDK](/docs/learn/sdk) preinstalled and already authenticated. There is no Dockerfile, no image build, and no registry push.

Reach for a Python action when the work is a script: summarize a dataset, tag files against a rule, generate a small report, call an external API. Reach for a container action when you need system packages, a non-Python toolchain, a large model, more compute than a Python action gets, or a dependency set the managed runtime does not carry.

Both kinds are ordinary actions once created. You invoke them the same way, they fire from the same [triggers](/docs/learn/actions#triggers), and they produce the same [invocations](/docs/learn/actions#invocations).

## The runtime contract

Your script runs with its working directory set to a fresh, empty directory, and:

- **stdout and stderr become the invocation log.** Print freely; there is no separate logging setup.
- **Non-hidden files written to the working directory are collected as run artifacts** when the run finishes.
- **Input files are not downloaded.** Read them through the SDK instead. This is the significant difference from container actions, which download inputs into the container's workspace.

### Environment

These variables are **always set**:

| Variable | Meaning |
|---|---|
| `ROBOTO_BEARER_TOKEN` | The credential for this run. SDK calls authenticate as the run with no client setup. |
| `ROBOTO_SERVICE_ENDPOINT` | The API endpoint the SDK talks to. |
| `ROBOTO_ORG_ID` | The organization the run belongs to. |
| `ROBOTO_INVOCATION_ID` | This invocation's identifier. |
| `ROBOTO_DATASET_ID` | The dataset the run's files came from. **Empty unless the file selection names exactly one dataset.** |

These are set **only in some runs**:

| Variable | Present when |
|---|---|
| `ROBOTO_PARAM_<name>` | The action declares a parameter `<name>` and the caller supplied it, or it has a default. |
| `ROBOTO_ACTION_INPUTS` | The run was invoked on one or more files **and** the input manifest is small enough to fit in the environment. Holds the manifest as JSON. |
| `ROBOTO_ACTION_INPUTS_URL` | The run was invoked on one or more files and the manifest was too large to inline. Holds a presigned URL for the same JSON. |

Three of these are easy to get wrong:

- `ROBOTO_DATASET_ID` is always present but may be empty. A run whose selection spans several datasets is legal, so check it before using it.
- `ROBOTO_PARAM_<name>` may be absent entirely. Always read parameters with a fallback, such as `int(os.environ.get("ROBOTO_PARAM_limit", "10"))`.
- **Don't read the input manifest out of the environment yourself.** Whether a run gets `ROBOTO_ACTION_INPUTS` or `ROBOTO_ACTION_INPUTS_URL` depends on the size of the selection, so code that reads only the first variable sees no inputs on exactly the large selections where inputs matter most, and exits successfully having processed nothing. Ask the SDK, which handles every delivery form:

```python
from roboto import InvocationContext

action_input = InvocationContext.from_env().get_input()
for file, _ in action_input.files:
    print(file.relative_path)
```

## Example

```python
import itertools
import json
import os

from roboto import Dataset


def main() -> None:
    dataset_id = os.environ["ROBOTO_DATASET_ID"]
    limit = int(os.environ.get("ROBOTO_PARAM_limit", "10"))

    file_paths: list[str] = []
    if dataset_id:
        dataset = Dataset.from_id(dataset_id)
        file_paths = [file.relative_path for file in itertools.islice(dataset.list_files(), limit)]

    print(f"{len(file_paths)} file(s) listed.")

    # Written to the working directory, so it comes back as a run artifact.
    with open("result.json", "w") as f:
        json.dump({"dataset_id": dataset_id, "files": file_paths}, f)


if __name__ == "__main__":
    main()
```

## Compute

A Python action runs on a lightweight virtual machine of one fixed size, unlike the configurable container compute described on the [Compute](/docs/learn/compute) page:

| Dimension | Python action |
|---|---|
| vCPU | 1 |
| Memory | 2 GiB |
| Storage | Not configurable; the disk is fixed |
| Architecture | `arm64` |
| GPU | Not available |
| Longest run | 12 minutes 30 seconds |

The size is not a setting. An invocation that asks for more vCPU or memory, for a storage size, for a GPU, or for `x86_64` is refused rather than run on a machine that does not match, and so is a timeout longer than the longest run. If your work needs more compute, a specific disk size, a GPU, or a longer run, use a container action.

## Network access

Each release declares what network its runs get:

- **Roboto only**: the run reaches the Roboto API and nothing else. This is the default.
- **Open internet**: the run can also reach the public internet. Choose this when the code installs packages at runtime or calls a third-party service.

Pick the narrower option when the code doesn't need the internet. A run that cannot reach the network cannot leak data to it.

## Versions

Every Python action is released under a semantic version, and **a released version never changes**. Editing the source of an existing release doesn't modify it: it publishes a new version and leaves the old one exactly as it was.

That is what makes an invocation reproducible. A run records the version it used, so the code behind a result is always recoverable.

When you invoke an action, you may name a version explicitly or let Roboto resolve the latest release. Triggers pin whatever you give them, so a trigger set to an exact version keeps running that code until you change it.

You can view the source of any release, edit it, and publish the result as a new version from the action's page in the Roboto web UI.
