On-Demand Execution

Execute tasks on-demand with automatic planning, agent selection, and flexible worker deployment strategies.

Quick Start

# Simple execution (auto-selects agent/team)
kubiya exec "Deploy my app to production"

# Local execution with ephemeral worker
kubiya exec "Run tests for changed files" --local --cwd $(pwd)

# Direct execution (skip planning)
kubiya exec agent AGENT_ID "Deploy to staging"

Execution Lifecycle

Every execution follows this lifecycle: Submit Request → Planning → Execute → Complete

Submit Request: Prompt analysis, resource discovery
Planning: Agent selection, cost estimation, plan creation
Execute: Queue selection, worker assignment, streaming output
Complete: Status update, response storage, graph updates

Lifecycle Stages

1. Submit Request

User provides natural language prompt
CLI authenticates with API key
Request routed to control plane

2. Planning (Auto Mode)

Resource Discovery: Fetches available agents, teams, environments
Agent Selection: AI analyzes prompt and selects best agent/team
Cost Estimation: Calculates token usage and estimated cost
Plan Generation: Creates detailed execution plan
User Approval: Shows plan for review (unless --yes)

3. Execute

Queue Selection: Chooses worker queue (persistent or ephemeral)
Worker Assignment: Assigns task to available worker in queue
Execution: Worker runs task using agent/team configuration
Streaming: Real-time output streamed to CLI
Context Updates: Updates context graph with results

4. Complete

Status Update: Marks execution as complete/failed
Response Storage: Stores full response in database
Graph Updates: Updates knowledge graph with execution metadata
Cleanup: For ephemeral workers, deletes queue and terminates process

Worker Deployment Modes

Choose between two deployment strategies based on your needs:

Persistent Workers

Best for: Production environments and high-frequency tasks Long-running workers that stay active and handle multiple executions:

# Deploy a persistent worker
kubiya worker start --queue-id QUEUE_ID --daemon

Benefits:

⚡ Instant task startup (dependencies already installed)
🔄 Handles multiple tasks sequentially
📦 Pre-warmed environment ready to execute
🎯 Best for production workloads

When to use:

Production agent deployments
Frequent executions throughout the day
Shared team resources
Mission-critical agents

Ephemeral Workers

Best for: CI/CD pipelines and one-off tasks Short-lived workers created on-demand for single executions:

# Automatically created when you use --local
kubiya exec "task" --local

Benefits:

💰 Pay only when running (no idle costs)
🧹 Automatic cleanup after execution
🔒 Isolated environment per execution
🚀 Perfect for CI/CD pipelines

When to use:

CI/CD pipeline integration
Development and testing
Occasional or scheduled tasks
Local execution from CLI

Quick Comparison

	Persistent Workers	Ephemeral Workers
Startup	Instant (pre-warmed)	10-120s first run, then cached
Lifecycle	Always running	Created → Execute → Cleanup
Cost	Continuous resource usage	Pay per execution
Best For	Production, frequent use	CI/CD, occasional tasks
Cleanup	Manual management	Automatic (5 min TTL)

Local Execution Mode

Run tasks with an ephemeral worker directly from your CLI or CI/CD pipeline.

How It Works

kubiya exec "analyze and fix linting errors" --local --cwd $(pwd)

When you run with --local, here’s what happens:

Queue Setup - CLI creates a temporary queue with 5-minute auto-cleanup
Worker Launch - CLI starts a local Python worker process
Task Execution - Worker runs in your specified directory with full file access
Stream Results - Real-time output appears in your terminal
Auto Cleanup - Worker exits and queue is automatically deleted

Key Benefits:

📁 Full access to local files and git repository
🔄 Works from any directory with --cwd
⚡ Fast for cached runs (dependencies installed once)
🧹 Zero cleanup needed (automatic)

Working Directory Support

The --cwd flag sets the execution working directory:

# Execute in current directory
kubiya exec "analyze git diff" --local --cwd $(pwd)

# Execute in specific directory
kubiya exec "run tests" --local --cwd /path/to/project

# In CI/CD pipeline
kubiya exec "run changed tests" --local --cwd $CIRCLE_WORKING_DIRECTORY

Why This Matters:

