Notiamo can start an AI agent on the open comments and tasks of a project. The agent makes the changes, and a person on your team approves them. A run can happen on Notiamo’s servers, or on a computer you own. This page is about the second way: the runner, a small program you install on your machine. It is for the agency team.

What the runner is

The runner waits for the agent runs your organization queues in Notiamo. For each run it clones the repository (or connects to the WordPress site), starts Claude Code with the run’s instructions, sends Notiamo what the agent does, and reports when it ends.

  • It holds no Claude credential. It starts the claude program already on the machine. The runner’s sessions use their own config folder, so they stay apart from yours. The sign-in itself is Claude Code’s, kept by Claude Code.
  • It is not a Claude login inside Notiamo. Notiamo never sees or uses your Claude account. The runner only runs your own Claude Code, on your machine, for your own work.

Install it

You need:

  • Node.js 22 or later;
  • Claude Code 2.1.314 or newer;
  • git 2.31 or newer;
  • on Linux and WSL2: bubblewrap and socat (Debian or Ubuntu: sudo apt install bubblewrap socat). On macOS there is nothing more to install.

Then:

  1. In Notiamo, open Settings › Agent runs. On the Runners card, press New runner and give it a name. Copy the token. It is shown once.
  2. On the machine, run:
npx @notiamo/runner init
  1. Paste the token. init checks that Claude Code works, runs Claude Code’s sign-in for the runner, then installs the service and starts it.
  2. On the project, set Where the agent runs to Own machine.

When init ends, the runner is running. It starts again by itself after a login or a restart.

Commands

Command What it does
npx @notiamo/runner init Sets up the runner: token, Claude Code sign-in, install and start the service.
npx @notiamo/runner@latest update Moves the runner to the newest version. The token, the name and the sign-in stay.
npx @notiamo/runner status Says whether the service is installed and running, and shows the last log line.
npx @notiamo/runner logs Shows the last 50 lines of the log.
npx @notiamo/runner stop Stops the service until the next login or boot.
npx @notiamo/runner uninstall Removes the service. The runner’s folder stays.
npx @notiamo/runner env <projectId> Makes or shows the env file this machine gives the runs of one project.
npx @notiamo/runner start Runs in the foreground. The service runs this; you rarely need it.

The service is a launchd agent com.notiamo.runner on macOS, a Scheduled Task “Notiamo runner” on Windows, and a systemd user unit notiamo-runner on Linux.

Two runners on one machine

npx @notiamo/runner init --profile staging sets up a second, separate runner. It has its own folder (~/.notiamo-runner/profiles/staging) and its own service. Add --profile staging to every command of that runner. A profile name has letters, digits and dashes, 1 to 32 characters.

What the agent can and cannot touch

Each run gets its own Claude Code settings file. Three things keep the agent in its place.

File tools stay in the run folder. Claude’s own file tools (read, edit, write, search) refuse anything outside the folder of the run. Any call that would ask for permission is refused, because nobody is there to answer.

Shell commands run in the operating system’s sandbox. On macOS (Seatbelt) and on Linux or WSL2 (bubblewrap and socat), every command the agent runs in a shell is confined. If the sandbox cannot start, the run does not start.

No credential of the machine reaches the agent. Claude Code gets only a short list of environment variables (PATH, HOME, USER, LOGNAME, SHELL, LANG, LC_ALL, LC_CTYPE, TERM, TMPDIR, TZ, XDG_*, the proxy and certificate settings) plus the run’s own. It never gets SSH_AUTH_SOCK, GH_TOKEN, GITHUB_TOKEN, NPM_TOKEN, AWS_* or ANTHROPIC_*. The agent’s git sees no global or system git config.

What the shell sandbox allows and denies:

  • Reads denied: the folders of other projects (other runs at the same time included), the runner’s own files, and your credential files and folders (SSH keys, cloud logins, package registry logins, git credentials).
  • Writes allowed: only in the run folder and in the project’s package cache folder next to it. The run’s .git/hooks and .git/config are read-only.
  • Network allowed: GitHub, npm, Notiamo, the WordPress site (for a WordPress run) and the hosts you add under Extra hosts the agent may reach on the Runners card. Everything else is refused.

The agent never pushes and holds no credentials. The runner pushes the run branch itself after the agent’s work.

When a run ends, the runner stops every process the agent left behind, such as a dev server.

The keychain on macOS

The macOS sandbox does not fully close the keychain. So keep no GitHub login in the keychain of the user that runs the runner (init warns when it finds one). The safest setup is a dedicated macOS user with its own keychain.

Windows

Plain Windows has no shell sandbox. Text in a comment could then make a run execute any command as you. Run the runner inside WSL2. On plain Windows the runner does not start unless you add "allowUnsandboxed": true to its config.json; do that only on a machine that holds nothing else.

Several runs at once

On the Runners card you set Runs at once: 1 to 3. Each run uses your Claude plan, so keep the number to what the plan has room for. One project never runs twice at the same time: a second run on the same project waits for the first.

Each run at the same time has its own slot folder. A run’s sandbox cannot read the other slots.

A runner for one client

When you make a runner, you can limit it to one workspace under Runs for. It then takes only that client’s runs. To set it up on the client’s computer: install Claude Code there, run npx @notiamo/runner init, and paste the runner’s token. The Claude login on that computer pays for the runs, so sign in with the account that should pay.

Setup and test commands

