Scripts

Scripts are small programs you write once and run on your machine, or on a Nocarta Runner. Use them when you need to do something to your data that an automation or form can't — converting a spreadsheet, generating reports, cleaning up records, calling an HTTP API, packaging files.

Scripts never run on Nocarta's web servers. When a script runs on your machine, your inputs, outputs, and secrets never leave it during execution. When a script runs on a Nocarta Runner — a temporary machine Nocarta starts for you when no desktop app of yours is connected — the script, its inputs and its Tier 1 secrets are sent to that machine, which is destroyed afterwards. See Running on a Nocarta Runner.

When should I use a script?

You want to…	Use
Automate a website (click, fill, navigate)	Automation (Automation)
Digitize a paper document or photo	Quick Document Capture
Transform CSV/Excel/PDF/JSON files	Script
Generate a report from your data	Script
Call an external API and write results to a file	Script

Requirements

The Nocarta Desktop App is required to run scripts on your machine. Editing a script works anywhere. When you click Run in a normal web browser, the run is sent to your connected desktop app — or, when none is connected, to a Nocarta Runner that Nocarta starts for you. See Running a script.

Download Nocarta Desktop

---

Creating a script

Open Scripts → New Script and fill in:

• Name — what you'll see in the list. Pick something memorable.
• Description — a short note to your future self about what this script does.
• Kind — see the next section. Pick Node if you're starting from scratch.
• Run command — for Shell scripts, the command that runs your source file (e.g. python3 main.py). For Node scripts this is cosmetic — the desktop app runs your code on its built-in Node runtime regardless, so it's not shown on a Node script's page.
• Source filename — the name your source code gets saved as on disk during a run. main.py / convert.sh / extract.rb for Shell. For Node it's fixed to main.js and, like the run command, is cosmetic.
• Source code — the actual program. See the two examples below.
• Persist stdout/stderr to backend — off by default. When on, the text your script prints is saved to Nocarta and shown in the run's details once it finishes. When off, the printed text is not kept anywhere.
• Time limits for remote runs — how long a run may take when it is started from a browser, the API or an assistant. See Time limits.

The two kinds

You choose how your script will be executed on the desktop:

Node

Recommended for new scripts. Runs on the Node.js runtime that ships with the desktop app — nothing extra to install. Your computer doesn't even need Node installed.

Your source code must export an async function:

module.exports = async function ({ inputDir, outputDir, env, log }) {
  const fs = require('fs');
  const path = require('path');

  // Read inputs from inputDir, write outputs to outputDir.
  const data = fs.readFileSync(path.join(inputDir, 'input.csv'), 'utf8');
  fs.writeFileSync(path.join(outputDir, 'result.txt'), data.toUpperCase());

  log('Done!');
};

What you get in the function arguments:

• inputDir — folder containing any input files you attached to this run.
• outputDir — anything you write into this folder is collected and uploaded back to Nocarta when the script finishes.
• env — environment variables, including any secrets you've bound (see Secrets).
• log(message) — prints to the script's output stream.

Standard Node modules (fs, path, crypto, http, https, url, util, …) are always available via require(). For extra npm packages, see Package downloads.

Shell

Use this when you need a language other than JavaScript — Python, Ruby, bash, Go, anything. Spawns a process using your system shell.

Important: on your machine, the runtime must be installed and on PATH. If you write run command: python3 main.py, Python 3 must be available when you click Run. On a Nocarta Runner only bash, python3 (standard library, no pip) and curl are guaranteed — nothing else. See Running on a Nocarta Runner.

Your source code is whatever the run command expects. Example for python3 main.py:

import sys, os, csv

input_path  = os.path.join(os.environ.get('PWD', '.'), 'input', 'input.csv')
output_path = os.path.join(os.environ.get('PWD', '.'), 'output', 'result.txt')

with open(input_path) as f:
    rows = list(csv.reader(f))

with open(output_path, 'w') as f:
    f.write(f"{len(rows)} rows processed\n")

print("Done!", file=sys.stderr)

Same input/output folder convention as Node — your script reads from input/ and writes to output/ inside its working directory.

---

Parameters — asking for input at run time

Instead of hardcoding values (a file to process, a template name, a server URL) at the top of your source, declare parameters. Each one becomes a field in a small dialog that pops up every time you click Run, so the same script can target different inputs without ever editing the code.

Add them in the script's Parameters editor. Each parameter has a name (UPPER_SNAKE_CASE — it becomes an environment variable), a type, a label, optional help text, an optional default, and a required flag.

Types

