Kubiya LogoKubiya Developer Docs
Deployment/Runners

Create Your First Runner

Step-by-step guide to creating and deploying a Kubiya runner

Create Your First Runner

This guide will walk you through the process of creating and deploying your first Kubiya runner, which provides the execution environment for your AI Teammates.

Prerequisites

Before you begin, make sure you have:

  • Access to the Kubiya platform
  • For local runners: Admin access to your Kubernetes cluster or Docker environment
  • Necessary permissions to deploy resources in your environment

Choose Your Runner Type

Hosted Runner

Fully managed by Kubiya - fastest path to getting started

Local Runner

Deploy in your own environment for enhanced control and security

Creating a Hosted Runner

Navigate to Runners Page

In the Kubiya platform, go to Settings > Runners.

Click Create Runner

Click the Create Runner button to start the setup process.

Configure Runner

  • Name: Provide a descriptive name for your runner
  • Description: Optional details about the runner's purpose
  • Type: Select Hosted Runner

Complete Setup

Click Create to provision your hosted runner. The platform will automatically set up and configure the runner for you.

Hosted runners are the quickest way to get started with Kubiya. They're fully managed, automatically scaled, and require no infrastructure setup on your part.

Creating a Local Runner

Navigate to Runners Page

In the Kubiya platform, go to Settings > Runners.

Click Create Runner

Click the Create Runner button to start the setup process.

Configure Runner

  • Name: Provide a descriptive name for your runner
  • Description: Optional details about the runner's purpose
  • Type: Select Local Runner

Select Deployment Method

Choose your preferred deployment method:

  • Kubernetes (recommended for production)
  • Docker (for development or simpler environments)

Get Configuration

Based on your selection, you'll receive either:

  • Kubernetes: Helm chart values and installation commands
  • Docker: Docker Compose file or run command

Deploy Runner

Follow the provided instructions to deploy the runner in your environment.

Verify Connection

Once deployed, the runner will automatically connect to the Kubiya platform. Verify its status on the Runners page.

Deploying with Terraform

For infrastructure-as-code deployments, you can create runners using the Kubiya Terraform provider:

resource "kubiya_runner" "local_runner" {
  name        = "k8s-runner"
  description = "Kubernetes runner for production environment"
  type        = "local"
  
  # Optional: Configure connection details
  connection_details = {
    url = "https://api.kubiya.ai"
  }
}
 
# Output the runner token for use in deployment
output "runner_token" {
  value     = kubiya_runner.local_runner.token
  sensitive = true
}

After creating the runner resource, use the token in your Kubernetes or Docker deployment.

Configuring Runner Permissions

Runners need appropriate permissions to execute tasks effectively. See our Runner Permissions guide for detailed instructions on configuring secure access.

Using Your Runner

Once your runner is set up and connected, you can associate it with use cases:

  1. When creating or editing a use case, select your runner in the configuration
  2. The use case will now execute its tasks on the selected runner
  3. Monitor the runner's activity in the Runners page

Next Steps

Runners

Understanding Kubiya runners and their deployment options

Enforcer Service

Advanced permission management and security controls for Kubiya runners

On this page