Skip to main content

​
Networking FAQ

Two surfaces have network requirements: the GitHub App webhook receiver (inbound to Roboticks; nothing for you to configure) and self-hosted runners (outbound from your network).

​
Hosted runners

Nothing for you to configure. Hosted runners live in our VPCs. The GitHub App POSTs to https://api.roboticks.io/api/v1/github/webhooks over HTTPS; we handle the rest.

​
Self-hosted runners

​
What outbound access does the runner need?

DestinationPortPurpose
api.roboticks.io443Job polling, heartbeat, status reporting
*.s3.amazonaws.com (region-specific)443MCAP / JUnit / log uploads via presigned URLs
github.com, *.githubusercontent.com443git clone of the repo under test (unless you mirror internally)
registry-1.docker.io, ghcr.io, quay.io443Container images (ROS2 base images, Gazebo/Webots)
NTP servers123 (UDP)Time synchronization
Inbound: none. The runner polls; you don’t open any inbound ports.

​
Air-gapped mode (Enterprise)

Air-gapped runners talk to only the Roboticks platform — no GitHub, no public container registries.
DestinationPortPurpose
api.roboticks.io (or your private endpoint)443Job polling + artifact upload via Roboticks-relayed presigned URLs
Customer-side prerequisites:
  • A mirror of the container images you depend on (run rbtk-runner doctor --list-images to print the set).
  • A mirror of any pip indexes the SDK pulls from.
  • An internal Git mirror, since the runner won’t reach GitHub directly. The CLI pushes commit bundles via rbtk test cloud --bundle.
See Air-gapped runners for the full setup.

​
GitHub App webhooks

GitHub POSTs webhook deliveries to https://api.roboticks.io/api/v1/github/webhooks. You don’t have to configure anything; GitHub’s IP range is public. If your repo lives in GitHub Enterprise Server behind a corporate firewall, your GHES instance must be able to reach api.roboticks.io on 443 to deliver webhooks. For air-gapped GHES deployments, the only option today is the CLI fallback path (no GitHub App).

​
Proxy support

The runner respects HTTPS_PROXY, HTTP_PROXY, and NO_PROXY environment variables: 
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,internal.example.com
For systemd-managed runners, set these in the unit file or in /etc/roboticks-runner/env.

​
TLS verification

The runner verifies TLS certificates by default. For private-CA setups (common in air-gapped enterprises), provide your CA bundle: 
export ROBOTICKS_CA_BUNDLE=/etc/ssl/certs/internal-ca.crt

​
Time synchronization

Keep runner clocks accurate (NTP). Clock skew breaks JWT verification, S3 presigned URL signing, and HMAC webhook verification. We’ve seen >5 minute skews cause silent job-pickup failures.

​
Why presigned URLs (and not direct S3 access)?

Runners do not hold long-lived AWS credentials. Each artifact upload uses a per-object presigned URL with a 15-minute expiry, requested via /internal/runners/jobs/{id}/artifacts/upload-urls. This keeps the blast radius of a runner compromise contained.

​
Bandwidth budget

  • JUnit XML uploads: kilobytes per test.
  • Logs: typically a few MB per run.
  • MCAP bag files: the variable. A 30-second navigation test with 5 sensor topics is ~50–200 MB. Plan accordingly, especially for self-hosted runners over constrained uplinks.
Use MCAP capture allowlists to limit which topics record if bandwidth is tight.

​
Troubleshooting

Check that outbound 443 to api.roboticks.io succeeds from the runner host: curl -I https://api.roboticks.io/healthz. If a proxy is in the path, confirm HTTPS_PROXY is set in the runner’s environment (not just your shell).
Presigned URLs expire in 15 minutes. Slow uplinks on multi-GB MCAPs may exceed that. Either reduce MCAP size (topic allowlist) or move to a runner host with better uplink. Enterprise customers can request a longer presign window.
Air-gapped mode requires you mirror the images internally. Run rbtk-runner doctor --list-images to enumerate; mirror them to your internal registry; set ROBOTICKS_IMAGE_REGISTRY to your mirror.