Runners execute workflows on your infrastructure - keeping your data secure while connecting to Kubiya’s coordination platform.

​
What runners do

Execute workflows: Run each workflow step in isolated containers for security and reliability. Stay in your infrastructure: All data and execution happens on your servers, never leaves your environment. Connect to Kubiya: Receive workflow instructions and report results back to the platform. Manage resources: Handle container orchestration, secrets, networking, and storage automatically.

​
Two deployment options

Run on your own Kubernetes cluster: 
helm repo add kubiya https://charts.kubiya.ai
helm install my-runner kubiya/kubiya-runner \
  --namespace kubiya \
  --create-namespace \
  --set runner.token=${RUNNER_TOKEN}
Benefits:
  • Complete data control and security
  • Custom resource allocation
  • Integration with existing monitoring
  • Compliance with internal policies
Requirements:
  • Kubernetes cluster
  • Outbound HTTPS access to Kubiya API
  • Sufficient resources for workflow execution

​
Hosted runners (quick start)

Managed by Kubiya for immediate use:
  • Zero infrastructure setup required
  • Automatic updates and scaling
  • Perfect for development and testing
  • No capacity planning needed
Note: Hosted runners are shared infrastructure - use self-hosted for production workloads.

​
How runners work

  1. Connect: Runner authenticates with Kubiya using a secure token
  2. Receive: Gets workflow assignments from Kubiya’s coordination platform
  3. Execute: Runs each step in isolated containers with proper resources
  4. Report: Sends results, logs, and status back to Kubiya
  5. Clean up: Removes containers and temporary resources after completion

​
Security model

Container isolation: Each step runs in its own container, preventing conflicts and ensuring clean environments. Network policies: Only necessary network access is allowed, with outbound HTTPS to Kubiya API. Secret management: Credentials are encrypted and injected securely into workflow steps. RBAC: Fine-grained permissions control what runners can do in your cluster. Audit logs: Complete record of all workflow executions for compliance.

​
Configuration example

# Basic runner configuration
runner:
  name: production-runner
  token: ${RUNNER_TOKEN}
  
  # Resource limits
  resources:
    requests:
      memory: "256Mi"
      cpu: "100m"
    limits:
      memory: "1Gi"
      cpu: "500m"
  
  # Workflow settings
  workflow:
    namespace: kubiya-workflows
    defaultTimeout: 30m
    maxConcurrent: 10
  
  # Security
  security:
    runAsNonRoot: true
    allowPrivileged: false

​
Common troubleshooting

Runner won’t connect:
  • Verify token is valid
  • Check outbound HTTPS connectivity
  • Ensure DNS can resolve Kubiya API
Workflows fail to start:
  • Check RBAC permissions
  • Verify resource quotas
  • Ensure container images are accessible
Performance issues:
  • Increase resource limits
  • Check node capacity
  • Monitor image pull times

​
Getting started

  1. Choose deployment: Self-hosted for production, hosted for testing
  2. Install runner: Use Helm chart or kubectl manifests
  3. Test connectivity: Verify runner shows as online in Kubiya
  4. Run first workflow: Execute a simple workflow to confirm everything works
Next: Deploy a runner or learn about security