Air-gapped mode

Air-gapped mode is the Enterprise tier posture for environments where the runner cannot — or must not — reach the public internet. Defence, medical-devices, automotive functional-safety teams use it to satisfy network-segmentation requirements.

Air-gapped pools are available only on the Enterprise tier. The platform itself can be SaaS, single-tenant SaaS, or fully on-prem. The runner side of the contract is identical across all three.

What changes

In air-gapped mode the runner only ever opens connections to:

https://<your-roboticks-platform> (could be api.roboticks.io, your single-tenant subdomain, or an on-prem https://roboticks.internal)
The S3-compatible object store presigned-URLs returned by the platform

It does not clone from GitHub. It does not pip install from public PyPI. It does not pull base images from Docker Hub at job time.

Set it up

Step 1 — declare an air-gapped pool

rbtk pool create \
  --project regulated-arm \
  --name onprem-airgapped \
  --type self-hosted \
  --airgapped

The --airgapped flag annotates the pool. Jobs routed to it must have airgapped: true on the project — the router refuses cross-mode dispatch.

Step 2 — flip the project flag

rbtk project update --slug regulated-arm --set airgapped=true

Once set, no job in this project is ever dispatched to a hosted pool, even if a self-hosted pool is unavailable. Jobs queue until a self-hosted runner picks them up.

Step 3 — install the runner on the isolated network

Mirror the Cosign-signed binary into your internal artifact store, then install on the host:

# On the air-gapped host (binary already side-loaded to /tmp)
sudo install -m 0755 /tmp/rbtk-runner-linux-amd64 /usr/local/bin/rbtk-runner

# Configure to talk to your on-prem platform
export ROBOTICKS_API_ENDPOINT=https://roboticks.internal
rbtk-runner register \
  --project regulated-arm \
  --pool onprem-airgapped \
  --token rbtk_pool_reg_xx... \
  --name airgap-runner-01

Step 4 — set `network.airgapped: true` in runner.yaml

The runner enforces network-egress restrictions when this flag is set:

network:
  airgapped: true
  allowlist:
    - roboticks.internal
    - s3.internal

Any outbound connection to a non-allowlisted host fails fast with an audit-log row.

Pushing tests without GitHub

In air-gapped mode the runner cannot git clone. Instead the CLI uploads the test payload directly:

# From a workstation with network access to BOTH GitHub and the Roboticks platform
rbtk test run \
  --project regulated-arm \
  --pool onprem-airgapped \
  --push ./           # tars the working dir and uploads to the platform

The platform stores the payload as an immutable blob, dispatches the job to the air-gapped pool, and the runner pulls the blob (not the git repo) before execution. For commit-traceable runs, attach the commit SHA explicitly:

rbtk test run --push ./ --git-sha $(git rev-parse HEAD) --git-ref main

The SHA is recorded in the evidence pack so auditors can reconstruct the source state.

Firewall rules

Open one outbound rule on the runner host. Everything else can be denied.

Direction	Destination	Port	Purpose
Outbound	`roboticks.internal` (or your platform host)	443	Heartbeat, poll, MCAP presign
Outbound	`s3.internal` (or your object store)	443	MCAP and JUnit uploads

That is the entire firewall surface.

On-prem `roboticks` SDK mirror (optional)

If your tests pip install roboticks at job time and the runner cannot reach pypi.org, host an internal mirror:

# On the platform side
rbtk admin sdk mirror sync --to s3://roboticks-pypi-mirror/

# In runner.yaml
resources:
  pip_index_url: https://pypi.internal/simple/

Or — preferred — bake the SDK into your test image so the runner never needs PyPI:

FROM osrf/ros:humble-desktop
RUN pip install roboticks==1.4.2

Push the baked image to your internal registry and reference it from the test config:

test:
  image: registry.internal/roboticks/test-base:1.4.2

Verification

After setup, prove isolation:

# On the runner host
rbtk-runner doctor --airgapped

✓ Network: only roboticks.internal and s3.internal reachable
✗ Network: external host github.com is reachable — air-gap violation

A red line is a finding, not a runner error — but you should fix the firewall before relying on the posture for audit.

Limits and trade-offs

	Air-gapped self-hosted	Standard self-hosted	Hosted
Internet egress	None	Optional	Required
GitHub App can drive jobs	No (CLI push only)	Yes	Yes
LLM triage	Only if platform on-prem with bundled LLM	Yes	Yes
Tier required	Enterprise	Any paid	Any paid
Setup effort	High	Low	Zero

Air-Gapped Mode

Air-gapped mode

What changes

Set it up

Step 1 — declare an air-gapped pool

Step 2 — flip the project flag

Step 3 — install the runner on the isolated network

Step 4 — set `network.airgapped: true` in runner.yaml

Pushing tests without GitHub

Firewall rules

On-prem `roboticks` SDK mirror (optional)

Verification

Limits and trade-offs

Next steps

Pool management

Service install

Documentation Index

​Air-gapped mode

​What changes

​Set it up

​Step 1 — declare an air-gapped pool

​Step 2 — flip the project flag

​Step 3 — install the runner on the isolated network

​Step 4 — set network.airgapped: true in runner.yaml

​Pushing tests without GitHub

​Firewall rules

​On-prem roboticks SDK mirror (optional)

​Verification

​Limits and trade-offs

​Next steps

Pool management

Service install

Air-gapped mode

What changes

Set it up

Step 1 — declare an air-gapped pool

Step 2 — flip the project flag

Step 3 — install the runner on the isolated network

Step 4 — set `network.airgapped: true` in runner.yaml

Pushing tests without GitHub

Firewall rules

On-prem `roboticks` SDK mirror (optional)

Verification

Limits and trade-offs

Next steps