Docs
Docs menu

Where to run a runner

A runner gives its agents everything its user can reach. How to pick the machine or account it runs on.

A runner runs Claude Code directly on its machine, as the OS user that started moru-runner. There’s no sandbox. An agent can do whatever that user can:

  • read and write the user’s files, including other checkouts, SSH keys, cloud credentials and the runner’s own key and token (in the cache directory, under .runner/);
  • use the machine’s network, including the local network and services on localhost;
  • run any program installed on the machine.

Claude Code runs unattended, in bypassPermissions mode, so it doesn’t ask before it acts. It also reads text other people wrote: the request, the repository’s files, the discussion, web pages it fetches. Instructions hidden in any of them can steer it. This is the same risk as running claude -p --permission-mode bypassPermissions in a checkout yourself.

What an agent still can’t do is change a repository on the node. Its task token lets it push only to its own scratch repo, and a change reaches a branch only when a person approves it.

Pick a machine#

Run the runner on a machine, or under a user account, that you’re happy for an agent to use. Some ways to do that:

  • Your own laptop or workstation, as you. The simplest setup. Agents build and test with your toolchains and your Claude Code login, the way you would. They can also reach everything you can.
  • A separate user account. Create a user for the runner and start it as that user. Agents can’t read your home directory, and you install only the toolchains and credentials the runner needs.
  • A VM or a container you set up. A virtual machine, a dev container or a cloud instance with only what the repositories need. Anything the agent does stays inside it. Install git, the runner and the toolchains, then register and start the runner there as you would anywhere else.

Jobs on one machine#

Jobs on the same runner run as the same user, so they can see each other. With --max-jobs above 1, the lanes of a Bake-off could read or change each other’s working copies. They’re all your own work, since a runner only takes jobs its owner started.

CI jobs#

A runner also runs CI jobs: the commands in a repository’s workflow files, for runs that are yours. They run the same way agents do, as the runner’s user, with no sandbox, and the commands come from the repository. Anyone who can write to it can change them in a change, and that change’s CI runs on the runner of the person the run is for: the change’s author, or the person who started the agent.

To keep CI off a machine, start its runner with --kind implement --kind review. To run only CI on a machine, use --kind ci:

moru-runner run --kind ci --cache-dir /var/lib/moru-ci

For machines that start for one job and go away, such as an autoscaling group, a Kubernetes Job or a spot instance, --once takes one job, runs it and exits. It also lets a job of another CI system run a Moru runner while you move a repository over.

A CI job’s secrets come from the runner’s ci.toml (see CI secrets). Its scopes decide which jobs the runner gives a secret to, not what code on the runner can reach. A step runs as the runner’s user, so it can read other processes’ environments (/proc/<pid>/environ on Linux, ps eww elsewhere), the runner’s token.json and runner.key, and every file ci.toml names. A runner process that holds a secret in its environment holds it for every job it runs.

Keep secrets that can deploy or publish on a runner of their own, under its own OS user, started with --only-named, and scope them to what you trust, such as pushes to main and tags. That runner takes only CI jobs that name it (runs-on: { runner: <name> }), and only from pushes and manual starts, never a change’s runs, so code nobody has reviewed doesn’t run there. Scheduled runs it takes only with --schedules, since anyone who can change the default branch decides what they run. It takes no agent jobs. A runner started with only --kind ci takes every CI job of its owner’s it can, changes’ runs included, and their code can read what it holds. See Deploy runners.

Containers on a CI runner#

Jobs with container:, services: or Docker actions need docker or podman on the runner’s machine, usable by the runner’s user (see Containers). The runner finds it by itself: install one and start it, and the runner offers container jobs from its next request for work, without a restart. On a Mac, Docker Desktop, OrbStack, colima or podman machine all work. Keep the runner’s --cache-dir in a folder the engine shares, such as one under your home directory, and its --work-dir too if you set one.

A container gives a job its own tools; it doesn’t isolate the job. The job decides what its container mounts, and its options can mount any folder of the machine or the Docker socket. Whoever can use the engine controls the machine: on Linux, a user in the docker group, or one that can reach a rootful Docker’s socket, can become root with one docker run. If a runner’s user shouldn’t be root, use rootless podman or rootless Docker, or keep the runner off container jobs with --container-cli none.

With rootful Docker on Linux, files a container writes as root land in the job’s folders owned by root. The runner gives them back to its own user at the end of the job; an image without sh, find and chown can’t, and the log warns that files may be left.

Credentials#

Agents use whatever Claude Code finds for the runner’s user: its login, or ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN in the runner’s environment. Since the agent runs as the same user, it can read that credential too. Use a key or token you’re prepared to rotate if a run goes wrong.

Claude Code’s settings, hooks and MCP servers for that user apply to agent runs as well. Keep that in mind if you run the runner as yourself.

Command menu
Search for a page, repository, change or request, or run a command