kodx 0.1.0

Docker-based code execution environment with LLM integration

Kodx - Containerized LLM Automation

Inspired by OpenAI Codex, Kodx implements an isolated environment for LLMs to interact with through shell commands.

Features

• Create multiple shell sessions on demand: Unlike Claude Code or Codex-cli, Kodx allows LLMs to create multiple shell sessions on demand.
• Shell Timeout & Partial output: Each shell command has a timeout and partial output is returned even if the command is not finished yet.
• Long-running shell commands: Kodx supports long-running shell commands, timeout does not automatically kill the command, instead, it will return the partial output. This allows LLMs to start a server in one shell, and then use another shell to interact with the server.
• Powered by LLMProc: Built on top of LLMProc for robust LLM program management and execution.
• Docker & Setup Script: Choose your own Docker image and setup script to initialize the container.
• Export: Export the container changes to the host filesystem for inspection and automation.
• Local Directory Support: Copy local directories into containers for analysis (note: be careful with secrets in the local directory)
• Cost Control: Built-in limits to manage API spending
• PTY Support: Full terminal capabilities including interrupt handling
• JSON Output: Structured results for automation and CI/CD integration

Kodx is production ready and actively maintained.

Installation

uv pip install kodx

Or run it directly:

uvx kodx [OPTIONS]  # Uses default assistant
uvx kodx PROGRAM_PATH [OPTIONS]  # Uses custom program

Quick Start

Default Assistant (New!)

Kodx now includes a built-in general-purpose assistant:

# Use default assistant with current directory
kodx --prompt "analyze this codebase and suggest improvements"

# Use default assistant with clean container
kodx --repo-dir "" --prompt "create a Flask web application"

# Use default assistant with specific directory
kodx --repo-dir ./my-project --prompt "run the tests"

Custom Programs

For specialized tasks, use the production configurations from .github/config/:

# Code analysis expert (used in GitHub workflows)
kodx .github/config/kodx-ask-program.yaml --repo-dir . --prompt "review architecture"

# Code implementation expert (used in GitHub workflows)
kodx .github/config/kodx-code-program.yaml --repo-dir "" --prompt "create FastAPI app"

Production Example

Here's how Kodx is used in production for automated code implementation (from .github/workflows/kodx-code.yml):

# Using Kodx from PyPI
uvx kodx .github/config/kodx-code-program.yaml \
  --repo-dir . \
  --prompt-file prompt.txt \
  --export-dir ./kodx-changes \
  --cost-limit 2.0 \
  --json-output-file kodx_result.json

This workflow automatically:

1. Processes code change requests from GitHub issues/PRs
2. Runs Kodx with cost controls to implement changes
3. Exports the modified files to ./kodx-changes
4. Creates a PR with the implemented changes

Documentation

For a map of all technical guides, see docs/index.md.

CLI Interface

kodx [PROGRAM_PATH] [OPTIONS]

Arguments:

• PROGRAM_PATH: Path to LLM program file (YAML/TOML). If omitted, uses built-in assistant.

Common Options:

• --repo-dir: Local directory to copy into container (default: current directory, use "" for clean container)

Key Options:

• --prompt, -p: Prompt text (or read from stdin)
• --image: Docker image to use (default: python:3.11)
• --setup-script: Setup script to execute in container before task
• --export-dir: Host directory to export container changes
• --cost-limit: Stop execution when cost exceeds this limit in USD
• --disable-network-after-setup: Disconnect container internet access after setup for security isolation
• --json: Output results as JSON for automation
• --json-output-file FILE: Write JSON results to file instead of stdout

Docker Configuration

You can configure Docker settings directly in your program YAML/TOML files:

# Program file with Docker configuration
model:
  name: claude-3-7-sonnet-20250219
  provider: anthropic

prompt:
  system: |
    You are an expert software engineer...

parameters:
  max_tokens: 20000
  temperature: 0.7

# Docker configuration section
docker:
  image: python:3.12-slim  # Docker image to use
  disable_network_after_setup: true  # Disconnect internet after setup for security
  setup_script: |
    #!/bin/bash
    apt-get update
    apt-get install -y git curl
    pip install pytest black

Important: CLI options always take precedence over configuration in the program file. For example, if you specify --image or --setup on the command line, those values override any docker.image or docker.setup_script in your YAML/TOML file.

See docker-config.md for detailed documentation on precedence rules.

• --quiet, -q: Suppress most output

Example Programs

Kodx includes several expert programs:

Code Analysis

# Repository analysis (production config)
kodx .github/config/kodx-ask-program.yaml --repo-dir . --prompt "What is the architecture of this project?"

Code Implementation

# Code implementation (production config)
kodx .github/config/kodx-code-program.yaml --repo-dir "" --prompt "Create a REST API with FastAPI"

Setup Scripts

Kodx supports custom setup scripts to prepare the container environment before LLM execution:

# Execute setup script before task
kodx .github/config/kodx-code-program.yaml --repo-dir . --setup setup.sh --prompt "Run tests"

Setup Script Features

• Execution Context: Scripts run in /workspace directory with access to repo files
• Shell Scripts Only: Always executed as bash /tmp/setup.sh
• Fail Fast: If setup script fails, entire execution stops
• Clean Isolation: Setup script copied to /tmp, automatically cleaned up

Example Setup Script

#!/bin/bash
# setup.sh
echo "Installing dependencies..."
pip install -r requirements.txt
echo "Setup completed successfully!"

Export Functionality

Kodx can export container changes to the host filesystem for inspection and GitHub automation:

