Hexagent

<p align="center"> <img src=".github/images/logo.svg" alt="HexAgent" width="300"/> </p> <p align="center"> <strong>Agent harness — give any LLM a computer. Ship any agent product.</strong> </p> <p align="center"> <a href="https://github.com/an7tang/hexagent/actions/workflows/ci.yml"><img src="https://github.com/an7tang/hexagent/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"></a> </p>

---

HexAgent is an open-source agent harness: the production runtime that gives any LLM a fully-equipped computer — terminal, filesystem, and shell — to complete tasks autonomously.

Unlike every other agent framework, HexAgent separates the agent runtime from the computer it operates on. Your agent gets a sandboxed machine; your runtime keeps its API keys, config, and source code private.

Why "harness" and not "framework"? A framework gives you building blocks and says "assemble your own agent." A harness gives the agent a fully equipped runtime — tools, context management, safety, execution environments — so you focus on what the agent does, not how it executes. (Read more)

The Computer Layer

In Claude Code, Codex, and every LangChain agent, the agent runtime and the computer it controls are the same process. The agent can read its own source code, config files, and API keys. HexAgent's Computer protocol makes this separation explicit and pluggable — swap execution environments without changing a line of agent code.

from hexagent import create_agent
from hexagent.computer import LocalNativeComputer, LocalVM, RemoteE2BComputer

# Development — run on your machine
agent = await create_agent(model="anthropic/claude-sonnet-4-20250514", computer=LocalNativeComputer())

# Security-sensitive — sandboxed VM (Lima on macOS, WSL on Windows)
agent = await create_agent(model="anthropic/claude-sonnet-4-20250514", computer=LocalVM())

# Production / multi-tenant — isolated cloud sandbox
agent = await create_agent(model="anthropic/claude-sonnet-4-20250514", computer=RemoteE2BComputer(api_key="..."))

┌───────────────────────────┐            ┌───────────────────────────┐
│     Agent Runtime         │            │     Agent's Computer      │
│     (your host)           │   run()    │     (sandboxed)           │
│                           │ ─────────> │                           │
│  - LLM API keys           │   start()  │  - Terminal + filesystem  │
│  - Agent source code      │   upload() │  - User's project files   │
│  - Harness config         │   stop()   │  - Installed tools        │
│  - Middleware & hooks     │            │                           │
│                           │            │  Cannot access runtime    │
└───────────────────────────┘            └───────────────────────────┘

Three built-in implementations cover every deployment scenario:

| Computer | Environment | Use case | |---|---|---| | LocalNativeComputer | Host shell | Development, trusted agents | | LocalVM | Lima (macOS) / WSL (Windows) | Security-sensitive work, Cowork products | | RemoteE2BComputer | E2B cloud sandbox | Production, multi-tenant, CI/CD |

Implement the Computer protocol to add your own — Docker, Kubernetes pods, or any remote execution target.

Quick Start

pip install hexagent

Minimal example

import asyncio
from hexagent import create_agent
from hexagent.computer import LocalNativeComputer

async def main():
    async with await create_agent(
        model="anthropic/claude-sonnet-4-20250514",  # or any LLM
        computer=LocalNativeComputer(),
    ) as agent:
        result = await agent.ainvoke({
            "messages": [{"role": "user", "content": "Find all TODO comments in this project"}]
        })
        print(result["messages"][-1].content)

asyncio.run(main())

Use any model

from hexagent import create_agent, ModelProfile
from hexagent.computer import LocalNativeComputer

# DeepSeek, Qwen, Llama, Mistral — anything OpenAI-compatible
model = ModelProfile(
    model="deepseek/deepseek-chat",
    base_url="https://api.deepseek.com/v1",
    api_key="your-key",
    context_window=64000,
)

agent = await create_agent(model=model, computer=LocalNativeComputer())

Add subagents, MCP servers, web tools

from hexagent import create_agent, AgentDefinition
from hexagent.computer import LocalNativeComputer

agent = await create_agent(
    model="anthropic/claude-sonnet-4-20250514",
    computer=LocalNativeComputer(),
    # Subagents for parallel specialized work
    agents={
        "researcher": AgentDefinition(
            description="Deep-dives into codebases",
            tools=["Read", "Glob", "Grep", "WebSearch"],
            model="fast",
        ),
    },
    # MCP tool servers
    mcp_servers={
        "github": {"type": "http", "url": "https://mcp.github.com/mcp"},
    },
    # Web capabilities
    search_provider=("tavily", "your-key"),
    fetch_provider=("jina", "your-key"),
)

