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.ts
import { runTask, LocalSubstrate } from "computeragent";

const result = await runTask({
  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: new LocalSubstrate(),
  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: new LocalSubstrate(),                                          // host process
runtime: new E2BSubstrate({ apiKey: process.env.E2B_API_KEY! }),        // cloud sandbox
runtime: new VZVMSubstrate({                                            // Apple Silicon VM
  baseImage: "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-sdk
harness: "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": new ClaudeAgentEngine(),
    "your-engine":      new YourEngine(),     // implements EngineDriver
  },
  identityLoaders: {
    gitagentprotocol: new GitAgentProtocolLoader(),
    "your-format":    new YourLoader(),       // implements IdentityLoader
  },
  sessionStores: {
    mongo: mongoSessionStoreBuilder({ url: process.env.MONGO_URL! }),
    redis: (cfg) => new YourRedisStore(cfg),  // implements SessionStore
  },
  authHandler: bearerToken(verifyJwt),         // implements AuthHandler
  auditSink:   new YourS3AuditSink(),          // 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";

const report = await runConformanceSuite(() => 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