Runabot Documentation

Mon, 01 Jan 0001 00:00:00 +0000

System Architecture#

Runabot Addon System & Access Control#

Runabot provides isolated sandboxed “addons” for bot connectivity, including the SSH Addon. Addons run in their own namespaces but share the cluster NetworkPolicy rules.

The SSH Jump Host Operator is integrated natively within runabot-api and manages BotSsh CustomResources in the cluster.

graph TD
 subgraph K8s Cluster
 User[[Developer/User]] -->|TCP:2222| SSHJumpHost(SSH Jump Host\nssh namespace)
 
 subgraph SSH Namespace
 SSHJumpHost -->|manages| SSHTokens[authorized_keys\nPID:1 Reconciler]
 SSHOperator(ssh-operator\nPID:1) -->|Reconciles| BotSshCRD((BotSsh CRD))
 end
 
 subgraph Runabot API
 APIServer(runabot-api) -->|RPC: CreateAddon| BotSshCRD
 end
 
 subgraph Bot Namespace
 SSHD(openssh-server\nTCP:18789 / TCP:2222)
 Bot(Bot Process)
 User -->|ProxyJump| SSHD
 end
 
 SSHJumpHost -->|TCP:2222| SSHD
 end

The Addon Operator strictly enforces the single instance rule so that a user may only deploy a single global jump host.

Mon, 01 Jan 0001 00:00:00 +0000

Bot Filesystem Provisioning: Strategy Analysis#

Current Approach: Full `rsync` Copy#

How it works today (see chart/openclaw/container/init.sh + statefulset.yaml):

Init container runs rsync -axH / /main_container/ on first boot -> copies the entire Debian 13 rootfs (~2.7 GB) to PVC.
On subsequent boots, init container only updates managed scripts (bot-wrapper.sh, bot-install.sh) and systemd units.
Main container mounts PVC subdirectories (/usr, /var, /home, /root, /opt, /etc) via subPath.
Container image itself is pulled but largely unused after initial rsync – it’s just a “source” of the rootfs.

Storage cost per bot: ~2.7 GB base + user data.

Mon, 01 Jan 0001 00:00:00 +0000

Runabot Network Architecture & Firewall#

This page describes the complete network topology of a Runabot tenant environment: how traffic flows between every component, and where authentication/authorisation and network firewall controls are enforced.

Legend#

Symbol	Meaning
🔥	Cilium / Kubernetes `NetworkPolicy` or `CiliumNetworkPolicy` firewall boundary
🔐	Authentication / Authorisation check (Ory Kratos + OpenFGA)
➡️	Allowed flow
✋	Blocked by default (explicit allowlist required)

Component Diagram#

The diagram below shows one user’s namespace (dev-alice) inside the cluster. All egress from bot and addon pods is default-deny at the eBPF level; only explicitly whitelisted FQDNs or cluster endpoints are reachable.

Mon, 01 Jan 0001 00:00:00 +0000

OIDC Configuration (Universal SSO)#

Runabot supports multiple OIDC providers (Google, Microsoft, Keycloak, etc.) via Ory Kratos. Configuration is managed entirely through SOPS secrets.

1. Configure SOPS#

Add your providers to the oidc_providers list in your environment’s SOPS file (pulumi/sops/secrets/<env>.json).

Example: Google SSO#

{
 "runabot": {
 "oidc_providers": [
 {
 "id": "google",
 "provider": "google",
 "label": "Sign in with Google",
 "client_id": "CLIENT_ID_HERE",
 "client_secret": "CLIENT_SECRET_HERE",
 "mapper_url": "file:///etc/config/kratos/oidc.google.json",
 "scope": ["email", "profile", "openid"]
 }
 ]
 }
}

Example: Microsoft (Azure AD)#

{
 "runabot": {
 "oidc_providers": [
 {
 "id": "microsoft",
 "provider": "microsoft",
 "label": "Sign in with Microsoft",
 "client_id": "CLIENT_ID_HERE",
 "client_secret": "CLIENT_SECRET_HERE",
 "microsoft_tenant": "organizations",
 "mapper_url": "file:///etc/config/kratos/oidc.microsoft.json",
 "scope": ["email", "profile", "openid"]
 }
 ]
 }
}