# Export container changes after LLM execution
kodx .github/config/kodx-code-program.yaml --repo-dir . --prompt "Fix bug" --export-dir ./changes

Export Features

• Automatic Export: Copies entire container workspace to host directory after LLM execution
• Smart Detection: Exports /workspace/repo for repository tasks, /workspace for clean containers
• GitHub Ready: Perfect for GitHub Actions workflows and PR creation
• Directory Creation: Automatically creates export directory if it doesn't exist

GitHub Automation Example

See the workflow files under .github/workflows for real automation examples.

Cost Control

Kodx includes built-in cost tracking and budget controls to help manage API expenses:

Cost Limits

Set a maximum USD cost for execution to prevent runaway costs:

# Stop execution if cost exceeds $0.50
kodx .github/config/kodx-code-program.yaml --repo-dir . --cost-limit 0.50 --prompt "Large task"

# Cost-controlled automation
kodx .github/config/kodx-ask-program.yaml --repo-dir . --cost-limit 1.00 --json --prompt "Full analysis"

Cost Reporting

When using --json output, cost information is automatically included:

{
  "api_calls": 3,
  "usd_cost": 0.0234,
  "last_message": "Task completed successfully",
  "stderr": ["INFO: Analysis complete"],
  "stop_reason": "end_turn"
}

Stop Reasons

Kodx provides clear indicators for why execution stopped:

• "end_turn": Normal completion
• "cost_limit_exceeded": Hit the specified cost budget
• "max_iterations": Reached iteration limit
• "tool_error": Tool execution failed

GitHub Actions Integration

Cost limits are automatically applied in GitHub workflows:

• Code implementation: --cost-limit 2.0 (up to $2.00)
• Q&A responses: --cost-limit 1.0 (up to $1.00)

Cost information is displayed in workflow status comments for transparency.

Available Tools

Kodx provides exactly 2 tools to LLMs:

1. feed_chars(chars) - Send characters/commands to the shell

   • Execute commands: feed_chars("ls -la")
   • Create files: feed_chars("echo 'content' > file.txt")
   • Send Ctrl+C: feed_chars("\\x03")
   • Run interactive programs: feed_chars("python")

2. create_new_shell() - Start a fresh shell session

   • Resets environment state
   • Useful when shell gets into bad state
   • Returns to /workspace directory

LLM Programs

Programs are YAML/TOML files that define the LLM behavior, following llmproc configuration format:

# my-program.yaml
model:
  name: claude-sonnet-4
  provider: anthropic

prompt:
  system: |
    You are an expert in [DOMAIN] with access to a Docker container.

    The repository is available at /workspace/repo (if provided).
    Available tools: feed_chars, create_new_shell

    [Add your specific expertise and instructions]

parameters:
  max_tokens: 8000
  temperature: 0.1

Creating Custom Programs

1. Copy a production configuration from .github/config/ directory
2. Modify the system prompt for your specific use case
3. Adjust model parameters as needed
4. Test your program: kodx my-program.yaml --repo-dir . --prompt "test"

Docker Images

Requirements

Kodx requires Docker images with the following pre-installed:

• Python 3.7+ and pip
• bash shell
• curl for internal communication

Recommended Images

• python:3.11 (default) - Full Python image with curl and build tools
• python:3.12 - Latest Python version with full toolset
• python:3.11-slim - Lightweight option (requires curl installation)

Custom Images

For custom requirements, create images based on Python base images:

FROM python:3.11-slim
RUN apt-get update && apt-get install -y git build-essential
# Add your custom tools

Or extend other base images:

FROM ubuntu:22.04
RUN apt-get update && apt-get install -y python3 python3-pip curl bash git
# Add your custom setup

GitHub Actions Integration

Kodx is perfect for GitHub Actions workflows with export functionality for automated PR creation:

See .github/workflows for sample automation and analysis workflows using Kodx.

Automation & CI/CD

JSON Output

When using --json, Kodx outputs structured results:

{
  "api_calls": 3,
  "usd_cost": 0.0156,
  "last_message": "Analysis complete. Found 2 potential issues...",
  "stderr": ["INFO: Container initialized", "INFO: Analysis complete"],
  "stop_reason": "end_turn"
}

Architecture

Kodx is built on these principles:

1. Minimal Interface - Only expose essential shell interaction tools
2. Explicit Behavior - No magic defaults, all actions are explicit
3. Container Isolation - Each session gets a clean Docker environment
4. Local Directory Focus - Simple file copying, no git complexity
5. llmproc Compatibility - Follow proven CLI patterns

Program vs Execution Separation

• Program files (YAML/TOML) define LLM behavior and expertise
• CLI options define execution context (container, directory, etc.)
• Clean separation allows reusing programs across different contexts

Development

# Clone and install in development mode
git clone https://github.com/kodx/kodx
cd kodx
pip install -e ".[dev]"

# Run tests (multiple tiers available)
make test         # Fast unit tests (no Docker required)
make test-docker  # Integration tests (requires Docker)
make test-all     # Complete test suite

# Code quality
make check        # Format and lint code
make lint         # Check code style
make format       # Auto-format code

Testing Tiers

Kodx uses a tiered testing approach:

• make test - Fast unit tests (~0.2s, no external dependencies)
• make test-docker - Docker integration tests (~1-2min, requires Docker)
• make test-system - System workflow tests (~2-5min, requires Docker)
• make test-perf - Performance benchmarks (~3-10min, requires Docker)

See TESTING.md for detailed testing documentation.

License

Apache License 2.0 - see LICENSE file for details.

Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines.

Related Projects

• llmproc - LLM process management framework
• SWE-agent - AI software engineer