Scripts
A script in Reminix is a command your team can run safely from the app, the CLI, your own code or an AI agent. It has a name, an owner and a JSON Schema for its inputs. The schema becomes the form people fill in and the input agents send. Its code lives in versions. Every change is a new version, and runs use the published one.
Publishing a folder
Section titled “Publishing a folder”A script starts as a folder with a command your team already runs,
such as a Python program, a shell script or a Node CLI. To publish it,
run reminix publish in that folder. Reminix reads the folder and
works out how to run it:
| The folder has | Reminix runs |
|---|---|
pyproject.toml with one [project.scripts] entry |
that entry |
pyproject.toml with a package that has __main__.py |
python -m <package> |
package.json with one bin, else scripts.start, else main |
node <bin>, npm start, node <main> |
one .py, .js, .mjs, .cjs, .ts, .mts or .sh file |
that file |
several, one of them main.py, __main__.py, index.js, index.mjs, index.ts, main.sh or run.sh |
that one |
no such file, but one executable file with no extension that starts with #! |
that file |
The script takes its name from pyproject.toml or package.json, or
from the folder when neither names it. Reminix installs its
dependencies when you upload it (see
Dependencies and the machine). For a
script with inputs, give the command with a {name} where each input
goes:
reminix publish --dry-run # what Reminix found; uploads nothingreminix publish --command "python unlock.py {email}"If the folder doesn’t say how it runs, or says two things (such as two
scripts and no main.py), reminix publish stops and names what it
found. Pass --command, or add a reminix.json. Your agent can write
one for you.
Customizing with reminix.json
Section titled “Customizing with reminix.json”Add a reminix.json beside the code when you want more than the
defaults:
- a form with labels, examples and types for its inputs
- a description and tags
- the hosts and secrets it may use
- a longer timeout
- how to run and install code the folder doesn’t describe, such as Ruby, Go or a custom install
The reminix.json page lists every field.
{ "slug": "unlock-account", "name": "Unlock an account", "description": "Lets a customer sign in again after too many attempts.", "command": "python unlock.py {email}", "inputSchema": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "title": "Customer email", "examples": ["jane@example.com"] } } }}# unlock.py: the result goes to standard output, the log to standard error.import json, sys
email = sys.argv[1]print(f"unlocking {email}", file=sys.stderr)status = unlock(email) # your code, calling your app's admin APIprint(json.dumps({"unlocked": email, "status": status}))reminix init "python unlock.py {email}" writes this reminix.json
and a README.md for you. The reminix.json it writes has a string
input for each {name}. reminix init never writes code. Then fill in
each input’s title, type and description.
To help your team find the script, add tags
and fill in the README.md. Tags go in reminix.json, as in
"tags": ["support", "accounts"]. A script can have up to 10 lowercase
tags. The script’s page shows the README.
The command
Section titled “The command”Reminix runs the command directly, never through a shell, so an input can’t become another command.
-
Words are split on spaces.
'…'and"…"keep spaces inside one word. Characters such as$,|,>and*are ordinary text. For a pipeline, writesh -c '…'or put it in a.shfile. -
The first word is the program:
python,node,sh, or a file in the folder such as./tool. -
{name}is an input. A word that is only{name}becomes one argument. If the input is a list, it becomes one argument per item. Inside a word, as in--email={email}, Reminix puts the value in place. -
[ … ]is an optional part. If an input in it is empty, Reminix leaves the whole part out. Empty means missing, null,"", false or an empty list. A true/false input adds no argument of its own, so[--dry-run {dryRun}]adds--dry-runonly whendryRunis true. One optional part can’t hold another. -
An input outside
[ … ]has to appear inrequired. -
An input can’t go inside code you pass to an interpreter on the command line, because the interpreter would run it as code. Publishing refuses it. Pass the input as its own argument instead:
Instead of Write sh -c 'echo {name}'sh -c 'echo "$1"' _ {name}python -c 'print({name})'python -c 'import sys; print(sys.argv[1])' {name}node -e 'console.log({name})'node -e 'console.log(process.argv[1])' {name}perl -e 'print {name}'perl -e 'print $ARGV[0]' {name}ruby -e 'puts {name}'ruby -e 'puts ARGV[0]' {name}php -r 'echo {name};'php -r 'echo $argv[1];' {name}The rule applies to the interpreters in the table.
bash,zshanddashcount assh, andnode -p,--evaland--printasnode -e. It also applies behindenvor a full path such as/bin/sh. Versions published before this rule keep running.
Defaults and examples
Section titled “Defaults and examples”Two optional keys on an input help people run your script:
defaultfills the field in. Use it for a value that’s right most of the time.examplesshows the first example as a hint in an empty field. A Use example link fills it in. Use it to show the shape of a value without choosing one for the person.
"email": { "type": "string", "title": "Customer email", "examples": ["jane@example.com"]}A file input can ship a sample file instead. See Ship a sample file.
Inputs, output and the log
Section titled “Inputs, output and the log”Your code gets its inputs in three ways. Use whichever suits it:
- In the command, as above.
- As environment variables named
REMINIX_INPUT_plus the input’s name in capitals. For example,emailisREMINIX_INPUT_EMAIL, and an input namedaccountIdisREMINIX_INPUT_ACCOUNT_ID. Strings arrive as they are, and other values arrive as JSON. - All together as one JSON object, on standard input and in the file
named by
$REMINIX_INPUTS_FILE. Nested objects and lists are easiest to read this way.
#!/bin/sh# unlock.sh, run with "command": "sh unlock.sh"set -eemail=$(jq -r .email "$REMINIX_INPUTS_FILE")echo "unlocking $email" >&2jq -n --arg email "$email" '{email: $email}' | curl -sf https://api.yourapp.com/admin/unlock -H "Content-Type: application/json" -d @-Standard output is the run’s result. If it parses as JSON, Reminix keeps it as JSON. Otherwise Reminix keeps it as text. If the output is over 1 MB, Reminix doesn’t keep it, and the run still succeeds with no output.
Exit code 0 means the run succeeded. Any other exit code fails the run, and the last lines of standard error become its error. Standard error is the run’s log, and the run’s page shows it as the run goes.
Dependencies and the machine
Section titled “Dependencies and the machine”When you upload a version, Reminix installs its dependencies once:
requirements.txtwith pippyproject.tomlwithpip install ., when there’s norequirements.txtpackage.jsonwith npm, usingnpm ciwhen there’s a lock file and leaving out dev dependencies
During the install, the code can reach only the package registries. To
install some other way, set "install" in reminix.json to your own
command. Reminix runs it with sh -c in the folder. If the install
fails, the upload fails and shows the install’s output. Runs never
install anything, so they start fast.
Every run gets a fresh machine with Python 3.12, Node 22, sh, curl,
jq and pdftotext. Node runs .ts files directly. The machine has 1/4
of a CPU, 1 GB of memory and 4 GB of disk. Nothing carries over from
one run to the next.
Calling APIs
Section titled “Calling APIs”By default, a script has no network access. To call an API, list the API’s hosts and the secrets Reminix should add to requests to them:
{ "hosts": ["api.yourapp.com"], "secrets": { "ADMIN_KEY": { "hosts": ["api.yourapp.com"], "header": "Authorization", "format": "Bearer {secret}" } }}# No key in the code: Reminix adds the Authorization header on the way out.import json, os, urllib.request
request = urllib.request.Request( "https://api.yourapp.com/admin/unlock", data=json.dumps({"email": os.environ["REMINIX_INPUT_EMAIL"]}).encode(), headers={"Content-Type": "application/json"},)with urllib.request.urlopen(request) as res: print(res.read().decode())- Requests go out only to
hosts, and only over HTTPS. A request to any other host gets an HTTP 403 right away, with a body that says why. Every request is a line in the run’s log. Python’surllibandrequests,curland Node’sfetchwork as they are. - Reminix adds a secret only to requests that go to a host on both
lists: the secret’s
hostshere, and the hosts the secret’s value allows in the run’s environment. See Secrets. - The code never holds a secret’s value, except through
envVarsbelow. Don’t send a secret to an API that echoes credentials back in its response, because the response would show the secret to the code. formatis the header’s value,{secret}by default. Use it to add a scheme, as in"Bearer {secret}".$REMINIX_ENVIRONMENTis the name of the run’s environment, such asproductionorstaging. Use it to pick an API’s test or live base URL, and list both hosts inhosts.- To let the code read a secret, list it in
"envVars": ["NAME"]. The code then gets it as the environment variableNAME. This works only for a secret where a workspace owner or admin turned on “Let scripts read it as an environment variable”.
The script’s page shows each version’s hosts and secrets, so whoever publishes can see what it can reach.
Publishing
Section titled “Publishing”reminix upload ./unlock-account # uploads a draft versionreminix publish ./unlock-account # uploads a version and publishes itThe CLI packs the folder as it is. This is the script’s source:
every file git tracks, plus new files .gitignore doesn’t exclude.
Outside a git repository, the CLI packs every file. It always leaves out
node_modules, .venv, venv, __pycache__, .deps, .git and
.env. The packed folder can be up to 10 MB.
The first upload creates the script. A draft changes nothing until someone publishes it, which makes it the version runs use. The script’s owner or a workspace owner or admin can publish. When an agent connected through MCP publishes, it becomes a request that a person approves. A coding agent that runs the CLI with your own token acts as you, so the agent skill tells it to ask you to publish. To roll back, publish an older version again. Governance covers who can use a script, which runs need approval and second-person publishing.
To publish from your own code instead, use a personal access token with
scripts:write. One call does what reminix publish does: call
Upload a version with
publish: true, and add create: true for a new script. You pack the
folder yourself, as a base64 .tar.gz. Its README.md becomes the
script’s page. Publish a version
publishes a version you already uploaded. API keys can’t upload or
publish, because each version records the person who made it.
Archiving a script
Section titled “Archiving a script”Reminix never deletes a script. When you no longer need one, archive it by selecting Archive script on the script’s page. An archived script leaves the Scripts list, and nobody can run it. Its schedules and triggers skip it. Its runs and versions stay, so you can always see what it did. Its logs and files last as long as your plan keeps them. To find it again, tick Archived on the Scripts page. Select Restore to bring it back.
The script’s owner or a workspace owner or admin can archive and
restore it. You can’t archive a script while one of its runs is in
progress or waiting for approval. In the CLI, use
reminix scripts archive <slug> and reminix scripts restore <slug>.
Running it
Section titled “Running it”Once someone publishes a version, anyone in the workspace who may use the script can run it:
- In the app: open it under Scripts, fill in the form and select Run to see the output and the log.
- From the CLI:
reminix run unlock-account --input '{"email":"jane@example.com"}'prints the output. Add--logto print the log too. - From an agent: through the MCP server, every
published script is a tool named after the script, such as
unlock_account. The tool takes the script’s inputs. - In another environment: if your workspace has more than one environment, each of these ways can choose which one a run uses. See Environments.
- From your code:
reminix.run("unlock-account", { email: "jane@example.com" })with the TypeScript SDK, orreminix.run("unlock-account", {"email": "jane@example.com"})in Python. See Runs.