Type	What the user sees in the dialog	How you read it in the script
text	single-line text box	env.NAME
multiline	multi-line text area	env.NAME
number	number input	env.NAME (as a string)
date	date input (YYYY-MM-DD)	env.NAME
email	email input	env.NAME
regexp	text, validated as a regular expression	env.NAME
select	dropdown of the options you define	env.NAME
file	file picker	inputDir/<NAME> — see below

Every type except file arrives as an environment variable. In a Node script, read it from env.MY_PARAM (or process.env.MY_PARAM); in a Shell script, from $MY_PARAM. A blank optional field falls back to its default; a blank required field stops the run with a clear message.

File parameters

A file parameter shows a file picker in the run dialog — this is the dialog you see when a script needs you to choose, say, a spreadsheet. The file you pick is not an environment variable. It's downloaded into your working folder as inputDir/<parameter name>. So a file parameter named XLSX_FILE is read like this:

module.exports = async function ({ inputDir }) {
  const fs = require('fs');
  const path = require('path');
  const buf = fs.readFileSync(path.join(inputDir, 'XLSX_FILE'));
  // …
};

Parameter names can't start with NOCARTA_ or ELECTRON_ (reserved), and can't clash with the env-var name of a bound secret — parameters and secrets share the same environment.

---

Binding secrets

If your script needs an API key, password, or database URL, don't paste it into the source. Instead:

1. Store the value in your Vault (e.g. a Secret named "Stripe Live Key").
2. Open the script's Secrets tab and bind that Vault entry to an env var name, e.g. STRIPE_KEY.
3. Access it from your script via process.env.STRIPE_KEY (Node) or os.environ['STRIPE_KEY'] (Shell).

Only the secrets you've explicitly bound are visible to the script. Everything else in your Vault stays out of reach.

The value is automatically blanked from any output the script prints — if your script accidentally log(STRIPE_KEY), what gets stored on the server is [REDACTED:STRIPE_KEY], never the real value.

Tier 1 and Tier 2 secrets

Your Vault holds two kinds of secret, and the difference decides where a script that uses them can run:

• Tier 1 secrets are protected by Nocarta. They work everywhere a script can run — on your machine and on a Nocarta Runner.
• Tier 2 secrets are protected by your master password, which only you know and only your browser can use. A script that binds a Tier 2 secret runs only on your own machine, with the desktop app open and your vault unlocked. If you send such a script to a Nocarta Runner, it is refused up front with that explanation — nothing is started.

Want a script to run anywhere? Bind Tier 1 secrets to it.

---

Running a script

There are three ways to start a script:

1. The Run button inside the Nocarta desktop app. The script runs on that machine, with no time limit.
2. The Run remote button, in a normal web browser or in the desktop app. A dialog first tells you where the run will go — your connected desktop app, one of your machines, or a Nocarta Runner that Nocarta starts for you. Its Run on list lets you send this one run somewhere else; the script's own setting doesn't change.
3. From an assistant or the API. See AI Integration and the API Guide. These runs follow the script's setting, unless the request names another place for that run.

Choosing where a script runs

Runs you start from a browser, the API or an assistant go to one of three places:

• Automatic — your connected desktop app takes the run. When none is connected, Nocarta starts a Nocarta Runner.
• A Nocarta Runner — always a Nocarta Runner, even while the desktop app is open on your computer.
• This machine: name — one of your own machines, and nothing else.

You choose in three places:

1. For your whole account: Settings → Profile and Connections → Where my automations and scripts run. This applies to your automations too.
2. For one script: the When started remotely, run on field in the script form. My account setting (the default) follows the account choice above.
3. For one run: the Run on list in the dialog that opens when you press Run in a browser. It starts on the script's setting.

The same Settings section lists your machines: every computer where the desktop app has connected with desktop execution on, whether it is connected right now, and whether it runs as a normal desktop app or in service mode. You can rename a machine, or Forget it. Forgetting a machine removes it from the choices: if your account or a script was set to run there, it goes back to Automatic (the script then follows your account setting, and its form tells you so). If the desktop app connects from that machine again, it appears in the list again.

A machine you chose must be connected. While it isn't, runs aimed at it are refused with a message that names it — Nocarta can't switch your computer on, so it doesn't wait. Open the desktop app on that machine, or pick another place.

Wherever it lands, the run proceeds the same way:

1. Your source code and any input files are downloaded into a working folder on that machine.
2. The script executes (Node or Shell).
3. Everything written to output/ is collected and uploaded back to Nocarta.
4. The run is marked completed (exit 0) or failed (any non-zero exit).

The script's page shows the last run's status and exit code live. Output files appear under the Runs tab and on the Runs page with a Download link. If you turned on "Persist logs", the printed output is in the run's details once it finishes.

While a script runs on your desktop, nothing else is dispatched to your account — one run at a time, scripts and automations alike.

Stopping a run