Local File Access: Worker can read/write files in specified directory
Git Integration: Access to .git directory and git commands
Project Context: Reads package.json, requirements.txt, etc.
Pipeline Integration: CI/CD jobs can pass their working directory

Pipeline Integration

Local mode is perfect for CI/CD pipelines. Here are examples for popular platforms:

GitHub Actions

name: Smart Testing
on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Kubiya CLI
        run: |
          curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash
          echo "$HOME/.kubiya/bin" >> $GITHUB_PATH

      - name: Run Smart Tests
        env:
          KUBIYA_API_KEY: ${{ secrets.KUBIYA_API_KEY }}
          KUBIYA_NON_INTERACTIVE: "true"
        run: |
          kubiya exec "
            Analyze git diff and run only tests for changed files.
            Skip irrelevant test suites.
          " \
            --local \
            --cwd ${{ github.workspace }} \
            --yes

GitLab CI

test-smart:
  stage: test
  image: node:20
  variables:
    KUBIYA_NON_INTERACTIVE: "true"
  script:
    - curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash
    - export PATH="$HOME/.kubiya/bin:$PATH"
    - |
      kubiya exec "
        Analyze git diff and run only affected tests.
      " \
        --local \
        --cwd $CI_PROJECT_DIR \
        --yes

CircleCI

version: 2.1
jobs:
  test:
    docker:
      - image: cimg/node:20.11
    environment:
      KUBIYA_NON_INTERACTIVE: "true"
    steps:
      - checkout
      - run:
          name: Install Kubiya CLI
          command: |
            curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash
            export PATH="$HOME/.kubiya/bin:$PATH"
      - run:
          name: Smart Test Selection
          command: |
            export PATH="$HOME/.kubiya/bin:$PATH"
            kubiya exec "Analyze git diff and run only affected tests." \
              --local --cwd $(pwd) --yes

Key Points:

--local: Creates ephemeral worker in the CI environment
--cwd: Sets working directory to pipeline workspace
--yes: Skips approval prompts for automation
KUBIYA_NON_INTERACTIVE="true": Ensures non-interactive mode

Real-World Use Case: Smart Test Selection

Problem: Traditional CI runs ALL tests on every commit, even when only one module changed. Solution: Kubiya analyzes changes and runs only relevant tests. Example from a Node.js project with modular test suites:

# In CI/CD pipeline
kubiya exec "
  You are an intelligent test executor.

  Steps:
  1. Run 'git diff HEAD~1 --name-only' to see changed files
  2. Analyze which module(s) were affected
  3. Run ONLY relevant test suites
  4. Explain your reasoning

  Rules:
  - If src/tasks/ changed, run: npm run test:tasks
  - If src/projects/ changed, run: npm run test:projects
  - If multiple modules changed, run tests for each
  - If only docs changed, skip all tests
" \
  --local \
  --cwd $(pwd) \
  --yes

Results:

Single module change: Run 8/36 tests (78% faster)
Documentation change: Run 0/36 tests (100% time saved)
Average savings: 77% time reduction

How It Works:

Git Diff Analysis: git diff --name-only shows src/tasks/tasks.js
Module Detection: Recognizes “tasks” module changed
Test Selection: Runs npm run test:tasks (8 tests)
Skip Irrelevant: Skips projects, comments, tags, search tests (28 tests)

Execution Modes

Auto-Planning Mode (Recommended)

Automatically selects agent/team and creates plan:

# Basic usage
kubiya exec "Deploy app to production"

# With options
kubiya exec "Analyze security issues" \
  --yes \
  --priority high \
  --output json

Features:

Analyzes task requirements
Selects best agent or team
Estimates cost and time
Shows detailed plan
Asks for approval

Local Mode

Execute with ephemeral local worker:

# Basic local execution
kubiya exec "task" --local

# With working directory
kubiya exec "run tests" --local --cwd $(pwd)

# With custom package source
kubiya exec "task" \
  --local \
  --package-source 0.5.0

# With local development wheel
kubiya exec "task" \
  --local \
  --local-wheel /path/to/worker.whl

Options:

--local: Use ephemeral worker
--cwd PATH: Set working directory
--environment ID: Specify environment
--package-source SOURCE: Custom worker package
--local-wheel PATH: Local wheel file (development)

Direct Mode

Skip planning and execute directly:

# Execute with specific agent
kubiya exec agent AGENT_ID "Deploy to staging"

# Execute with specific team
kubiya exec team TEAM_ID "Run integration tests"

Use Cases:

Testing specific agents
Bypassing plan approval
Scripting and automation

Plan File Mode

Execute from saved plan:

# Execute saved plan
kubiya exec --plan-file ~/.kubiya/plans/abc123.json

# Execute from URL
kubiya exec --plan-file https://example.com/plan.json

# Execute from GitHub
kubiya exec --plan-file user/repo/path/to/plan.json

Command Reference

# Auto-planning mode
kubiya exec "PROMPT" [flags]

# Local mode
kubiya exec "PROMPT" --local [--cwd PATH] [--environment ID]

# Direct mode
kubiya exec agent AGENT_ID "PROMPT"
kubiya exec team TEAM_ID "PROMPT"

# Plan file mode
kubiya exec --plan-file PATH_OR_URL

Global Flags

--yes, -y: Auto-approve plan (skip confirmation)
--output, -o: Output format (text, json, yaml)
--non-interactive: Skip all prompts
--priority: Task priority (low, medium, high, critical)
--save-plan PATH: Custom plan save location

Local Mode Flags

--local: Enable local execution mode
--cwd PATH: Working directory for execution
--environment ID: Environment ID
--package-source SOURCE: Worker package source (PyPI version, git URL, GitHub ref)
--local-wheel PATH: Path to local wheel file (development)

Queue Flags

--queue ID: Specific worker queue ID(s)
--queue-name NAME: Queue selection by name

Advanced Flags

--parent-execution ID: Parent execution for conversation continuation

Environment Variables

# API authentication
export KUBIYA_API_KEY=your-api-key

# Non-interactive mode (for CI/CD)
export KUBIYA_NON_INTERACTIVE=true

# Debug output
export KUBIYA_DEBUG=true

Best Practices

Local Execution

Use --local for CI/CD pipelines
Always specify --cwd for file access
Set KUBIYA_NON_INTERACTIVE=true in pipelines
Use --yes to skip approval prompts
Capture --output json for result parsing

Persistent Workers

Use for production environments
Pre-deploy workers to reduce latency
Monitor worker health and capacity
Scale workers based on load

Planning

Review plans before approval in production
Save important plans for reproducibility
Use --priority for urgent tasks
Check cost estimates for large operations

Error Handling

Parse --output json for status codes
Implement retries for transient failures
Monitor execution logs
Set up alerts for failed executions

Next Steps

Workers

Deploy and manage worker infrastructure

Workflows

Compose multi-step execution workflows

Core Resources

Manage agents, teams, and projects

Execution Resources

View and manage execution history

​Quick Start

​Execution Lifecycle

​Lifecycle Stages

​1. Submit Request

​2. Planning (Auto Mode)

​3. Execute

​4. Complete

​Worker Deployment Modes

​Persistent Workers

​Ephemeral Workers

​Quick Comparison

​Local Execution Mode

​How It Works

​Working Directory Support

​Pipeline Integration

​GitHub Actions

​GitLab CI

​CircleCI

​Real-World Use Case: Smart Test Selection

​Execution Modes

​Auto-Planning Mode (Recommended)

​Local Mode

​Direct Mode

​Plan File Mode

​Command Reference

​Global Flags

​Local Mode Flags

​Queue Flags

​Advanced Flags

​Environment Variables

​Best Practices

​Local Execution

​Persistent Workers

​Planning

​Error Handling

​Next Steps

Workers

Workflows

Core Resources

Execution Resources

Quick Start

Execution Lifecycle

Lifecycle Stages

1. Submit Request

2. Planning (Auto Mode)

3. Execute

4. Complete

Worker Deployment Modes

Persistent Workers

Ephemeral Workers

Quick Comparison

Local Execution Mode

How It Works

Working Directory Support

Pipeline Integration

GitHub Actions

GitLab CI

CircleCI

Real-World Use Case: Smart Test Selection

Execution Modes

Auto-Planning Mode (Recommended)

Local Mode

Direct Mode

Plan File Mode

Command Reference

Global Flags

Local Mode Flags

Queue Flags

Advanced Flags

Environment Variables

Best Practices

Local Execution

Persistent Workers

Planning

Error Handling

Next Steps