Documentation

Installation

Install klaas on macOS, Linux, or Windows in seconds. Choose your preferred installation method below.

curl -fsSL https://klaas.sh/install.sh | bash

irm https://klaas.sh/install.ps1 | iex

curl -fsSL https://klaas.sh/install.cmd -o install.cmd && install.cmd

brew install klaas-sh/tap/klaas

scoop bucket add klaas https://github.com/klaas-sh/scoop-bucket
scoop install klaas

nix run github:klaas-sh/cli

nix profile install github:klaas-sh/cli

Verifying Installation

After installation, verify klaas is working:

klaas --version

Quickstart

Get up and running with klaas in under a minute.

Prerequisites

Before using klaas, ensure you have at least one supported AI coding agent installed:

Step 1: Start klaas

Simply run:

klaas

If you have multiple agents installed, klaas displays an interactive selector. Use arrow keys or the shortcut key (shown in brackets) to select your agent.

Step 2: Authenticate

On first run, klaas prompts you to authenticate. A browser window opens automatically. Log in with your klaas account, and the CLI receives your credentials securely via OAuth Device Flow.

Step 3: View Your Session

Open klaas.sh in any browser, log in, and navigate to Sessions. You'll see your active session streaming in real-time.

From the web dashboard, you can:

• Watch terminal output as it happens
• Send text input to your agent
• Approve permission requests (for supported agents)

CLI Commands

Complete reference for all klaas command-line commands.

klaas

The main command to start a new agent session with remote access enabled.

klaas [options] [-- agent-args...]

Examples

# Start with auto-detected agent
klaas

# Start with a specific agent
klaas --agent claude
klaas -a gemini

# Resume the previous session
klaas --resume

# Pass arguments through to the agent
klaas -- --model sonnet --allowedTools "Bash(git*)"
klaas -a claude -- -p "Help me refactor this code"

Options

klaas agents

List all installed AI coding agents that klaas can use.

klaas agents

Example Output

  Installed agents:

    claude       - Anthropic Claude Code
    gemini       - Google Gemini CLI
    aider        - Aider

Agents without any installed binaries are not shown.

klaas upgrade

Upgrade klaas to the latest version.

klaas upgrade

Alias: klaas update

This command:

1. Checks for the latest version on GitHub releases
2. Downloads the appropriate binary for your platform
3. Replaces the current installation

klaas uninstall

Remove klaas from your system.

klaas uninstall [--purge]

Options

This command removes:

• The klaas binary
• Cache directory (~/Library/Caches/klaas/ on macOS, ~/.cache/klaas/ on Linux)
• Optionally: user data directory (~/.klaas/)

Supported Agents

klaas supports multiple AI coding agents out of the box:

Hooks Support indicates whether klaas can receive notifications when the agent requests permissions: Full = permission requests trigger notifications, Partial = some events supported, None = output streaming only.

Global Flags

Flags that work with any klaas command.

Configuration File

Customize klaas behavior with a TOML configuration file.

klaas reads configuration from TOML files in two locations:

1. Project-level: ./.klaas/config.toml (in your project directory)
2. User-level: ~/.klaas/config.toml (in your home directory)

Project-level configuration takes precedence over user-level.

Basic Configuration

# Default agent when multiple are available
default_agent = "claude"

# Only show these agents (even if others are installed)
only = ["claude", "gemini"]

# Or add agents to the built-in list
also = ["my-custom-agent"]

# Disable anonymous analytics (tracks install/upgrade/uninstall
# events with version and platform only, no personal data)
analytics = false

Custom Agent Definitions

Define your own agents with full configuration:

[agents.my-agent]
# Required: command to execute
command = "/path/to/my-agent"

# Required: human-readable name
name = "My Custom Agent"

# Optional: alternative binary names for detection
detect = ["my-agent", "myagent"]

# Optional: default arguments
args = ["--verbose"]

# Optional: hooks type ("claude", "gemini", "codex", or "none")
hooks_type = "claude"

# Optional: single-letter shortcut for interactive selection
shortcut = "X"

# Optional: run through shell (for complex commands)
shell = false

Full Example

# ~/.klaas/config.toml

# Use Claude by default when multiple agents are installed
default_agent = "claude"

# Only show Claude and my custom agent
only = ["claude", "my-local-llm"]

# Define a custom agent
[agents.my-local-llm]
command = "ollama run codellama"
name = "Local CodeLlama"
shell = true
shortcut = "L"

Session Management

Understanding how klaas manages terminal sessions.

Session Lifecycle

When you run klaas, it:

1. Authenticates (if needed) using OAuth Device Flow
2. Detects agents and presents a selection if multiple are installed
3. Creates a session on the klaas cloud
4. Spawns the agent in a pseudo-terminal (PTY)
5. Streams output encrypted to the cloud in real-time
6. Handles input from both local terminal and remote dashboard

Resuming Sessions

Use --resume to continue your previous session:

klaas --resume

This reconnects to the most recent session rather than starting fresh.

Session Storage

Sessions are stored encrypted on klaas servers. Only you can decrypt them using your account credentials. Session metadata (timestamps, status) is stored in plaintext for functionality.

Remote Access

Access your terminal sessions from anywhere.

Viewing Sessions

1. Go to klaas.sh
2. Log in with your account
3. Navigate to Sessions
4. Click on an active session to view it

The terminal view shows real-time output as it happens on your local machine.

Sending Input

From the web dashboard, you can:

• Type text: Click the input area and type. Press Enter to send.
• Approve permissions: When your agent requests permission, a notification appears. Click to approve or deny.

Multi-Device Access

You can view the same session from multiple devices simultaneously. All viewers see the same real-time output, and any viewer can send input.

Security

How klaas protects your terminal data.

End-to-End Encryption

klaas implements end-to-end encryption (E2EE) ensuring that only you can read your terminal sessions—not even the klaas team can decrypt your data.

┌─────────────┐     encrypted with      ┌─────────────┐
│ Your        │ ───────────────────────▶│ Stored on   │
│ Master Key  │     your password       │ Server      │
└─────────────┘                         └─────────────┘
       │
       │ decrypted locally on each device
       ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ CLI         │  │ Web Browser │  │ Mobile App  │
└─────────────┘  └─────────────┘  └─────────────┘

Key Principles

1. Zero-Knowledge Architecture: The server stores only encrypted data and your password-protected master key. Without your password, the data is unreadable.
2. Client-Side Encryption: All encryption and decryption happens on your devices. The server never sees plaintext content.
3. Multi-Device Access: All authenticated devices share the same master key, encrypted with your password.
4. Password-Protected Keys: Your master encryption key is encrypted with your password. If you forget your password, your data cannot be recovered (by design).

What's Protected

Credential Storage

klaas stores authentication credentials securely using your operating system's native credential storage:

• macOS: Keychain
• Windows: Credential Manager
• Linux: Secret Service (libsecret)

No sensitive data is written to disk in plain text.