---
title: Action Configuration
sidebar:
  order: 57
---
`action.json` is the configuration file that defines a Roboto Action. The Roboto CLI consumes it when creating or updating actions:

```bash
roboto actions create --from-file action.json
```

`roboto actions init` generates one when scaffolding a new action project.

## Top-level fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Unique identifier for the action within your organization. Conventionally `kebab-cased`. |
| `description` | string | No | Full description of what the action does. |
| `short_description` | string | No | One-line summary shown in listings and the Action Hub. |
| `parameters` | list of [Parameter](#parameter) | No | Runtime parameters that customize action behavior at invocation time. Defaults to `[]`. |
| `requires_downloaded_inputs` | boolean | No | Whether to download input files into the action's workspace before execution. Set to `false` if the action reads only ingested topic data and does not need raw files. Defaults to `null` (platform default applies). |
| `compute_requirements` | [ComputeRequirements](#computerequirements) | No | CPU, memory, and storage to allocate for each invocation. |
| `container_parameters` | [ContainerParameters](#containerparameters) | No | Overrides for the container's entrypoint, command, environment variables, and working directory. |
| `image_uri` | string | No | URI of a pre-built Docker image in a registry the Roboto platform can access. Mutually exclusive with `docker_config`. |
| `docker_config` | [DockerImageConfig](#dockerimageconfig) | No | Instructions for building a Docker image from a local Dockerfile. Mutually exclusive with `image_uri`. |
| `inherits` | [ActionReference](#actionreference) | No | Reference to another action whose container image, container parameters, action parameters, and input-download settings this action inherits. When set, `image_uri`/`docker_config`, `container_parameters`, `parameters`, and `requires_downloaded_inputs` must be omitted — those are inherited from the referenced action. |
| `tags` | list of strings | No | Free-form labels for filtering and discovery. Defaults to `[]`. |
| `metadata` | object | No | Arbitrary key/value metadata attached to the action. Defaults to `{}`. |
| `timeout` | integer | No | Maximum invocation duration in minutes. If omitted, the platform applies a tier-dependent default (30 minutes for free-tier orgs, 720 minutes otherwise). |

## Parameter

Defines a parameter passed to an action at invocation time. Action code reads parameters via [`InvocationContext`](/docs/reference/python-sdk/roboto/action_runtime#roboto.action_runtime.InvocationContext).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Parameter name. Used as the key when passing values at invocation time. |
| `description` | string | No | Human-readable description of the parameter's purpose. |
| `required` | boolean | No | Whether the parameter must be provided at invocation time. Defaults to `false`. |
| `default` | any | No | Value used when the parameter is not provided. Coerced to a string. |

**Example:**

```json
"parameters": [
    {
        "name": "threshold",
        "description": "Alert threshold in meters per second squared",
        "required": false,
        "default": "9.8"
    },
    {
        "name": "topic",
        "description": "Topic name to analyze",
        "required": true
    }
]
```

## ComputeRequirements

Compute resources allocated to each action invocation. Not all vCPU and memory combinations are valid — see the table below for supported pairings, or the [Compute](/docs/learn/compute) page for how usage is measured.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `vCPU` | integer | No | CPU units to allocate; 1024 units = 1 vCPU. Defaults to `512` (0.5 vCPU). |
| `memory` | integer | No | Memory in MiB. Valid values depend on `vCPU` — see the table below. Defaults to `1024` (1 GiB). |
| `storage` | integer | No | Ephemeral storage in GiB. Minimum `21`; maximum `200` (premium-tier orgs). Defaults to `21`. |

**Valid vCPU / memory combinations:**

| `vCPU` | vCPUs | Valid `memory` values (MiB) |
| --- | --- | --- |
| `256` | 0.25 | 512, 1024, 2048 |
| `512` | 0.5 | 1024, 2048, 3072, 4096 |
| `1024` | 1 | 2048 – 8192 (in 1024 MiB increments) |
| `2048` | 2 | 4096 – 16384 (in 1024 MiB increments) |
| `4096` | 4 | 8192 – 30720 (in 1024 MiB increments) |
| `8192` | 8 | 16384 – 61440 (in 4096 MiB increments) |
| `16384` | 16 | 32768 – 122880 (in 8192 MiB increments) |

## ContainerParameters

Overrides for the action container's runtime configuration. Each field overrides the value baked into the Docker image.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entry_point` | list of strings | No | Overrides the image `ENTRYPOINT`. |
| `command` | list of strings | No | Overrides the image `CMD`. |
| `env_vars` | object (string → string) | No | Environment variables injected into the container. |
| `workdir` | string | No | Overrides the container's working directory. |

## DockerImageConfig

Builds a Docker image from a local Dockerfile at deploy time. Set as the `docker_config` top-level field. Mutually exclusive with `image_uri`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `dockerfile` | string (path) | No | Path to the Dockerfile. Defaults to `./Dockerfile` relative to the current working directory. |
| `context` | string (path) | No | Docker build context. Defaults to the current working directory. |
| `build_args` | object (string → string) | No | Build-time variables passed via `docker build --build-arg`. |

## ActionReference

Points at another action whose container image, container parameters, action parameters, and input-download settings this action reuses. Set as the `inherits` top-level field. See the `inherits` row in [Top-level fields](#top-level-fields) for fields that cannot be set alongside it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Name of the action to inherit from. |
| `owner` | string | No | Org ID of the action's owner. Defaults to your own organization. |
| `digest` | string | No | Pins to a specific action version digest. If omitted, the latest version is used. |

## Full example

```json
{
    "name": "check-magnetometer-norm",
    "short_description": "Flag flights where magnetometer norm deviates from expected range",
    "description": "Computes the magnetometer vector norm for each flight and creates an event if it falls outside the configured tolerance range.",
    "parameters": [
        {
            "name": "min_norm",
            "description": "Minimum acceptable magnetometer norm (µT)",
            "required": false,
            "default": "25"
        },
        {
            "name": "max_norm",
            "description": "Maximum acceptable magnetometer norm (µT)",
            "required": false,
            "default": "65"
        }
    ],
    "requires_downloaded_inputs": false,
    "compute_requirements": {
        "vCPU": 1024,
        "memory": 2048
    },
    "tags": ["diagnostics", "magnetometer"]
}
```