Preparing the project
A code project's contract: the roberty.json manifest, the roberty-* variables, arguments and result, exit codes, the exception entry point and the official SDK.
Preparing the project
To run on Roberty, the repository (or the .zip) follows a simple contract: a roberty.json manifest at the root tells the platform how to start the robot, and the platform talks to the process through environment variables, JSON files and the exit code. On every deploy, Roberty validates this structure and installs the dependencies before handing the code to the devices.
Minimum structure
Node.js
my-robot/
├── roberty.json
├── package.json
└── src/
└── index.js
Python
my-robot/
├── roberty.json
├── main.py
└── requirements.txt
The roberty.json manifest
Every project — Node.js or Python — declares its entry points in a roberty.json file at the root of the repository or the .zip. It is the single source of truth on how to start the robot: Roberty never guesses the language, the runtime or the starting file. The manifest is validated on every deploy.
| Key | Required | Description |
|---|---|---|
entrypoint | Yes | How Roberty starts the robot. Node.js: a shell command. Python: the relative path of a .py file. |
exceptionHandler | No | Runs when the entrypoint ends with an error, in the same format as the entrypoint. See Exception entry point. |
blockParallel | No | true makes the project run alone on the device. Default: false. See Exclusive execution. |
webhook | No | The webhook trigger's contract: the keys the robot reads and writes. See The webhook section. |
$schema | No | The URL of the public JSON Schema, for autocomplete and validation in the IDE. Ignored on deploy. |
A complete example:
{
"$schema": "https://api.roberty.app/v4/public/schemas/code/roberty.json",
"entrypoint": "node src/index.js",
"exceptionHandler": "node src/exception.js",
"webhook": {
"inputs": [
{ "name": "cpf", "type": "string", "required": true, "description": "Customer's CPF, digits only" }
],
"outputs": [
{ "name": "status", "type": "string", "description": "ok | not_found" }
]
}
}
Validation rules
- The file must be a valid JSON object, and
entrypointis required and cannot be empty. - Python: paths are relative to the project root, must end in
.pyand point to files that exist in the deploy. Absolute paths, or paths that escape the root with.., are rejected. - Node.js: the command is free shell — plain Node,
tsx,ts-node, a prior build and so on — but commands that look like they invoke Python (e.g.python main.py) are rejected. blockParallelmust be a boolean; any other value fails the deploy.- Unknown keys are ignored.
Autocomplete in the IDE ($schema)
The roberty.json format is published as a JSON Schema at https://api.roberty.app/v4/public/schemas/code/roberty.json. With the $schema key pointing to it, editors such as VS Code autocomplete the keys, show each one's description and flag errors (such as a missing entrypoint), with no extension.
The same reference appears in the project's settings, on the Manifest tab, with a ready-made template for the project's language. See Settings.
The webhook section
Declares, for whoever integrates with the robot, which keys it reads from the arguments file (inputs) and which it writes to the result file (outputs). The platform exposes this declaration through the API and uses it to build the example request. See API and webhook.
Each item of inputs and outputs:
| Field | Required | Description |
|---|---|---|
name | Yes | The key's name. It cannot be empty and must be unique within the list. |
type | No | Free text to guide the integrator (string, number, object…). Default: any. Not validated when the run is triggered. |
required | No | In inputs, true makes a webhook trigger fail with 400 if the key is missing from the arguments. In outputs, it is documentation only. Default: false. |
description | No | Free text shown to the integrator. |
When a run is triggered, only the presence of the inputs marked required is checked: types and extra keys reach the robot exactly as they were sent. A malformed webhook section — not an object, inputs that is not a list, an item without name, or a repeated name — fails the deploy with a message pointing at the field. Without the section the webhook trigger still works; there is simply no published contract.
Exclusive execution (blockParallel)
With "blockParallel": true, the project does not run in parallel: it only starts when the device is idle, nothing else starts on the device while it runs — RPA robots and other code projects wait for it to finish — and runs that arrive afterwards wait in the queue. Deployments with this option carry the Does not run in parallel badge. See Deployments.
Node.js project
roberty.jsonat the root, withentrypointas a shell command. The command runs at the project root, with the Node version configured on the platform and the project's package manager on thePATH(e.g.node src/index.js,npm run start,npx tsx src/index.ts).package.jsonat the root, used to install the dependencies with npm or yarn. No particular script is required in it.
{
"$schema": "https://api.roberty.app/v4/public/schemas/code/roberty.json",
"entrypoint": "node src/index.js"
}
Python project
roberty.jsonat the root, withentrypointpointing to the starting.pyfile. Its name and location are up to you; the file must exist and is syntax-checked (py_compile) on deploy.requirements.txtat the root is optional. If it exists, the dependencies are installed in an isolated virtual environment, with the Python version configured on the platform; if not, the installation is skipped.
{
"$schema": "https://api.roberty.app/v4/public/schemas/code/roberty.json",
"entrypoint": "main.py"
}
Environment variables
On every run, Roberty injects these variables into the process:
| Variable | Present in | Description |
|---|---|---|
roberty-environment | Every run | production or preview. |
roberty-trigger | Every run | manual, schedule, webhook or evaluation. |
roberty-output-file-path | Every run | The path of a file where the robot can write its result (JSON). |
roberty-args-file-path | webhook and evaluation only | The path of a JSON file with the run's arguments. In manual and schedule runs the variable does not exist. |
The names contain hyphens, so read them by key: process.env["roberty-trigger"] in Node.js, os.environ.get("roberty-trigger") in Python.
Arguments and result
- Arguments. In webhook and evaluation runs, the arguments arrive as JSON in the file at
roberty-args-file-path. Manual and scheduled runs have no arguments: the robot is responsible for getting its own input. - Result. Whatever the robot writes to the file at
roberty-output-file-pathis read back by the platform: in evaluations, it is compared with the expected output; in webhooks, it is returned to the integrator inresponsewhen the process ends successfully. Write valid JSON — text that is not JSON comes back as a raw string. In the webhook response, the result is capped at 256 KB; anything beyond that is cut off.
Exit code and logs
- Exit code
0means success. Any other value marks the run as failed. Exit with a non-zero code on errors — unhandled exceptions already do. stdoutandstderrbecome the run's logs, visible on the platform. Use them to record the robot's progress.
Exception entry point
exceptionHandler is an optional command (Node.js) or .py file (Python) that Roberty runs automatically when the entrypoint ends with an error.
- It runs only when the
entrypointfails. It does not run on evaluation runs, nor when the user stops the run. - It gets the same environment variables as the main run, and the file at
roberty-args-file-pathholds the error's details:
{
"message": "the error message",
"stack": "stack trace (may be null)",
"exitCode": 1
}
- Its exit code and output do not change the main run's result. Its logs are appended to the run's logs.
- Use it for alerts, notifications and cleanup — not to "fix" the result.
{
"entrypoint": "main.py",
"exceptionHandler": "on_error.py"
}
Official SDK
Roberty publishes one package per language that wraps this contract, so you don't deal with variable names or with the arguments and result files:
| Language | Package | Install | Import |
|---|---|---|---|
| Node.js ≥ 18 | @roberty/code | npm install @roberty/code | import roberty from "@roberty/code" or const roberty = require("@roberty/code") |
| Python ≥ 3.9 | roberty-code | pip install roberty-code | import roberty_code as roberty |
The API is the same in both languages and can be called anywhere in your code:
| Member | What it does |
|---|---|
roberty.trigger | "manual", "schedule", "webhook" or "evaluation" (null/None outside Roberty). |
roberty.environment | "production" or "preview". |
roberty.isRoberty / roberty.is_roberty | true when the process runs on Roberty. |
roberty.inputs() | Every argument (webhook and evaluation); null/None when there are none. |
roberty.input("key", default) | A single argument, with an optional default value. |
roberty.output(value) | Writes the result (JSON) that the platform reads back. |
roberty.exception() | { message, stack, exitCode } inside the exception entry point. |
roberty.run(handler) | Optional: runs handler(roberty), writes its return value as the result and exits with code 0 or 1. |
The same code runs outside Roberty: inputs() returns nothing and output() only warns that there is no result file.
Node.js
const roberty = require("@roberty/code");
async function main() {
console.log(`Starting (${roberty.environment}, trigger: ${roberty.trigger})`);
const cpf = roberty.input("cpf");
const result = { status: "ok", cpf };
roberty.output(result);
}
main()
.then(() => process.exit(0))
.catch((error) => {
console.error("Run failed:", error);
process.exit(1);
});
Python
import sys
import roberty_code as roberty
def main() -> None:
print(f"Starting ({roberty.environment}, trigger: {roberty.trigger})")
cpf = roberty.input("cpf")
roberty.output({"status": "ok", "cpf": cpf})
if __name__ == "__main__":
try:
main()
except Exception as error:
print(f"Run failed: {error}", file=sys.stderr)
sys.exit(1)
Exception entry point with the SDK
const roberty = require("@roberty/code");
const { message, exitCode } = roberty.exception();
console.error(`Robot failed (exit code ${exitCode}): ${message}`);
Without the SDK
If you'd rather not add the dependency:
- Read
roberty-triggerto know the run's context. - If
roberty-args-file-pathexists, read the file and parse the JSON to get the arguments. - At the end, write the result (JSON) to the path in
roberty-output-file-path. - Exit with code
0on success.
import json
import os
args = None
args_file_path = os.environ.get("roberty-args-file-path")
if args_file_path:
with open(args_file_path, encoding="utf-8") as file:
args = json.load(file)
result = {"status": "ok"}
output_file_path = os.environ.get("roberty-output-file-path")
if output_file_path:
with open(output_file_path, "w", encoding="utf-8") as file:
json.dump(result, file)
Deprecated formats
The roberty:start and roberty:exception scripts in package.json (Node.js) and the fixed main.py and exception.roberty.py files at the root (Python) are deprecated. Move those declarations to roberty.json — for example, "entrypoint": "node src/index.js" in Node.js or "entrypoint": "main.py" in Python.
Best practices
- Clear logs: print the start, the key milestones and the end of the run.
- Fail loudly: on an unrecoverable error, throw or exit with a non-zero code. Don't report success while hiding an error.
- No secrets in code: don't hard-code passwords or keys in the repository.
- Idempotency: where possible, make the robot safe to run again — schedules and manual re-runs happen.
- Support every trigger: treat arguments as optional and always write the result, so the robot already answers webhooks and evaluations with no changes.
- Run it locally: keep a way to run the project on your machine (e.g. a
startscript orpython main.py). To simulate a trigger, set theroberty-*variables by hand.
Pre-deploy checklist
-
roberty.jsonat the root withentrypoint(Node.js: a shell command; Python: the relative path of the.py). - Node.js:
package.jsonat the root. Python: theentrypointfile exists, plusrequirements.txtif there are dependencies. - (Optional)
exceptionHandlerdeclared. - (Recommended)
$schemapointing to the public schema. - (Recommended) SDK installed:
@roberty/codeorroberty-code. - No secrets in the code.
- The process exits with code
0on success and non-zero on failure. - The robot reads the arguments when there are any and writes the result as JSON.
- (Optional) A
webhooksection declaringinputsandoutputs, if the robot is triggered through the API.