ComputerAgent

Run any AI agent, anywhere, with any loop, and any memory backend.

Think Docker for AI agents — a portable agent definition (any format), a swappable engine, a swappable host, a swappable memory store. One SDK call, four orthogonal axes.

npx create-computeragent my-agent
cd my-agent && npm install
ANTHROPIC_API_KEY=sk-ant-... npm start

That's it. 60 seconds to a running agent.

A reference implementation of the Harness Protocol — a framework-agnostic standard for executing AI agents over HTTP+SSE, with a complete agent workspace exposed through the same surface.

Why ComputerAgent

• Portable agents — agents are git repos (or inline manifests), not framework-specific Python objects. Move them between machines, between teams, between models without rewriting.
• Swappable everything — the four ports (engine / identity / substrate / memory) are independently pluggable. Run the same agent on your laptop today and in an E2B sandbox tomorrow with a one-line change.
• Boring tech — Hono on Bun/Node, Zod, vitest, MIT. No experimental frameworks. The protocol is plain HTTP+SSE; curl can drive it.
• Production-shaped failure semantics — explicit, documented contracts: AuditSink is fire-and-forget, SessionStore is fail-loud, sibling sessions never share blast radius. Validated by an adversarial conformance suite.
• Live-tested — every substrate × every engine × every memory backend verified end-to-end against the real Anthropic API.

ComputerAgent decomposes the agent stack into four orthogonal axes — any combination works through the same SDK call:

• WHAT — agent identity. Default loader: GitAgentProtocol. Add your own with an IdentityLoader.
• HOW — the agentic loop. Two engines today: @anthropic-ai/claude-agent-sdk and gitclaw (gitagent). Add your own with an EngineDriver.
• WHERE — the substrate. Three today: local subprocess, E2B cloud sandbox, and VZVirtualMachine via Tart. Add your own with a Substrate.
• REMEMBER — session storage. Three today: in-memory, file (JSONL), MongoDB. Add your own with a SessionStore.

275 tests across 13 packages, all green. End-to-end live demos verified against the real Anthropic API across all three substrates AND all three session stores, for both engines.

60-second getting started

Two ways. Either scaffolds a runnable project; pick one.

Fastest — npx create-computeragent:

npx create-computeragent my-agent
cd my-agent && npm install
ANTHROPIC_API_KEY=sk-ant-... npm start

Or wire it up yourself:

npm install computeragent

// my-first-agent.tsimport{runTask,LocalSubstrate}from"computeragent";constresult=awaitrunTask({source: {type: "inline",manifest: {name: "hello",version: "0.1.0"},files: {"agent.yaml": ['spec_version: "0.1.0"',"name: hello","version: 0.1.0","model: { preferred: claude-haiku-4-5-20251001 }","runtime: { max_turns: 2 }",].join("\n"),"SOUL.md": "Respond in one short sentence.",},},harness: "claude-agent-sdk",envs: {ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!},runtime: newLocalSubstrate(),message: "Say hi.",});console.log(result.ended.reason);// "complete"

ANTHROPIC_API_KEY=sk-... node --experimental-strip-types my-first-agent.ts

That's it. No harness server to boot, no session lifecycle to manage — runTask handles everything and tears the substrate down before returning.

The computeragent umbrella package gives you the SDK + LocalSubstrate in one install. For other substrates / engines / memory backends, install the scoped packages alongside (see Packages).

Swap the substrate. Same code.

import{E2BSubstrate}from"@computeragent/runtime-e2b";import{VZVMSubstrate}from"@computeragent/runtime-vzvm";import{LocalSubstrate}from"@computeragent/runtime-local";runtime: newLocalSubstrate(),// host processruntime: newE2BSubstrate({apiKey: process.env.E2B_API_KEY!}),// cloud sandboxruntime: newVZVMSubstrate({// Apple Silicon VMbaseImage: "ghcr.io/cirruslabs/ubuntu:latest",sshUser: "admin",sshPassword: "admin",}),

Swap the memory. Same agent, different backend.

// In-process memory (default — no setup):
sessionStore: {kind: "memory"}// JSONL on disk:
sessionStore: {kind: "file",options: {root: "./sessions"}}// MongoDB — survives across processes / hosts:
sessionStore: {kind: "mongo"}// ^ resolved server-side via createHarnessServer({// sessionStores: { mongo: mongoSessionStoreBuilder({ url: process.env.MONGO_URL! }) }// })

Pass sessionId: "<previous>" to a fresh runTask and the agent picks up the conversation from the store — proven for all three engines × backends. See examples/wedge16-mongo-resume-demo.ts and examples/wedge16-gitagent-mongo-demo.ts.

Swap the engine. Same SDK call.