Long-running script? Open the Runs page and click Stop on the run. The machine running it sends the script a stop signal, then force-kills it 5 seconds later if it hasn't shut down on its own. If the run is on a Nocarta Runner, you can also choose Stop and shut down the Nocarta Runner.

---

Time limits

Time limits apply to remote runs only — runs started from a browser, the API or an assistant. Pressing Run inside the desktop app has no time limit.

You set them per script, in the script form:

Where the run lands	Default	Range
Nocarta Runner	5 minutes	up to 30 minutes
Your machine (connected desktop app)	5 minutes	any value, or no limit

A run that reaches its limit is stopped and marked failed. The limit that applied is shown in the run's details on the Runs page. Need more than 30 minutes? Run the script on your own machine — see below.

---

The Runs page

Open Runs in the main menu. It lists every run of your scripts and your automations, newest first, with its status, where it ran (your machine or a Nocarta Runner), when it started, how long it took and how it was started (web page, desktop app, API, assistant…). Filter by kind, status or script.

Open a run for its details: parameters, exit code, the time limit that applied, logs (when the script keeps them) and its output files with Download links.

From the list or the details you can:

• Stop a running or waiting run.
• Stop and shut down the Nocarta Runner when the run is on one.
• Shut down the Nocarta Runner from the panel at the top of the page — available whenever one is up for your account, even when nothing is running. The next remote run starts a new one.
• Delete a finished run, with its logs and output files.

---

Running on a Nocarta Runner

When you start a script from a browser, the API or an assistant and no desktop app of yours is connected — or when you chose A Nocarta Runner as the place to run (see Choosing where a script runs) — Nocarta starts a Nocarta Runner: a temporary machine that signs in as you, runs the script and is destroyed afterwards. What it offers:

• Node scripts are fully supported, npm packages included. Packages are installed fresh each runner session. As on the desktop, packages that need install scripts or native builds don't work, devDependencies aren't installed and lockfiles aren't used.
• Shell scripts get a minimal Linux with bash, python3 (standard library only, no pip) and curl. Nothing else is guaranteed.
• Nothing persists between sessions — no files, no caches, no installed packages.
• Tier 1 secrets work. A script that uses Tier 2 (master-password) secrets is refused up front — see Tier 1 and Tier 2 secrets.
• Time limit: 5 minutes by default, up to 30 — see Time limits.

Need more tools, or longer runs? Use your own machine

Install whatever the script needs on a machine you control, run the desktop app there in service mode, and it appears under your machines in Settings. Choose This machine: name for your account or for one script, and the browser, API and assistant runs that follow that choice go to it — never to a Nocarta Runner. See Choosing where a script runs and the Desktop App Guide.

---

Package downloads — please read carefully

By default, a Node script can use only Node's built-in modules. If you need something from the npm registry (e.g. axios, exceljs, uuid), you can turn on Allow this script to download packages before it runs in the Package downloads section of the script form.

This switch is off by default for a reason. Before turning it on, you must read and acknowledge the danger modal that appears. Here's what's in it:

Once enabled, the form shows a package.json field. Put your dependencies there as a JSON object — exact versions only, no ranges:

{
  "dependencies": {
    "uuid": "9.0.1",
    "axios": "1.6.2"
  }
}

In your source code, require() them the normal way:

module.exports = async function ({ outputDir }) {
  const { v4: uuidv4 } = require('uuid');
  const axios = require('axios');
  // …
};

The first run with a new dependency list takes a moment (downloading packages). Subsequent runs on your machine are fast — the packages are reused from cache. On a Nocarta Runner nothing persists, so packages are downloaded again each runner session.

---

Common questions

Where are my output files saved?

After the run finishes, they appear in the Runs tab of your script, with a Download link. They're stored in Nocarta and tied to that specific run.

Why is my Shell script failing with "command not found"?

Shell scripts use the runtimes installed on the machine that runs them. On your machine, if you wrote run command: python3 main.py and Python 3 isn't on your PATH, the run fails. Either install it, switch to a runtime you have, or use a Node script (which has no system requirements). On a Nocarta Runner only bash, python3 and curl exist — a script that needs anything else must run on your own machine.

I changed my source code — is the old version gone?

No. Every save creates a new version. Past runs always reference the exact version they used. You can go back to any older version if needed.

Can I see what my script prints?

During a run, the script's page shows its status and exit code — not the printed output. To read what the script printed, turn on Persist stdout/stderr to backend; the logs then appear in the run's details on the Runs page once it finishes. Off by default to avoid storing sensitive data accidentally.

Can I run a script on a schedule?

Not yet — scripts are started manually, from the desktop app, a browser, the API or an assistant. Scheduling is on the roadmap.