# Self-hosted runners

> What Pullfrog's shell sandbox needs from a self-hosted runner on a VM, in a container, or on Kubernetes.

Pullfrog runs on self-hosted runners. The [shell sandbox](https://pullfrog.com/docs/security#shell-environment-scrubbing) needs `CAP_SYS_ADMIN`, which runner kinds expose differently:

- **VM and bare-metal runners** work with no setup. Pullfrog uses passwordless `sudo` to create the namespace, as it does on GitHub-hosted runners.
- **Containerized and Kubernetes runners**, such as [actions-runner-controller](https://github.com/actions/actions-runner-controller), usually have neither `CAP_SYS_ADMIN` nor `sudo`. Pullfrog first creates an unprivileged user namespace, which grants the capability inside that namespace only. A stock runner pod needs no configuration.

## Runner requirements

- **System tools in a root-owned directory.** Pullfrog only uses `sudo`, `env`, `unshare`, `setpriv` and `bash` from a `PATH` directory that root owns and no other user can write, because anything a shell command can write it could replace. The directories `/usr/bin` and NixOS's `/run/wrappers/bin` and `/run/current-system/sw/bin` qualify. If `unshare` or `setpriv` lives only in a user-writable directory, such as a Homebrew prefix, shell commands stay off for that run and the log says why.
- **Ephemeral runners.** Use runners that take one job each. On a runner that keeps its workspace between jobs, what the agent leaves in the checkout, `.git` included, is still there when the next job's `actions/checkout` runs git in it.
- **Passwordless `sudo` for subscriptions.** Subscription credentials need it to set up `/var/lib/pullfrog/`. On a runner without it, Pullfrog skips them and uses an API key if one is available.

## Container fallback

On a runner with neither `CAP_SYS_ADMIN` nor `sudo`, shell commands run in an unprivileged user namespace.

### Guarantees

A shell command still cannot read another process's environment variables, reach Pullfrog-managed files, undo the filesystem protections or signal the Pullfrog process. The kernel blocks cross-namespace environment reads on its own.

One thing differs: inside a user namespace the container's `/proc` cannot be replaced, so a shell command can see which processes run and their command lines. Pullfrog never puts credentials on a command line.

### Requirements

The fallback needs a pod that may create user namespaces and a node kernel that permits them. It does not engage in these cases:

- **Pod seccomp.** A pod hardened to `seccompProfile: RuntimeDefault`, which the Pod Security Standards `baseline` and `restricted` profiles require, cannot create user namespaces. Stock runner pods are unaffected, because the [ARC chart](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) sets no `securityContext` by default.
- **Root pod without `CAP_SETFCAP`.** A container that runs as root needs this capability to map user IDs. Pods that run as a non-root user, the ARC default, are unaffected.
- **Node kernel.** Most distributions permit unprivileged user namespaces, including Debian, Ubuntu 22.04 and earlier, RHEL 8 and 9, Amazon Linux 2023 and GKE COS. Ubuntu 23.10 and 24.04 restrict them by default (`kernel.apparmor_restrict_unprivileged_userns`), and RHEL and CentOS 7, Bottlerocket and Talos disable them (`user.max_user_namespaces=0`).

If no method provides isolation, the run continues without a shell or the `gh` tool, and the log names these causes. Pullfrog never runs shell commands unsandboxed in CI.

The agent can still read and edit files, commit, push, review and comment. It is told why it has no shell, and says so when that leaves a result unverified, such as a fix whose tests it could not run.

## Git commands

Pullfrog's own git commands run in the PID namespace where the runner allows one, and otherwise in a path sandbox: Landlock on Linux, Seatbelt on macOS. Authenticated fetches and pushes run in the path sandbox on every runner that supports it.

The path sandbox limits a git command and anything it starts:

| Access | Limit |
| --- | --- |
| Writes | The checkout, cross-repository checkouts and a private temp directory |
| Reads | System directories, git's own installation, the object stores the checkout borrows from, and the system and global git config with the files and CA bundles it names |
| Other processes | No reading another process's environment variables, and no connecting to a Unix socket such as `/var/run/docker.sock` |
| Programs, on macOS | Git itself and the `sh`, `git-lfs` and `node` that hooks, LFS and authentication need |

Landlock needs Linux 5.13 or later with Landlock enabled. The command `cat /sys/kernel/security/lsm` lists `landlock` when it is. On a macOS version whose Seatbelt rejects one of the sandbox's rules, git runs without that rule if it still works, which only narrows what it can reach.

> A CI runner that provides neither isolation stops the run before the agent starts, and the comment says why. This includes Linux containers whose kernel lacks Landlock. Windows runners are not supported.