Example: Generic OIDC (Keycloak/Okta)#

{
 "runabot": {
 "oidc_providers": [
 {
 "id": "my-sso",
 "provider": "generic",
 "label": "Company SSO",
 "client_id": "CLIENT_ID_HERE",
 "client_secret": "CLIENT_SECRET_HERE",
 "issuer_url": "https://sso.example.com/realms/master",
 "mapper_url": "file:///etc/config/kratos/oidc.generic.json"
 }
 ]
 }
}

2. Redirect URIs#

Ensure your identity provider has the correct Authorized Redirect URI: https://<your-domain>/_auth/kratos/self-service/methods/oidc/callback/<provider_id>

Mon, 01 Jan 0001 00:00:00 +0000

Terms of Service (AGB)#

Status: February 2026

1. Scope of Service#

Runabot (“the Provider”) provides the user with a web-based platform that allows access to persistent container environments (“Bot Containers”). The service includes:

Provisioning of isolated Linux container environments with persistent storage.
Access to these environments via a web terminal, SSH, and API interfaces.
The ability to install and execute software (e.g., AI assistants like OpenClaw) within the allocated resources.

The Provider does not guarantee 100% availability and reserves the right to perform maintenance work, which may lead to temporary outages.

Mon, 01 Jan 0001 00:00:00 +0000

Getting Started with Runabot#

Runabot allows you to deploy and manage AI assistants (bots) in an isolated environment.

Navigate to the Runabot UI (e.g., https://runabot.de/ui/). If not logged in, you will be redirected to the login page. Sign in with your corporate credential (Google/Microsoft).

2. Deploy a Bot#

On the Dashboard, click Deploy New Bot.
Enter a name (e.g., my-assistant).
Select the Chart (e.g., runabot-bot).
Select a Version.
Click Deploy.

The bot will appear in your list. It may take a minute to become Running.

Mon, 01 Jan 0001 00:00:00 +0000

OpenClaw Bot Guide#

OpenClaw is a powerful personal assistant that you can run on Runabot. This guide covers common administrative tasks for your OpenClaw instance.

Initial Setup (Onboarding)#

When you first deploy an OpenClaw bot, you need to perform an initial onboarding to set up your administrator account and basic settings.

Open the Web Terminal for your bot.
Run the onboarding command:
```
openclaw onboard
```
Follow the interactive prompts to:
- Set up your administrator username and password.
- Configure basic system settings.
- Initialize the local database.

Once onboarding is complete, you can access the OpenClaw Web UI using the credentials you just created.

Mon, 01 Jan 0001 00:00:00 +0000

UI Reference#

Dashboard#

The main dashboard provides an overview of your resources.

My Bots: Grid view of your running bot instances.
- Status Indicator: Green (Running), Orange (Pending), Red (Failed).
- Delete: Remove the bot and its data.
- Terminal: Open the web terminal.
- Download kubeconfig: Download a kubeconfig file for kubectl access (valid 30 days).
Deploy New Bot: Opens the deployment wizard.

Terminal#

The Web Terminal provides direct shell access.

Reconnect: If the connection drops, use the reload button in the header.
Security: The terminal session is authenticated via your user identity.
OpenClaw Operations: For OpenClaw-specific commands like openclaw onboard or systemctl reboot, see the OpenClaw Guide.

Backups#

(If enabled) Lists automated backups of your bot volumes.

Runabot Documentation

System Architecture#

Runabot Addon System & Access Control#

Bot Filesystem Provisioning: Strategy Analysis#

Current Approach: Full rsync Copy#

Runabot Network Architecture & Firewall#

Legend#

Component Diagram#

OIDC Configuration (Universal SSO)#

1. Configure SOPS#

Example: Google SSO#

Example: Microsoft (Azure AD)#

Example: Generic OIDC (Keycloak/Okta)#

2. Redirect URIs#

Terms of Service (AGB)#

1. Scope of Service#

Getting Started with Runabot#

1. Login#

2. Deploy a Bot#

OpenClaw Bot Guide#

Initial Setup (Onboarding)#

UI Reference#

Dashboard#

Terminal#

Backups#

Current Approach: Full `rsync` Copy#