Lite Runner (Pods & Dockerless Hosts)

The Reoclo Runner has two profiles. Full is what most people install: it deploys applications, manages containers, and reports stats. Lite is a leaner mode that ships stats and remote shell only — no deploys, no Docker required. Use Lite when you want observability and access to a host that can’t (or shouldn’t) run Docker.

Use Lite for:

• Cloud GPU pods — RunPod, Vast.ai, Lambda Cloud, anywhere you can’t install Docker because you are the container
• Bare-metal monitoring — observability on a server before you commit to Docker deploys
• Kubernetes — a sidecar runner that gives you Reoclo shell access without messing with the pod’s runtime
• Anything ephemeral — the runner re-registers on every boot without losing its identity

What’s different from Full

	Lite	Full
Stats / heartbeat	✅	✅
Interactive shell	✅	✅
GPU detection	✅	✅
Docker required	no	yes
Application deploys	❌	✅
Container management	❌	✅
systemd required	no	yes (or use Docker image)

Lite runners show up in your FleetView with an amber Lite badge. Deploys are blocked at dispatch time with a clear error — there’s no silent failure mode.

Install via one-liner

The installer auto-detects whether to use Lite. If Docker isn’t on the host, it picks Lite. If you’re inside a container (/.dockerenv or RUNPOD_POD_ID or KUBERNETES_SERVICE_HOST is set), it picks foreground mode — no systemd unit, no dedicated user, just exec the runner.

curl -sSL https://get.reoclo.com | bash -s -- \
  --token rt_xxxxxxxxxxxx \
  --gateway wss://api.reoclo.com/ws/runner \
  --yes

You can force the choice explicitly:

# Force lite profile on a host that happens to have Docker
curl -sSL https://get.reoclo.com | bash -s -- \
  --token rt_xxx --profile lite --yes

# Force foreground mode (no systemd unit, exec the runner directly)
curl -sSL https://get.reoclo.com | bash -s -- \
  --token rt_xxx --profile lite --mode foreground --yes

# Use a custom hostname (e.g. a stable pod ID)
curl -sSL https://get.reoclo.com | bash -s -- \
  --token rt_xxx --profile lite --hostname my-gpu-pod-01 --yes

The installer’s --check flag prints what mode it would use without touching anything — handy for templating pod images.

Foreground mode

When the installer detects a container environment (or you pass --mode foreground), it doesn’t write a systemd unit. Instead it writes /opt/reoclo/run.sh, a small wrapper that reads REOCLO_TOKEN, REOCLO_GATEWAY_URL, and REOCLO_PROFILE from env and execs the runner. The orchestrator (RunPod, Kubernetes, whatever) owns the process lifecycle.

This is the right model for pods because:

• Pods rarely ship systemd; adding a second supervisor fights the orchestrator
• The pod filesystem is ephemeral — session tokens can’t be persisted across restarts anyway
• The runner re-registers on every boot, which is fast (~1s)

Stable identity across restarts

Lite runners on pods register under a stable hostname (we recommend runpod-<pod_id> or similar). The Reoclo gateway upserts servers by (tenant_id, hostname), so every restart of the same logical pod reuses the same Server record. The restart_count field tracks how many times the pod has come back.

Container snapshots are purged on every restart (the pod filesystem is gone), but metrics history, configured applications, and audit log all persist.

Reusable, scoped tokens

For pods that restart often, you’ll want a reusable, server-bound registration token instead of a one-shot token. Issue one with the token issuance API bound to a specific Server and scoped to that server’s hostname (and optionally a specific IP):

curl -X POST https://app.reoclo.com/api/admin/runners/tokens \
  -H "Authorization: Bearer $REOCLO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "runpod-prod-01",
    "server_id": "<server-uuid>"
  }'

When server_id is set, the API auto-fills allowed_hostnames from the server’s current hostname so a leaked token can only re-register the same logical pod. The token’s usage_count increments on every successful registration, preserving the audit trail even though status stays pending for reuse.

If a leaked token is registered from a hostname not in allowed_hostnames (or an IP not in allowed_ips), the gateway rejects with 4003 Token scope mismatch and logs the attempt.

Pod-image reference

For RunPod / Kubernetes templates, see the pod-image reference — a minimal Ubuntu 22.04 Dockerfile with reoclo-runner pre-installed and an entrypoint that auto-derives the hostname from $RUNPOD_POD_ID. For step-by-step RunPod setup, see RunPod Setup.

Limitations of Lite

• No deploys. Lite runners can’t build images or run containers. If you try to assign a Docker application to a Lite server, it’s rejected with a clear error at dispatch time.
• No host admin operations. Operations like firewall management, disk cleanup, and service control are gated on Docker (specifically the host_admin capability), which Lite runners don’t have.
• Foreground mode has no auto-restart on crash. If you’re not in a pod (no orchestrator), use --mode user to get systemd --user lifecycle management. In pods, the orchestrator handles restart.

If any of these matter, install the Full profile instead.