kernex-agent-0.5.0 is not a library.

kx

CLI dev assistant powered by Kernex.

Features

11 LLM providers - Claude Code (default), Anthropic, OpenAI, Gemini, Ollama, OpenRouter, Groq, Mistral, DeepSeek, Fireworks, xAI; AWS Bedrock available behind a Cargo feature
Stack detection - Automatically detects Rust, Node/TypeScript, Python, Flutter/Dart, PHP, Go, Java, and Swift projects
Persistent memory - Remembers decisions, patterns, and context across sessions per project, with FTS5 full-text search
Cost telemetry - /cost slash command surfaces cumulative tokens, estimated cost, and prompt-cache hit ratio
OS sandbox - Tool execution runs under Seatbelt (macOS) or Landlock (Linux) for filesystem and network isolation
Skills system - Install reusable behavior packages (kx skills add owner/repo) with SHA-256 integrity verification and trust levels
MCP integration - Connects to MCP servers per skill or project for extra tool surface
Headless server - kx serve exposes an authenticated HTTP API for job submission, webhooks, and multi-step workflows
Multi-agent pipelines - Topology-driven workflows with reality-check gates
Auto-compact - Optional automatic context summarization when approaching the model's window
One-shot or interactive - Run kx "question" for quick answers or kx dev for a REPL with multiline input via """ delimiters
Project configuration - Per-project settings via .kx.toml

What Can kx Do?

kx is your AI coding assistant. It can:

Answer questions about your code, errors, and architecture
Suggest refactoring patterns and improvements
Hunt for bugs and explain potential issues
Explain errors with context from your codebase
Remember context across sessions (facts, decisions, patterns)
Search conversations with full-text search

Limitations:

File and shell tools run under sandbox; outside that surface kx suggests changes rather than applying them.
An LLM provider must be available (default: Claude Code CLI; alternatives use API keys via env or .kx.toml).

Requirements

kx needs at least one LLM provider configured. The default is the Claude Code CLI; any other provider can be selected via --provider or .kx.toml.

Dependency	Minimum Version	When required
Rust toolchain	1.74+	For `cargo install kernex-agent` (not needed if using Docker)
Claude CLI	2.0+	Only when using the default `claude-code` provider
Docker + Compose v2	24+	Only for the Docker deployment path

Provider options

Provider	Auth	Set with
`claude-code` (default)	Subscription via local CLI	`claude --version` to verify
`anthropic`	API key	`ANTHROPIC_API_KEY` env var
`openai`	API key	`OPENAI_API_KEY` env var
`gemini`	API key	`GEMINI_API_KEY` env var
`ollama`	Local	Run `ollama serve`
`openrouter`	API key	`OPENROUTER_API_KEY` env var
`groq`	API key	`GROQ_API_KEY` env var
`mistral`	API key	`MISTRAL_API_KEY` env var
`deepseek`	API key	`DEEPSEEK_API_KEY` env var
`fireworks`	API key	`FIREWORKS_API_KEY` env var
`xai`	API key	`XAI_API_KEY` env var

To install Claude Code (the default):

Visit claude.ai/download
Download and install for your platform (macOS, Linux, Windows)
Run claude --version to verify installation (must be 2.0+)

Documentation: docs.anthropic.com/en/docs/claude-code

Platform Support

Platform	Status	Notes
macOS (Apple Silicon & Intel)	Fully supported	Sandbox via Seatbelt
Linux (x86_64, aarch64)	Fully supported	Sandbox via Landlock; partial enforcement on kernel 5.13+, full enforcement on 6.x+
Windows	Experimental	No sandbox support; requires WSL2 for best experience

The sandbox layer comes from kernex-sandbox and is used by the runtime to isolate AI subprocesses. On platforms without sandbox support, kx still works but without process isolation.

Installation

Quick Install (requires Rust)

cargo install kernex-agent

Verify installation:

kx --version

New to Rust?

Install Rust first from rustup.rs:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
cargo install kernex-agent

From Source

git clone https://github.com/kernex-dev/kernex-agent.git
cd kernex-agent
cargo install --path .

First Run

cd /path/to/your/project
kx

kx automatically detects your project's stack (Rust, Node, Python, etc.) and starts an interactive session:

kx dev my-project (Rust)
Type /help for commands, /quit to exit.

> explain the error in src/main.rs

For one-shot questions:

kx "what does this function do?"

Quick Start

One-shot mode

# Ask a quick question
kx "explain this error: cannot borrow as mutable"

# With dev subcommand
kx dev "add error handling to src/lib.rs"

Interactive mode

# Start interactive session in current project
kx

# Or explicitly
kx dev

In interactive mode, type your questions and get responses. Use /help for available commands.

Multiline input

For pasting code blocks or multi-line content:

> """
  1 | fn main() {
  2 |     println!("Hello");
  3 | }
  4 | """
  (3 lines captured)

Serve Mode

kx serve runs kx as a headless HTTP daemon. Deploy it on a VPS or Mac Mini to accept agent jobs from external triggers, webhooks, or CI pipelines — no active terminal needed.

Deploy with Docker (recommended)

No Rust installation required. Pull the pre-built image from GHCR.

Mac Mini or local server (no TLS):

curl -O https://raw.githubusercontent.com/kernex-dev/kernex-agent/main/deploy/docker-compose.local.yml
curl -O https://raw.githubusercontent.com/kernex-dev/kernex-agent/main/deploy/.env.example
cp .env.example .env
# Edit .env: set KERNEX_AUTH_TOKEN and CLAUDE_CREDENTIALS_PATH
docker compose -f docker-compose.local.yml up -d
curl http://localhost:8080/health

VPS with a domain and automatic TLS:

mkdir kx-server && cd kx-server
curl -O https://raw.githubusercontent.com/kernex-dev/kernex-agent/main/deploy/docker-compose.vps.yml
curl -O https://raw.githubusercontent.com/kernex-dev/kernex-agent/main/deploy/Caddyfile
curl -O https://raw.githubusercontent.com/kernex-dev/kernex-agent/main/deploy/Dockerfile.caddy
curl -O https://raw.githubusercontent.com/kernex-dev/kernex-agent/main/deploy/.env.example
cp .env.example .env
# Edit .env: set KERNEX_AUTH_TOKEN, CLAUDE_CREDENTIALS_PATH, DOMAIN, ACME_EMAIL
docker compose -f docker-compose.vps.yml up -d
curl https://api.yourdomain.com/health

The image ships with 16 pre-loaded skills and 4 workflows (PR review, feature design, security audit, GEO audit). Skills and job data persist in a named Docker volume across restarts and updates.

For the complete step-by-step guide, provider options, and customization: deploy/SETUP.md.

Run from the CLI

If you already have kx installed:

kx serve --auth-token mysecrettoken
kx serve --host 0.0.0.0 --port 9000 --auth-token mysecrettoken --workers 8

The auth token can also be set via environment variable:

export KERNEX_AUTH_TOKEN=mysecrettoken
kx serve

Flags

Flag	Default	Description
`--host`	`127.0.0.1`	Bind address
`--port`	`8080`	Listen port
`--auth-token`	(required)	Bearer token for API authentication
`--workers`	`4`	Max concurrent agent jobs

Provider flags (--provider, --model, --api-key, etc.) work the same as in interactive mode and set the default for all jobs.

API

All endpoints except /health require Authorization: Bearer <token>. Jobs run asynchronously — /run returns a job_id, poll /jobs/{id} until status is done or failed.

Method	Path	Description
`GET`	`/health`	Health check (no auth required)
`POST`	`/run`	Submit an agent job
`GET`	`/jobs`	List recent jobs (default limit: 50)
`GET`	`/jobs/{id}`	Get job status and output
`POST`	`/webhook/{event}`	Trigger a job from a webhook

# Submit a job
curl -s -X POST http://localhost:8080/run \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Review this Express handler for SQL injection",
    "skills": ["security-engineer"]
  }' | jq .

# Poll for result
curl -s http://localhost:8080/jobs/<job_id> \
  -H "Authorization: Bearer <token>" | jq .

# Webhook trigger (e.g. from GitHub Actions)
curl -s -X POST http://localhost:8080/webhook/pr-review \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"message": "PR #42: add user auth endpoint"}'

Commands

Command	Description
`/help`	Show available commands
`/search <query>`	Search past conversations (FTS5)
`/history`	Show recent conversation history (last 20 messages)
`/stack`	Show detected stack and project info
`/memory`	Show memory stats and database size
`/facts`	List stored facts
`/facts delete <key>`	Delete a specific fact
`/config`	Show active configuration
`/retry`	Retry last failed message
`/clear`	Close current conversation
`/quit` or `/exit`	Exit kx

Configuration

Create a .kx.toml file in your project root to customize behavior:

# Override auto-detected stack
stack = "rust"

# Add project-specific instructions to the system prompt
system_prompt = """
This project uses a custom error type in src/error.rs.
Always use MyError instead of anyhow.
"""

# Provider settings
[provider]
model = "claude-sonnet-4-20250514"  # Model to use
max_turns = 10                       # Max agentic turns per request
timeout_secs = 300                   # Request timeout in seconds

Stack options

Valid values for stack:

rust
node, javascript, typescript
python
flutter, dart
php
go, golang
java, kotlin
swift, swiftui

Skills

kx supports the Agent Skills standard — an open format for reusable AI agent capabilities. Skills are SKILL.md files that extend kx with specialized knowledge and guidelines.

Installing Skills

# Install from GitHub
kx skills add anthropics/skills/rust-best-practices

# Install with specific trust level
kx skills add vercel-labs/agent-skills/web-design-guidelines --trust standard

# List installed skills
kx skills list

# Verify integrity (SHA-256)
kx skills verify

# Remove a skill
kx skills remove rust-best-practices

Skills can also be managed from the interactive REPL with /skills, /skills add, /skills remove, and /skills verify.

Permission Model

Skills are text-only (SKILL.md), but they influence the AI's behavior. kx uses a permission model to give users control:

Permission	Description	Risk
`context:files`	Reference project files	Low
`context:git`	Reference git history	Low
`suggest:edits`	Suggest code modifications	Medium
`suggest:commands`	Suggest shell commands	High
`suggest:network`	Suggest network requests	High

Trust Levels

Level	Permissions	Use Case
sandboxed (default)	`context:files` only	Unknown skills
standard	`context:*`, `suggest:edits`	Verified skills
trusted	All permissions	Allowlisted sources

Configuration

Configure skills behavior in .kx.toml:

[skills]
default_trust = "sandboxed"
trusted_sources = ["anthropics/skills", "vercel-labs/agent-skills"]
blocked = ["suspicious-skill"]

Security

Text only — Skills are markdown files. No scripts, binaries, or executables.
SHA-256 integrity — Every installed skill is hashed. Use kx skills verify to detect tampering.
Size limits — Skills are capped at 64 KB.
Name validation — Strict naming rules prevent path traversal attacks.
Prompt guardrails — Skills are injected into the system prompt with XML delimiters and trust metadata. The AI is instructed to treat skills as untrusted third-party content.
Audit log — All skill operations (install, remove, verify, load) are logged to skills-audit.log.
Blocklist — Block specific skills via .kx.toml configuration.

Stack Detection

kx automatically detects your project's stack by looking for these files (in order):

File	Detected Stack
`Cargo.toml`	Rust
`go.mod`	Go
`Package.swift`	Swift/SwiftUI
`pubspec.yaml`	Flutter/Dart
`pom.xml`	Java
`build.gradle` / `build.gradle.kts`	Java
`package.json`	JavaScript/TypeScript (Node)
`requirements.txt`	Python
`pyproject.toml`	Python
`Pipfile`	Python
`composer.json`	PHP

The first match wins. Override with stack in .kx.toml if needed.

Data Storage

Project data is stored in:

~/.kx/projects/{project-name}/

Where {project-name} is derived from the directory name. Each project maintains its own:

Conversation history
Stored facts
Input history (readline)

Providers

kx defaults to Claude Code CLI as its AI backend. The underlying kernex-providers crate supports additional backends:

Flag	Provider	Requires
`--provider claude-code`	Claude Code CLI (default)	Claude CLI installed
`--provider anthropic`	Anthropic API	`ANTHROPIC_API_KEY`
`--provider openai`	OpenAI API	`OPENAI_API_KEY`
`--provider ollama`	Ollama (local)	Ollama running at `localhost:11434`
`--provider gemini`	Google Gemini	`GEMINI_API_KEY`
`--provider openrouter`	OpenRouter	`OPENROUTER_API_KEY`
`--provider groq`	Groq	`GROQ_API_KEY`
`--provider mistral`	Mistral	`MISTRAL_API_KEY`
`--provider deepseek`	DeepSeek	`DEEPSEEK_API_KEY`
`--provider fireworks`	Fireworks AI	`FIREWORKS_API_KEY`
`--provider xai`	xAI (Grok)	`XAI_API_KEY`

AWS Bedrock is available as an optional compile-time feature. Build with --features bedrock to enable --provider bedrock. Requires standard AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION). Bedrock is not included in the 11 built-in provider count above.

Provider is auto-detected if --provider is omitted. Override the model with --model <name>.

You can also set defaults via environment variables:

export KERNEX_PROVIDER=anthropic
export KERNEX_MODEL=claude-opus-4-6-20251001

Architecture

kx is a thin CLI wrapper around the Kernex runtime:

kernex-runtime - Core engine: Runtime::run() drives the agentic loop, RuntimeBuilder wires all subsystems
kernex-providers - AI backends: Claude Code CLI, Anthropic, OpenAI, Ollama, Gemini, OpenRouter, Groq, Mistral, DeepSeek, Fireworks, xAI (11 built-in; AWS Bedrock optional)
kernex-core - Shared types (Request, Response, Context), HookRunner trait for tool lifecycle events
kernex-memory - SQLite-backed persistent memory with conversation history and reward-based learning (transitive via kernex-runtime)
kernex-skills - Skill loader for SKILL.md files (Skills.sh compatible format)

The HookRunner trait lets you intercept tool calls before and after execution (pre_tool / post_tool / on_stop). kx uses this for --verbose output and session summaries.

For the full implementation spec (provider resolution, runtime wiring, hook runner, KAIROS scheduler), see kernex/docs/kernex-agent.md.

For details on the underlying runtime, see kernex-dev/kernex.

Extending with Skills

kx can be extended with MCP-based and CLI-based skills from kernex-dev.

Available skills: filesystem, git, playwright, github, postgres, sqlite, brave-search, pdf, webhook.

See kernex-dev/examples/skills for setup.

Troubleshooting

"Claude CLI not found"

Ensure Claude Code is installed and in your PATH:

claude --version

If not found, install from claude.ai/download.

"Permission denied: ~/.kx"

Create the directory manually:

mkdir -p ~/.kx

Database locked

Only one kx session per project can run at a time. Close other sessions or wait for them to complete.

Security

The runtime executes LLM tool calls (file reads/writes, shell commands, MCP tools, custom toolboxes) inside an OS sandbox: Seatbelt on macOS, Landlock on Linux. Skills installed via kx skills add are pinned by SHA-256 in ~/.kx/projects/<name>/skills.toml and verified on every load; tampering causes the skill to be refused and an audit-log entry written.

If you find a vulnerability, please open a private security advisory at github.com/kernex-dev/kernex-agent/security/advisories/new rather than a public issue. We rotate token-bound auth and ship sandbox fixes as patch releases.

License

Apache-2.0 OR MIT

kernex-agent 0.5.0

kx

Features

What Can kx Do?

Requirements

Provider options

Platform Support

Installation

Quick Install (requires Rust)

New to Rust?

From Source

First Run

Quick Start

One-shot mode

Interactive mode

Multiline input

Serve Mode

Deploy with Docker (recommended)

Run from the CLI

Flags

API

Commands

Configuration

Stack options

Skills

Installing Skills

Permission Model

Trust Levels

Configuration

Security

Stack Detection

Data Storage

Providers

Architecture

Extending with Skills

Troubleshooting

"Claude CLI not found"

"Permission denied: ~/.kx"

Database locked

Security

License