Embeddable Autonomous Agent Runtime for Software Engineering

codepilot.mp4

Embeddable Autonomous Agent (EAA) • Code-as-Interface Runtime • Terminal Multiplexer • MIT Licensed

pip install codepilot-ai

What CodePilot Is

CodePilot is a Python library for embedding autonomous software-engineering agents into your own products: CLIs, FastAPI services, hosted code-server workspaces, internal developer tools, CI repair systems, and local automation.

It is intentionally not a hosted chatbot UI. The package gives applications a runtime: model inference, tool execution, file editing, terminal control, persistence, hooks, and completion semantics. You bring the product surface, auth model, sandbox, database, and deployment strategy.

Version: 0.9.37

Full user documentation lives at: https://Jahanzeb-git.github.io/codepilot/

⚡ CodePilot Workspace (Daemonless Containerization)

In addition to the Python library, this repository ships CodePilot Workspace — a self-contained, daemonless Linux containerization engine written in Go. It allows developers to run the full CodePilot agentic IDE locally without relying on the Docker daemon.

Built for systems engineers and low-level virtualization environments (like Unikraft), the unified Go binary directly pulls OCI images, flattens them, and constructs isolated environments using pure Linux kernel primitives:

• Namespaces: CLONE_NEWPID, CLONE_NEWUTS, CLONE_NEWNS for process, hostname, and mount isolation.
• Resource Control: Cgroups v2 for deterministic memory and process limits.
• Zero-Dependency: Uses go-containerregistry to stream and extract GHCR image layers concurrently without any host container runtime.
• Process Lifecycle: Tracks container state purely via /proc/<pid>/exe symlink verification, eliminating stale PID recycling bugs.

Quick Start (Linux)

Install the pre-compiled binary:

curl -fsSL https://raw.githubusercontent.com/Jahanzeb-git/codepilot/main/cloud/distribution/install.sh | bash

Launch the workspace from any local directory:

cd ~/my-project
codepilot-workspace

(Pulls the OS rootfs on first run, provisions the container, and opens a chromeless app-window IDE instantly bound to your local files).

Quick Start (Python Library)

Create an agent.yaml:

agent:
  name: CodePilot
  role: Autonomous software engineering agent.

  model:
    provider: anthropic
    name: claude-sonnet-4-5
    api_key_env: ANTHROPIC_API_KEY

  runtime:
    work_dir: ./workspace
    max_steps: 20
    unsafe_mode: false

  tools:
    - name: read_file
      enabled: true
    - name: execute
      enabled: true
      config:
        require_permission: true
    - name: read_output
      enabled: true
    - name: send_input
      enabled: true
    - name: terminate_terminal
      enabled: true
    - name: find
      enabled: true

Gemini can be configured with a Gemini API key from Google AI Studio:

agent:
  model:
    provider: gemini
    name: gemini-3.5-flash
    api_key_env: GEMINI_API_KEY

Run the agent:

from codepilot import Runtime, on_stream, on_finish

runtime = Runtime("agent.yaml", stream=True)

@on_stream(runtime)
def stream(text: str, **_):
    print(text, end="", flush=True)

@on_finish(runtime)
def finish(summary: str, **_):
    print(f"\nDone: {summary}\n")

summary = runtime.run("Inspect the project and fix the failing tests.")
print(summary)

Async applications should use AsyncRuntime:

from codepilot import AsyncRuntime

runtime = AsyncRuntime("agent.yaml", session="db", db=async_engine, stream=True)
summary = await runtime.run("Refactor the repository layer to use async SQLAlchemy.")

Architecture

CodePilot is designed as a library-first runtime that can be embedded under many product surfaces.

flowchart TD
    A[Your app: CLI, FastAPI, code-server extension, desktop app] --> B[CodePilot Runtime]
    B --> C[LLM Provider]
    B --> D[Tool Registry]
    D --> E[Filesystem Tools]
    D --> F[Terminal Tools]
    D --> G[Search and Context Tools]
    B --> H[Session Backend]
    H --> I[Memory]
    H --> J[File JSON]
    H --> K[SQLAlchemy Database]
    F --> L[PTY / ConPTY]
    L --> M[Unix Socket Multiplexer on POSIX]

Loading

For hosted web IDE deployments, the intended shape is a small control plane plus disposable per-user runtime machines:

flowchart LR
    Browser --> FlyProxy["Fly Proxy"]
    FlyProxy --> CodeServer["code-server :8080"]
    CodeServer --> Extension["Custom code-server extension"]
    Extension --> RuntimeSock["/run/codepilot/runtime.sock"]
    RuntimeSock --> Daemon["CodePilot runtime daemon"]
    Daemon --> TerminalSock["/tmp/codepilot_main.sock"]
    Daemon --> Postgres[("Postgres / Neon")]
    Daemon --> ObjectStore[("Backblaze B2 snapshots")]
    Daemon --> Workspace["Workspace files"]

Loading

Why Code-as-Interface

Most agent frameworks force the model to express actions as JSON function calls. CodePilot uses a search/replace-native Code-as-Interface protocol: each workspace mutation is a self-contained conflict-marker block, and tool calls live in a fresh ephemeral codepilot.py block:

I will inspect the failing test first.

codepilot.py
<<<<<<< SEARCH
=======
view_file("tests/test_api.py")
execute("main", "pytest tests/test_api.py -q", timeout=30)
>>>>>>> REPLACE

The runtime executes only the generated ephemeral codepilot.py script. Ordinary Python markdown remains display text and is never executed.

This design is useful because software work is naturally procedural:

• Agents often need several tool calls in a deliberate order.
• Tool results need to feed control flow inside the same step.
• File writes use reviewable, content-addressed SEARCH/REPLACE blocks instead of fragile escaped strings or positional payloads.
• Developers need observable execution results, not opaque function-call envelopes.

