Self-hosted runners
Pullfrog runs on self-hosted runners. The shell sandbox needs CAP_SYS_ADMIN, which runner kinds expose differently:
- VM and bare-metal runners work with no setup. Pullfrog uses passwordless
sudoto create the namespace, as it does on GitHub-hosted runners. - Containerized and Kubernetes runners, such as actions-runner-controller, usually have neither
CAP_SYS_ADMINnorsudo. 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,setprivandbashfrom aPATHdirectory that root owns and no other user can write, because anything a shell command can write it could replace. The directories/usr/binand NixOS's/run/wrappers/binand/run/current-system/sw/binqualify. Ifunshareorsetprivlives 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,
.gitincluded, is still there when the next job'sactions/checkoutruns git in it. - Passwordless
sudofor 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 Standardsbaselineandrestrictedprofiles require, cannot create user namespaces. Stock runner pods are unaffected, because the ARC chart sets nosecurityContextby 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.

