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

experimental-features = nix-command flakes

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 approve the device. The CLI then receives your credentials securely with end-to-end encryption.

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

# Start with a named session (for easy reconnection)
klaas --name refactor-tests
klaas -n api-work -a claude

# 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 connect

Connect to an existing session as a guest. You can specify either a session ID or a session name.

klaas connect <session-id|session-name>

Examples

# Connect by session name
klaas connect refactor-tests
klaas connect api-work

# Connect by session ID
klaas connect 01HQXK7V8G3N5M2R4P6T1W9Y0Z

When connected as a guest, you have full terminal interaction:

• See all terminal output in real-time
• Send keystrokes to the session
• All data is end-to-end encrypted

klaas sessions

List your available sessions with interactive selection. Navigate with arrow keys and press Enter to connect as a guest.

klaas sessions

Example Output

  Your klaas sessions

  ● refactor-tests       ~/projects/myapp              2 minutes ago
    01HQXK7V8G3N5M2R4P6T1W9Y0Z                         attached

    api-work             ~/work/api                    1 hour ago
    01HQXK8W9H4O6N3S5Q7U2X0Z1A                         detached

  Use ↑↓ arrows and Enter. Esc to cancel.

Sessions with a green dot (●) have an active host connection. Session names are set with klaas -n <name>.

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/)

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

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

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

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

# Add custom agents alongside built-in ones
# Mutually exclusive with `only`
also = ["my-custom-agent"]

# Custom agent definitions
[agents.my-custom-agent]
command = "/path/to/my-agent"
name = "My Custom Agent"
detect = ["my-agent", "myagent"]  # Binary names to check
hooks_type = "claude"              # "claude", "gemini", "codex", or "none"
shortcut = "X"                     # Single letter for selection menu
shell = false                      # Run through shell (default: false)
args = ["--verbose"]               # Default arguments

# Notification settings
[notifications]
enabled = true
events = ["permission_request", "task_complete"]

# Multi-connection input configuration
[session.input]
mode = "auto-lock"     # "host-only", "auto-lock", or "free-for-all"
idle_timeout_ms = 1500 # Lock timeout for auto-lock mode (ms)

# Analytics (tracks install/upgrade/uninstall
# events with version and platform only, no personal data)
analytics = true  # Set to false to disable

Session Management

Understanding how klaas manages terminal sessions.

Session Lifecycle

When you run klaas, it:

1. Authenticates (if needed) using device authorization flow with E2EE
2. Detects agents and presents a selection if multiple are installed
3. Spawns the agent (or shell) in a pseudo-terminal (PTY)
4. Captures all I/O and displays it on your local terminal
5. Streams output encrypted to the klaas cloud (when attached)
6. Handles remote input from web dashboard or CLI guest connections

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 or CLI guest connection, you can:

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

CLI Guest Mode

You can also connect to sessions from another terminal using the CLI:

# List your sessions
klaas sessions

# Connect to a session by name or ID
klaas connect my-session

Guest connections use the same E2EE as the web dashboard—the server cannot see your session content.

Guest Access

Multiple guests can connect to a session simultaneously (web dashboard, CLI, mobile). Each guest sees real-time output and can send input based on the session's input mode.

• Host attached: Guests can view and send input (based on input mode)
• Host detached: Guests have read-only access (can view history)

See Multi-Connection Input Modes for details on controlling who can type.

Multi-Connection Input Modes

Control how input is handled when multiple clients connect to your session.

When multiple clients connect to the same session (e.g., from your desktop CLI, phone browser, and tablet), you can control who is allowed to send terminal input. Configure this via the [session.input] section in your config file.

Input Modes

Auto-Lock Mode (Default)

auto-lock provides the best experience for most use cases:

1. Start typing from any connected device to acquire the input lock
2. Other clients see a "typing" indicator (e.g., "MacBook Pro typing")
3. Continue typing to keep the lock active
4. Lock automatically releases after idle timeout (default: 1500ms)
5. Any device can then acquire the lock by typing

Configuration

Add to your ~/.klaas/config.toml:

[session.input]
# Input mode: "host-only", "auto-lock", or "free-for-all"
mode = "auto-lock"

# Lock idle timeout in milliseconds (for auto-lock mode)
idle_timeout_ms = 1500

Example Configurations

# View-only for dashboard users (most restrictive)
[session.input]
mode = "host-only"

# Auto-lock with longer timeout
[session.input]
mode = "auto-lock"
idle_timeout_ms = 3000  # 3 seconds

# Open input from any client (least restrictive)
[session.input]
mode = "free-for-all"

Dashboard Status Indicators

The Dashboard terminal displays the current input status:

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.

┌──────────────────────────────────────────────────────────────────┐
│                        Your Password                             │
└──────────────────────────────────────────────────────────────────┘
                                │
                   ┌────────────┴────────────┐
                   ▼                         ▼
           ┌─────────────┐           ┌─────────────┐
           │  Auth Key   │           │   Enc Key   │
           │ (for login) │           │(for crypto) │
           └──────┬──────┘           └──────┬──────┘
                  │                         │
                  ▼                         ▼
           ┌─────────────┐           ┌─────────────────────────────┐
           │   Server    │           │  Master Key (MEK)           │
           │  verifies   │           │  - Stored encrypted on server│
           │   login     │           │  - Decrypted only on your   │
           └─────────────┘           │    devices                  │
                                     └──────┬──────────────────────┘
                                            │
                   ┌────────────────────────┼────────────────────────┐
                   ▼                        ▼                        ▼
            ┌───────────┐            ┌───────────┐            ┌─────────────┐
            │ Dashboard │            │    CLI    │            │Other Clients│
            │(password) │            │ (pairing) │            │             │
            └───────────┘            └───────────┘            └─────────────┘

         Server cannot decrypt your sessions - only your devices can.

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. The Dashboard uses your password; the CLI pairs securely without needing it.
4. Password-Protected Keys: Your master encryption key is encrypted with a key derived from 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.