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

# Runner Deployment

> How to configure and run lynx-runner on your infrastructure

The `lynx-runner` binary runs on your infrastructure and connects to the Lynx platform. You can deploy it on bare metal, VMs, or Kubernetes.

Connection credentials (endpoint URL and auth tokens) are provided during onboarding. Set them as environment variables before starting the runner.

## Start a runner

```bash theme={null}
lynx-runner \
  --runner-id my-runner-1 \
  --name "My Runner 1" \
  --max-concurrent-jobs 4
```

### Flags

| Flag                        | Description                                                           |
| --------------------------- | --------------------------------------------------------------------- |
| `--runner-id`               | Unique identifier for this runner. Must be distinct across your pool. |
| `--name`                    | Display name shown in the API and dashboard                           |
| `--max-concurrent-jobs`     | Maximum number of jobs this runner executes in parallel               |
| `--heartbeat-interval-secs` | How frequently the runner sends a heartbeat (default: 5)              |

## Verify registration

After starting, confirm the runner has registered:

```bash theme={null}
curl -s https://api.lynx.tetryx.io/runners | jq
```

You should see your runner with `"status": "Idle"`. Inspect a specific runner:

```bash theme={null}
curl -s https://api.lynx.tetryx.io/runners/my-runner-1 | jq
```

## Running multiple runners

Start additional runners with distinct `--runner-id` values. Lynx distributes jobs across all active runners automatically.

```bash theme={null}
# Second runner on the same machine or a different host
lynx-runner \
  --runner-id my-runner-2 \
  --name "My Runner 2" \
  --max-concurrent-jobs 4
```

## Drain before maintenance

Before taking a runner offline, drain it so it finishes its current jobs and stops accepting new ones:

```bash theme={null}
curl -X POST https://api.lynx.tetryx.io/runners/my-runner-1/drain
```

The runner's status becomes `Maintenance`. Resume when ready:

```bash theme={null}
curl -X POST https://api.lynx.tetryx.io/runners/my-runner-1/resume
```

## Kubernetes deployment

Run `lynx-runner` as a Deployment. Each pod acts as one runner in the pool.

```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: lynx-runner
spec:
  replicas: 4
  selector:
    matchLabels:
      app: lynx-runner
  template:
    metadata:
      labels:
        app: lynx-runner
    spec:
      containers:
      - name: lynx-runner
        image: tetryx/lynx-runner:latest
        args:
          - --name
          - $(POD_NAME)
          - --max-concurrent-jobs
          - "4"
        env:
        - name: POD_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: LYNX_RUNNER_ID
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        envFrom:
        - secretRef:
            name: lynx-credentials
```

Store your Lynx connection credentials in the `lynx-credentials` secret. Contact Tetryx for your onboarding credentials.