Isolation and egress

Every job runs on your server, so HookCI confines it. This page covers what the agent sets up per job and how to widen network access when a job needs it.

Process isolation

With --isolation auto (the default) or --isolation systemd, each job runs:

• as the unprivileged user hookci-run, created by the installer,
• in a systemd transient unit,
• under the slice hookci.slice, so all CI work is grouped and accounted together,
• with limits for CPU, memory, timeout, and tasks.

State lives in /var/lib/hookci (mode 0700). Jobs do not run as root.

Limits

Set limits for all jobs, and override them per job:

checks:
  limits: { cpus: 2, memory: 4G, timeout: 15m, tasks: 512 }
  jobs:
    test:
      run: npm test
      timeout: 20m
      limits: { memory: 6G }

A job that exceeds memory or tasks is stopped by the kernel through its cgroup. A job that exceeds timeout is stopped by the agent. Field details are in the reference.

Parallelism is separate: --slots N sets how many jobs run at once (default: half the CPUs).

Network egress

Each job gets its own network namespace. The only way out is an egress proxy that allows connections on port 443 to hostnames you list in checks.egress. Matching is by hostname, not by IP address. Other hosts and other ports are blocked.

checks:
  egress:
    - registry.npmjs.org
    - github.com

The agent clones your repository itself with a short-lived installation token, outside the job, so your jobs do not need github.com just for checkout.

Adding an egress host

When a job needs a host that is not allowed, the connection fails. Typical symptoms are a package install that hangs or a TLS or proxy error naming a host.

$ hookci logs 42 setup
error connect to registry.example.com:443 refused by egress policy
$ hookci validate
✓ .hookci.yml is valid

~/my-app recording
$ hookci logs 42 setup
error connect to registry.example.com:443 refused by egress policy
$ hookci validate
✓ .hookci.yml is valid

Illustration. Find the blocked host in the logs, add it to checks.egress, and validate.

1. Read the job log (hookci logs <run> [job|setup]) and note the hostname.

2. Add it to checks.egress in .hookci.yml:

   checks:
     egress:
       - registry.npmjs.org
       - registry.example.com

3. Run hookci validate, commit, and push. Allow only hostnames you trust, and review egress changes in pull requests: a longer list is a wider exit for code you run.

Running without isolation

--isolation none runs jobs without systemd units and without the per-job network namespace. Use it only when systemd or cgroup v2 is unavailable and the repository is trusted.

hookci --isolation none agent

Redaction

List secrets or values in redact and the agent scrubs them from job logs before upload or local storage:

redact: [NPM_TOKEN, MY_SECRET]

Redaction is a last line of defense. Keep secrets out of commands and echo statements, and set logs: local if logs must never leave the agent. Logs sent to the hub are capped at 10 MiB per job and opened through signed links valid 15 minutes.

Related: reference, Trust and forks.