Docs

Quickstart

Get Kōl installed, check the role it infers for you, and run your first dry-run prompt. Full reference docs live in the repository.

Prerequisites

Rust 1.70+
AWS CLI configured with credentials
IAM groups llm-owners, llm-admins and llm-users — Kōl maps these to roles

Install

Kōl is currently distributed as source. Install the CLI with Cargo:

shell

cargo install --git https://github.com/Nuvai/Kol kol-cli

Or clone and build the whole workspace:

shell

git clone https://github.com/Nuvai/Kol.git
cd Kol
cargo build --release

Configure

Kōl reads environment variables and an optional config.toml. Start from the example:

shell

cp config.example.toml config.toml

.env

# Required
SUDO_SIGNING_KEY=base64-encoded-32-byte-key

# AWS
AWS_REGION=us-east-1
SNS_TOPIC_ARN=arn:aws:sns:us-east-1:123456789012:alerts

# LLM
LLM_PROVIDER=claude-bedrock
OPENROUTER_API_KEY=your-api-key

config.toml

[aws]
region = "us-east-1"

[llm]
default_provider = "claude-bedrock"
max_tokens = 1000
temperature = 0.1

[audit]
enabled = true
owner_email = "admin@example.com"

[sudo]
default_duration_hours = 24
max_duration_hours = 168

Your first prompt

Check the identity and role Kōl inferred, then preview an action with a dry run:

shell

kol identity

kol --dry-run --prompt "Create an EC2 instance for ML training"

# guided mode
kol --interactive

Cohorts

Cohorts group users and resources across cloud providers. Scope any prompt to one with --cohort.

shell

kol cohort create "Data Science" --providers aws,azure
kol cohort add-user "Data Science" user@example.com
kol --cohort "Data Science" --prompt "Create S3 bucket for datasets"

Sudo tokens

Owners can grant time-limited, action-scoped escalation. Tokens are signed with SUDO_SIGNING_KEY and every use is audited.

shell

kol sudo issue user123 "create_gpu_instance,create_large_instance" \
  --duration 24 --reason "ML training project"

kol --token "eyJ0eXAi…" --prompt "Create GPU instance"

Deploy to Lambda

Run Kōl as a serverless API behind API Gateway:

shell

./deploy.sh

curl -X POST https://<api-gateway>/execute \
  -H "Content-Type: application/json" \
  -d '{"prompt": "list all EC2 instances", "dry_run": true}'