> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roboticks.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Networking FAQ

> Network requirements for the Roboticks platform, self-hosted runners, air-gapped mode, proxy support, and GitHub App webhook reachability.

# 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?

| Destination                                  | Port      | Purpose                                                           |
| -------------------------------------------- | --------- | ----------------------------------------------------------------- |
| `api.roboticks.io`                           | 443       | Job polling, heartbeat, status reporting                          |
| `*.s3.amazonaws.com` (region-specific)       | 443       | MCAP / JUnit / log uploads via presigned URLs                     |
| `github.com`, `*.githubusercontent.com`      | 443       | `git clone` of the repo under test (unless you mirror internally) |
| `registry-1.docker.io`, `ghcr.io`, `quay.io` | 443       | Container images (ROS2 base images, Gazebo/Webots)                |
| NTP servers                                  | 123 (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.

| Destination                                   | Port | Purpose                                                            |
| --------------------------------------------- | ---- | ------------------------------------------------------------------ |
| `api.roboticks.io` (or your private endpoint) | 443  | Job 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](/runners/air-gapped) 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:

```bash theme={null}
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:

```bash theme={null}
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](/sdk/mcap-capture) to limit which topics record if bandwidth is tight.

```mermaid theme={null}
%%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%%
flowchart LR
    Runner -- HTTPS 443 --> API[api.roboticks.io]
    Runner -- HTTPS 443 --> S3[(S3 presigned)]
    Runner -- HTTPS 443 --> GH[github.com]
    Runner -- 123/UDP --> NTP[(NTP)]
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Runner registered but never picks up jobs">
    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).
  </Accordion>

  <Accordion title="MCAP uploads time out">
    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.
  </Accordion>

  <Accordion title="Air-gapped runner can't pull container images">
    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.
  </Accordion>
</AccordionGroup>