Run in a cloud sandbox

from hexagent import create_agent
from hexagent.computer import RemoteE2BComputer

# Fully isolated cloud execution — no local risk
agent = await create_agent(
    model="openai/gpt-4o",
    computer=RemoteE2BComputer(api_key="your-e2b-key"),
)

See libs/hexagent/README.md for the full API reference.

What Can You Build?

One harness powers four product types — no other agent SDK does this:

| Product Type | Description | Example | |---|---|---| | CLI Coding Agent | Terminal-native agent that lives in your shell, reads your codebase, writes and runs code autonomously | Claude Code, Gemini CLI | | Chatbot | Conversational AI assistant — you ask, it answers, with web search, file uploads, and tool use in the loop | ChatGPT, Claude Chat | | Cowork | Desktop agent that works on your local files, folders, and apps — completing knowledge work tasks autonomously while you steer | Claude Cowork | | Autonomous Agent | Headless agent that runs tasks end-to-end without supervision | OpenClaw, Devin |

The hexagent_demo app ships with ready-to-use Chat and Cowork modes as concrete examples.

Features

Core Architecture

• Computer Protocol — Pluggable execution environments (local, VM, cloud) with full runtime isolation. The agent's computer is a separate process from the agent itself.
• Model-agnostic — Anthropic, OpenAI, DeepSeek, open-weight models via OpenRouter, or any OpenAI-compatible endpoint. Swap models without changing your agent.
• Context engineering — Automatic 3-phase compaction keeps agents effective across long sessions. Context is an architectural concern, not an afterthought.

Production Capabilities

• 12+ built-in tools — Bash, Read, Write, Edit, Glob, Grep, WebSearch, WebFetch, plus extensible skills and MCP servers
• Subagent orchestration — Spawn specialized child agents (foreground + background) with isolated contexts and filtered tool sets
• MCP native — First-class Model Context Protocol support via stdio, SSE, or HTTP transports
• Permission gating — Multi-layer safety rules validate every tool call before execution with human-in-the-loop approval flows
• Skills system — Filesystem-based extensions with SKILL.md metadata and on-demand loading
• System reminders — Rule-based context injection before model calls (<system-reminder> mechanism)
• Web providers — Pluggable search (Tavily/Brave) and fetch (Jina/Firecrawl) backends
• Composable, not magical — Small modules with explicit I/O. No hidden state. Every piece is testable and replaceable.

How HexAgent Compares

| | HexAgent | Claude Agent SDK | LangChain Deep Agents | |---|---|---|---| | Open source | MIT | MIT | MIT | | Model-agnostic | Any LLM | Claude only | Any LLM | | Runtime / Computer separation | Yes (Computer protocol) | No (same process) | No (virtual filesystem) | | Computer environments | Local + VM + Cloud (E2B) | Local only | Pluggable sandboxes | | Multi-product (Chat, Code, Cowork, Autonomous) | Yes, from one harness | No (CLI-focused) | Assemble yourself | | Context compaction | 3-phase automatic | Automatic | 3-tier (offload + truncate + summarize) | | Subagent orchestration | Built-in (foreground + background) | Built-in (no nesting) | Built-in | | MCP support | Native | Native | Via adapters | | Skill / plugin system | Filesystem-based (SKILL.md) | Filesystem-based | Filesystem-based (SKILL.md) | | Observability | LangSmith / Braintrust | None built-in | LangSmith | | Language | Python | Python + TypeScript | Python + TypeScript |

How the Harness Works

┌─────────────────────────────────────────────────────────────────┐
│                        Agent Harness                            │
│                                                                 │
│  ┌───────────┐  ┌──────────────┐  ┌───────────┐                 │
│  │  Prompt   │  │  Middleware  │  │   Tools   │                 │
│  │  System   │  │  Pipeline    │  │           │                 │
│  │           │  │              │  │ Bash,Read │                 │
│  │ Fragments │  │ Compaction   │  │ Write,Edit│                 │
│  │ Sections  │  │ Permissions  │  │ Glob,Grep │                 │
│  │ Variables │  │ Reminders    │  │ Web,MCP   │                 │
│