A clean clone has no installed packages. Tell the agent how to install them and how to test. Open the project’s agent settings and fill in Setup command and Test command, one line each.

  • The agent runs the setup command once, before its first change. Example: pnpm install --frozen-lockfile.
  • The agent runs the test command before each commit. A change that fails it is fixed or undone. Example: pnpm typecheck && pnpm lint.
  • The agent runs both itself, in the same sandbox as its other commands. The package registry must be on the allowed hosts. GitHub and registry.npmjs.org are there by default. Add any other one (PyPI, crates.io, a private registry) under Extra hosts the agent may reach on the Runners card.
  • Each project has a package cache folder next to its clone. npm, pnpm, Yarn, Corepack, Bun, pip, uv and Composer keep their caches there, because the sandbox closes the usual places in your home folder. The folder stays between the runs of the project and goes away with the clone. It does not exist on plain Windows.
  • Keep the test command light. A test that needs Docker cannot run. A test that needs a database can run only when the project’s env file points at one you keep running (see below).

The agent commits as “Notiamo agent”, one plain line per item. The runner turns off Claude Code’s “Co-Authored-By” trailer and “Generated with” line, so the repository shows no AI co-author.

An environment for your own projects

A run on a GitHub project gets a clean clone and nothing else. For a software project of your own, the tests may also need a database, a file store, a mail catcher and a .env. The runner machine gives them to the runs of one project with a plain file:

npx @notiamo/runner env <projectId>

<projectId> is the last part of the project page’s address in Notiamo. The command makes ~/.notiamo-runner/env/<projectId>.env, readable by you only, and prints the path. Put one KEY=VALUE per line. The next run of that project gets the variables in its shell, and the agent is told their names, never the values. Remove the file to take them away. The file never leaves the machine: Notiamo does not know it exists.

With the file present, the run’s shell may also reach services on 127.0.0.1 on macOS: your Postgres, a file store, a dev server. You keep them running; the agent cannot start them, and Docker stays out of its reach. On Linux the sandbox has its own network, so 127.0.0.1 there is not the machine’s: bind the services to the machine’s network address and add that host under Extra hosts the agent may reach.

Rules:

  • Development and test values only. The agent runs shell commands and can read every variable. Never a production key, never a password you use elsewhere.
  • PATH, HOME, the proxy and certificate variables, NODE_OPTIONS, NODE_TLS_REJECT_UNAUTHORIZED, NOTIAMO_*, GIT_*, CLAUDE_* and ANTHROPIC_* are ignored, and the log says so. The file can change what the agent’s commands see, never how Claude Code talks to Anthropic and Notiamo.
  • Values of 6 characters or more are masked as [secret] in the transcript Notiamo receives. Short values (1, true) are not.
  • Keep Runs at once at 1 when the projects of a runner share a database through their env file. Two runs at the same time would run their tests on the same database.

WordPress sites

The connection is on the project’s Website access card: an application password, and optionally SSH or FTP. The runner remembers the SSH server’s key on its first visit and refuses a server that shows another key later. A run goes like this:

  1. Backup before. With SSH the runner exports the database and uploads it to Notiamo, compressed, 200 MB at most. Notiamo keeps it for 30 days. With FTP or the API only there is no backup.
  2. The agent works through the allow-list below.
  3. Site check after. The runner opens the site and checks that it still answers.
  4. Restore on failure. If the check fails, the runner restores the database.

What the agent may run with wp-cli, per group (set on the project):

  • Content: post *, term *, menu *, media import, option get, option update.
  • Database: search-replace (the old and the new text only; it never touches the users or the options tables), cache flush, rewrite flush, transient delete.
  • Plugins and themes: plugin and theme with list, activate, deactivate, update.
  • Information: core version, site list, db size.
  • Files: no wp-cli command; the agent uses its file tools. They write styles, scripts and other files the server does not run.
  • PHP files (off by default): the file tools may also write PHP. A PHP file is code that runs on your server, and a WordPress run has no approval step: the change is live at once. Turn it on only for a site where you trust everyone who can write a comment.
  • Never, unless you choose “Allow everything”: eval, eval-file, shell, user *, db query|import|reset|drop|export, plugin install, theme install, core update|download.

What is stored where

Everything lives in ~/.notiamo-runner.

Path What it holds
config.json Notiamo’s address, the runner’s name and the runner token. Readable by you only.
claude/ Claude Code’s config folder for the runner: its sign-in and sessions.
projects/ The working copies of your projects, one folder per project in each slot. A project not used for the number of days set on the Runners card is removed; the next run clones it again.
git/ The runner’s own copies of your repositories. The agent can neither read nor write this folder.
env/ The env files you made, one per project.
runs/ The Claude Code settings of each run in progress. No secret. Deleted when the run ends.
runner.log What the runner did, with no secrets.
state.json The ids of the runs in progress. After a restart, each is reported to Notiamo as failed.

The secrets of a run (WordPress passwords, the run’s own tokens) come from Notiamo with the run and live only in memory. The agent gets them as environment variables, never in a file. What the agent prints is cleaned of them before the transcript is uploaded.

The runner never uses the machine’s git credentials. Each run gets from Notiamo a GitHub token that works for one hour and for the run’s repository only. The runner keeps it in memory and uses it for its own fetch and push. Notiamo opens and merges the pull request.

Stop a runner

On the Runners card, press Disable to pause a runner, or Delete to remove it. A deleted runner’s token stops working at once.