Skip to content

chore(docs): update intro and glossary to reflect runtime architecture #179

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
feloy merged 1 commit into from
Apr 3, 2026
Merged

chore(docs): update intro and glossary to reflect runtime architecture #179

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 13 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@
[![codecov](https://codecov.io/gh/kortex-hub/kortex-cli/branch/main/graph/badge.svg)](https://codecov.io/gh/kortex-hub/kortex-cli)
[![Documentation](https://img.shields.io/badge/documentation-blue)](https://kortex-hub.github.io/kortex-cli/)

kortex-cli is a command-line interface for launching and managing AI agents with custom configurations. It provides a unified way to start different agents with specific settings including skills, MCP (Model Context Protocol) server connections, and LLM integrations.
kortex-cli is a command-line interface for launching and managing AI agents in isolated, reproducible workspaces. It creates runtime-based environments (containers, VMs, or other backends) where agents run with your project source code mounted, automatically configured and ready to use — no manual onboarding or setup required.

The architecture is built around pluggable runtimes. The first supported runtime is **Podman**, which creates container-based workspaces using a custom Fedora image. Additional runtimes (e.g., MicroVM, Kubernetes) can be added to support other execution environments.

**Supported Agents**

Expand All @@ -13,10 +15,13 @@ kortex-cli is a command-line interface for launching and managing AI agents with

**Key Features**

- Configure agents with custom skills and capabilities
- Connect to MCP servers for extended functionality
- Integrate with various LLM providers
- Consistent interface across different agent types
- Isolated workspaces per project, each running in its own runtime instance
- Pluggable runtime system — Podman is the default, with support for adding other runtimes
- Automatic agent configuration (onboarding flags, trusted directories) on workspace creation
- Multi-level configuration: workspace, global, project-specific, and agent-specific settings
- Inject environment variables and mount directories into workspaces at multiple scopes
- Connect to MCP servers and integrate with various LLM providers (including Vertex AI)
- Consistent CLI interface across different agent types and runtimes
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Use “consistent CLI” instead of “CLI interface.”

“CLI interface” is redundant wording; tightening this improves doc quality.

Suggested edit 
-- Consistent CLI interface across different agent types and runtimes
+- Consistent CLI across different agent types and runtimes
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- Consistent CLI interface across different agent types and runtimes
- Consistent CLI across different agent types and runtimes
🧰 Tools
🪛 LanguageTool

[style] ~24-~24: This phrase is redundant (‘I’ stands for ‘interface’). Use simply “CLI”.
Context: ...ders (including Vertex AI) - Consistent CLI interface across different agent types and runtim...

(ACRONYM_TAUTOLOGY)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 24, Replace the redundant phrase "CLI interface" with
"consistent CLI" in the README sentence that currently reads "Consistent CLI
interface across different agent types and runtimes" so it becomes "Consistent
CLI across different agent types and runtimes"; locate and update that exact
sentence in README.md to tighten wording.


## Getting Started

Expand Down Expand Up @@ -72,18 +77,15 @@ The underlying AI model that powers the agents. Examples include Claude (by Anth
### MCP (Model Context Protocol)
A standardized protocol for connecting AI agents to external data sources and tools. MCP servers provide agents with additional capabilities like database access, API integrations, or file system operations.

### Runtime
The environment where workspaces run. kortex-cli supports multiple runtimes (e.g., Podman containers), allowing workspaces to be hosted on different backends depending on your needs.

### Skills
Pre-configured capabilities or specialized functions that can be enabled for an agent. Skills extend what an agent can do, such as code review, testing, or specific domain knowledge.

### Workspace
A registered directory containing your project source code and its configuration. Each workspace is tracked by kortex-cli with a unique ID and a human-readable name. Workspaces can be accessed using either their ID or name in all commands (start, stop, remove, terminal).

**Workspace States:**
- `stopped` - The workspace instance is created but not running
- `running` - The workspace instance is actively running
- `error` - The workspace instance encountered an error
- `unknown` - The workspace state cannot be determined

## Scenarios

### Claude with a Model from Vertex AI
Expand Down
Loading