The model still operates under a strict protocol:

• <path> on its own line immediately before <<<<<<< SEARCH: a complete file mutation.
• codepilot.py with an empty SEARCH section: fresh executable tool script.
• No tool calls in a response: the turn ends and control returns to the user.

This aligns with research showing that LLM agents benefit from interleaving reasoning and environment actions, as in ReAct, and from well-designed agent-computer interfaces for software engineering tasks.

How File Editing Works

Each block is applied by uniquely finding the SEARCH content in the current file, then replacing it with the REPLACE content. A zero-match or multi-match SEARCH section is rejected without guessing.

config.py
<<<<<<< SEARCH
TIMEOUT = 30
=======
TIMEOUT = 60
>>>>>>> REPLACE

For creation or a complete rewrite, leave the SEARCH section empty. If an OS-level failure occurs after a large block is parsed, CodePilot reports block_cache_id; repair the condition in codepilot.py and call retry_block(id) to replay the exact cached operation.

Safety properties:

• Paths are constrained to runtime.work_dir unless unsafe_mode: true.
• Edits use unique content matching before mutation; SEARCH sections are never trusted to be positionally correct, only content-correct.
• Multiple blocks are applied against evolving in-memory content, then committed atomically per file.
• Tool results are appended back into the conversation as ground truth.

How Terminal Tools Work

CodePilot starts a default terminal session named main when the runtime is created. The session persists across run() calls.

execute("main", "pytest tests/ -v", timeout=30)

Long-running commands return with status: running instead of hanging the agent:

execute("server", "uvicorn app.main:app --port 8000", timeout=4, new_terminal=True)
read_output("server", timeout=10)
execute("main", "pytest tests/test_api.py -v", timeout=30)
send_input("server", "\x03", timeout=5)

Terminal architecture:

• Linux/macOS use pexpect and a PTY.
• Windows 10 1809+ uses ConPTY through pywinpty.
• POSIX terminal sessions are exposed through a Unix socket multiplexer.
• Multiple clients can attach to the same terminal stream, enabling a code-server extension or xterm.js bridge to share the shell with the agent.

flowchart TD
    Bash[bash process] <--> PTY[PTY master]
    PTY <--> Mux[MuxServer]
    Mux <--> AgentClient[CodePilot terminal tool client]
    Mux <--> UIClient[code-server / xterm.js client]

Loading

Persistence Model

Session backends are selected at runtime construction:

Runtime("agent.yaml")                                      # memory
Runtime("agent.yaml", session="file", session_id="demo")   # JSON file
Runtime("agent.yaml", session="db", db_url="sqlite:///./codepilot.db")

For async web apps, pass the engine your application owns:

from sqlalchemy.ext.asyncio import create_async_engine
from codepilot import AsyncRuntime

engine = create_async_engine(
    DATABASE_URL,
    pool_size=5,
    max_overflow=10,
    pool_pre_ping=True,
)

runtime = AsyncRuntime("agent.yaml", session="db", db=engine)

Important deployment rule:

A SQLAlchemy engine is a local process object, not the database. Different processes or MicroVMs should create their own engine or receive their own engine from the application process, even if all engines point to the same Postgres database.

Observability and Product Integration

Hooks are the UI and orchestration contract:

from codepilot import EventType

runtime.hooks.register(
    EventType.STREAM,
    lambda text, **_: send_to_ui({"type": "stream", "text": text}),
)

runtime.hooks.register(
    EventType.TOOL_CALL,
    lambda tool, args, label="", **_: send_to_ui({
        "type": "tool_call",
        "tool": tool,
        "label": label,
        "args": args,
    }),
)

runtime.hooks.register(
    EventType.TOOL_RESULT,
    lambda tool, result, **_: send_to_ui({
        "type": "tool_result",
        "tool": tool,
        "result": result,
    }),
)

This allows applications to stream progress, render tool timelines, request approvals, inject mid-task messages, and persist final summaries without coupling the UI to runtime internals.

Security Model

CodePilot gives agents real software-engineering capabilities. The runtime is not a security sandbox by itself.

Recommended production posture:

• Run untrusted workspaces inside containers, MicroVMs, or OS sandboxes.
• Use unsafe_mode: false by default.
• Gate shell execution with require_permission: true.
• Use short-lived machine/session tokens in hosted workspaces.
• Keep user auth, runtime auth, and database credentials separate.
• Prefer disposable machines plus Postgres/object-storage persistence for hosted demos.

Research Grounding

CodePilot’s design is influenced by agent and tool-use research:

• ReAct: Synergizing Reasoning and Acting in Language Models motivates interleaving reasoning traces with environment actions.
• Toolformer: Language Models Can Teach Themselves to Use Tools studies when models should call tools, what arguments to pass, and how to incorporate results.
• SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering argues that software agents benefit from purpose-built interfaces for navigating repositories, editing files, and running programs.
• Voyager: An Open-Ended Embodied Agent with Large Language Models demonstrates the value of agents that accumulate skills while acting in an external environment.
• Unikraft: Fast, Specialized Unikernels and the rise of daemonless virtualization principles inspired the zero-dependency, pure Linux namespace architecture of codepilot-workspace.

CodePilot translates those ideas into a small Python library focused on practical software work: ephemeral executable scripts, content-addressed diff edits, persistent terminals, observable hooks, and pluggable session storage.

Documentation

The README is intentionally architectural. Use the documentation site for library usage:

• Installation and AgentFile configuration
• Runtime and streaming behavior
• File, terminal, search, and context tools
• Session persistence
• Hooks and permission gating
• FastAPI and hosted workspace patterns
• API reference

Docs: https://Jahanzeb-git.github.io/codepilot/

License

MIT License. See LICENSE.