harness: "claude-agent-sdk",// wraps @anthropic-ai/claude-agent-sdkharness: "gitagent",// wraps gitclaw (open-gitagent/gitagent)

Curl works too

The protocol is plain HTTP+SSE. Anything that speaks HTTP can drive it:

bun run examples/wedge1-server.ts &
bash examples/wedge1-curl.sh
bash examples/wedge1-fs-tour.sh # agent writes a file; curl /fs/* to inspect

CLI

computeragent health
computeragent run github.com/org/my-agent -m "your message"

Status

Wedge	What it ships	Status
1 — The Standard	Harness Protocol + harness-server framework + GAP loader + 2 engines	✅
1.5 — Hardening	Last-Event-ID replay buffer, AuditSink, AuthHandler, conformance suite, GAP compliance/tools/sub-agents/hooks	✅
1.6 — Swappable session memory	SessionStore port + Memory/File/Mongo/SQLite backends + per-engine replay	✅
2 — Client SDK	@computeragent/sdk — typed TS client + runTask one-shot helper + await using	✅
2.1 — CLI	computeragent run …	✅
3 — Substrates	runtime-local, runtime-e2b, runtime-vzvm	✅

See PLAN.md for the full architecture history.

Packages

Package	Role
computeragent	Umbrella — re-exports SDK + LocalSubstrate. The one-line install.
create-computeragent	npx create-computeragent my-agent scaffolder
@computeragent/protocol	Type defs + zod schemas + EngineDriver / IdentityLoader / SessionStore contracts
@computeragent/harness-server	Generic HTTP+SSE framework with workspace FS API + built-in stores (Memory, File)
@computeragent/engine-claude-agent-sdk	Wraps @anthropic-ai/claude-agent-sdk
@computeragent/engine-gitagent	Wraps gitclaw (open-gitagent/gitagent) — synthesizes resume via session-replay
@computeragent/identity-gitagentprotocol	Loads GitAgentProtocol repos
@computeragent/runtime-local	Subprocess pool on the host
@computeragent/runtime-e2b	Cloud sandbox via E2B
@computeragent/runtime-vzvm	Linux VM on Apple Silicon via Tart
@computeragent/session-store-mongo	MongoDB-backed SessionStore
@computeragent/session-store-sqlite	SQLite-backed SessionStore
@computeragent/sdk	The user-facing client (ComputerAgent, ChatHandle, runTask)
@computeragent/cli	computeragent binary
@computeragent/testing	Mocks + SSE helpers + the conformance suite (conformanceCases, runConformanceSuite)

Architecture in three minutes

Ten diagrams in one: four orthogonal ports (WHAT/HOW/WHERE/REMEMBER/AUDIT), the HTTP+SSE harness protocol, git-URL-as-identity, the substrate runtime matrix, permission/governance flow, telemetry pipeline, library vs server mode, SessionStore architecture, end-to-end topology, and design principles. Every box is swappable through the same SDK call.

The protocol is the artifact. Engines, identity loaders, substrates, and session stores are plug-ins.

Adding your own plug-in

Every port follows the same shape: implement a small interface, register at createHarnessServer({...}) boot. No fork required.

import{createHarnessServer}from"@computeragent/harness-server";import{mongoSessionStoreBuilder}from"@computeragent/session-store-mongo";createHarnessServer({engines: {"claude-agent-sdk": newClaudeAgentEngine(),"your-engine": newYourEngine(),// implements EngineDriver},identityLoaders: {gitagentprotocol: newGitAgentProtocolLoader(),"your-format": newYourLoader(),// implements IdentityLoader},sessionStores: {mongo: mongoSessionStoreBuilder({url: process.env.MONGO_URL!}),redis: (cfg)=>newYourRedisStore(cfg),// implements SessionStore},authHandler: bearerToken(verifyJwt),// implements AuthHandlerauditSink: newYourS3AuditSink(),// implements AuditSink});

Then drive it with curl, the SDK, the CLI — same protocol, same wire shape.

Conformance

Third-party EngineDriver / IdentityLoader / SessionStore implementations validate against the same suite the reference implementation runs against:

import{conformanceCases,runConformanceSuite}from"@computeragent/testing";constreport=awaitrunConformanceSuite(()=>yourDriverFor(yourHarness));console.log(`${report.passed} passed, ${report.failed.length} failed`);

If your implementation passes the suite, it's a drop-in replacement.

Community

Questions, ideas, build journals — head to Discussions. Issues are for actionable bugs and feature requests.

If ComputerAgent helps you build something, ⭐ star the repo — it makes a real difference for discoverability. While you're there, the open protocol this implements lives at open-gitagent/opengap — give that a star too.

Star history

License

MIT