Skip to main content
Roberty Studio
CODECode

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.

KeyRequiredDescription
entrypointYesHow Roberty starts the robot. Node.js: a shell command. Python: the relative path of a .py file.
exceptionHandlerNoRuns when the entrypoint ends with an error, in the same format as the entrypoint. See Exception entry point.
blockParallelNotrue makes the project run alone on the device. Default: false. See Exclusive execution.
webhookNoThe webhook trigger's contract: the keys the robot reads and writes. See The webhook section.
$schemaNoThe URL of the public JSON Schema, for autocomplete and validation in the IDE. Ignored on deploy.

A complete example:

json
{
"$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 entrypoint is required and cannot be empty.
  • Python: paths are relative to the project root, must end in .py and 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.
  • blockParallel must 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:

FieldRequiredDescription
nameYesThe key's name. It cannot be empty and must be unique within the list.
typeNoFree text to guide the integrator (string, number, object…). Default: any. Not validated when the run is triggered.
requiredNoIn 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.
descriptionNoFree 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.json at the root, with entrypoint as 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 the PATH (e.g. node src/index.js, npm run start, npx tsx src/index.ts).
  • package.json at the root, used to install the dependencies with npm or yarn. No particular script is required in it.
json
{
"$schema": "https://api.roberty.app/v4/public/schemas/code/roberty.json",
"entrypoint": "node src/index.js"
}

Python project​

  • roberty.json at the root, with entrypoint pointing to the starting .py file. Its name and location are up to you; the file must exist and is syntax-checked (py_compile) on deploy.
  • requirements.txt at 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.
json
{
"$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:

VariablePresent inDescription
roberty-environmentEvery runproduction or preview.
roberty-triggerEvery runmanual, schedule, webhook or evaluation.
roberty-output-file-pathEvery runThe path of a file where the robot can write its result (JSON).
roberty-args-file-pathwebhook and evaluation onlyThe 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-path is read back by the platform: in evaluations, it is compared with the expected output; in webhooks, it is returned to the integrator in response when 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 0 means success. Any other value marks the run as failed. Exit with a non-zero code on errors — unhandled exceptions already do.
  • stdout and stderr become 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 entrypoint fails. 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-path holds the error's details:
json
{
"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.
json
{
"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:

LanguagePackageInstallImport
Node.js ≥ 18@roberty/codenpm install @roberty/codeimport roberty from "@roberty/code" or const roberty = require("@roberty/code")
Python ≥ 3.9roberty-codepip install roberty-codeimport roberty_code as roberty

The API is the same in both languages and can be called anywhere in your code:

MemberWhat it does
roberty.trigger"manual", "schedule", "webhook" or "evaluation" (null/None outside Roberty).
roberty.environment"production" or "preview".
roberty.isRoberty / roberty.is_robertytrue 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

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

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

js
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:

  1. Read roberty-trigger to know the run's context.
  2. If roberty-args-file-path exists, read the file and parse the JSON to get the arguments.
  3. At the end, write the result (JSON) to the path in roberty-output-file-path.
  4. Exit with code 0 on success.
python
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 start script or python main.py). To simulate a trigger, set the roberty-* variables by hand.

Pre-deploy checklist​

  • roberty.json at the root with entrypoint (Node.js: a shell command; Python: the relative path of the .py).
  • Node.js: package.json at the root. Python: the entrypoint file exists, plus requirements.txt if there are dependencies.
  • (Optional) exceptionHandler declared.
  • (Recommended) $schema pointing to the public schema.
  • (Recommended) SDK installed: @roberty/code or roberty-code.
  • No secrets in the code.
  • The process exits with code 0 on success and non-zero on failure.
  • The robot reads the arguments when there are any and writes the result as JSON.
  • (Optional) A webhook section declaring inputs and outputs, if the robot is triggered through the API.