Kagent

Kagent is an intelligent agent system built around the Codex protocol. It provides a CLI, backend services, a controller, and a web UI. The codebase is organized as a Rust workspace, and the frontend is built with Next.js and managed via bun.

Repository Layout

• kagent-cli: CLI entrypoint.
• kagent-api-server: REST API service.
• kagent-codex-server: Codex protocol server.
• kagent-controller: Sandbox/Pod controller.
• kagent-core: Core business logic.
• kagent-config: Configuration definitions and loading.
• kagent-sandbox: Sandbox management.
• kagent-sandbox-type: Sandbox type definitions.
• kagent-assembler: File fetching and assembly inside containers.
• kagent-db: Database access layer.
• kagent-db-migration: Database migrations.
• kagent-observability: Observability and telemetry.
• kagent-etl: ETL-related components.
• kagent-event: Event-related components.
• kagent-git: Git-related components.
• kagent-util: Shared utilities.
• kagent-ui: Web UI.
• codex/, codex-utils/: Codex protocol implementation and utilities.

Quick Start

Requirements

• Rust (see rust-toolchain.toml for the pinned version)
• bun (see kagent-ui/package.json for the version)
• Postgres (used by the API server and migrations)

Configuration

Kagent loads configuration from the following locations (low to high priority):

• ${KAGENT_HOME:-~/.kagent}/config.toml
• .kagent/config.toml within the repo (searched upwards to the project root)

Example configuration:

[api_server]
addr = "127.0.0.1:8080"
auto_migrate = true

[database]
url = "postgres://user:pass@127.0.0.1:5432/kagent"

Run Backend Services

cargo run -p kagent-cli -- codex-server
cargo run -p kagent-cli -- api-server
cargo run -p kagent-cli -- controller
cargo run -p kagent-cli -- db migrate

Common environment variables:

• KAGENT_CODEX_PORT: Port used by the API server to connect to the Codex server (default 8080).
• KAGENT_POLL_INTERVAL_SECS: Controller polling interval in seconds (default 10).
• KAGENT_HOME: Custom config directory.

Show all CLI commands:

cargo run -p kagent-cli -- --help

Run Frontend

cd kagent-ui
bun install
bun dev

Open http://localhost:3000 in your browser.

Generate Frontend Protocol Code

kagent-ui/lib/codex-app-server is a generated directory and should not be edited manually. Regenerate after protocol changes:

cargo run --bin codex -- app-server generate-ts -o kagent-ui/lib/codex-app-server

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Development Notes

• After modifying Rust code, ensure cargo check succeeds for the workspace.
• For the frontend, use bun lint as needed.