{"id":51083261,"url":"https://github.com/open-gitagent/computeragent","last_synced_at":"2026-06-23T20:02:19.055Z","repository":{"id":362043198,"uuid":"1233449784","full_name":"open-gitagent/ComputerAgent","owner":"open-gitagent","description":"Run any AI agent — Claude Code, GAP, LangGraph DeepAgents — in a hermetic sandbox. Reference implementation of the Harness Protocol.","archived":false,"fork":false,"pushed_at":"2026-06-22T22:22:43.000Z","size":26745,"stargazers_count":16,"open_issues_count":2,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-23T00:15:49.103Z","etag":null,"topics":["agent-framework","agent-runtime","agents","ai-agents","anthropic","bwrap","claude-agent-sdk","claude-code","deepagents","gap","gitagent","harness","langgraph","sandbox","typescript"],"latest_commit_sha":null,"homepage":"https://computeragent.sh","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/open-gitagent.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-09T01:19:21.000Z","updated_at":"2026-06-16T13:44:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/open-gitagent/ComputerAgent","commit_stats":null,"previous_names":["open-gitagent/computeragent"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/open-gitagent/ComputerAgent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-gitagent%2FComputerAgent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-gitagent%2FComputerAgent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-gitagent%2FComputerAgent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-gitagent%2FComputerAgent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/open-gitagent","download_url":"https://codeload.github.com/open-gitagent/ComputerAgent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-gitagent%2FComputerAgent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34704748,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-framework","agent-runtime","agents","ai-agents","anthropic","bwrap","claude-agent-sdk","claude-code","deepagents","gap","gitagent","harness","langgraph","sandbox","typescript"],"created_at":"2026-06-23T20:02:16.846Z","updated_at":"2026-06-23T20:02:19.040Z","avatar_url":"https://github.com/open-gitagent.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/hero.png\" alt=\"ComputerAgent — Research Labs\" width=\"720\"\u003e\n\u003c/p\u003e\n\n# ComputerAgent\n\n[![CI](https://github.com/open-gitagent/ComputerAgent/actions/workflows/ci.yml/badge.svg)](https://github.com/open-gitagent/ComputerAgent/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n[![Tests](https://img.shields.io/badge/tests-278%20passing-brightgreen)](#status)\n[![Packages](https://img.shields.io/badge/packages-13-blue)](#packages)\n[![Discussions](https://img.shields.io/github/discussions/open-gitagent/ComputerAgent?logo=github\u0026label=Discussions)](https://github.com/open-gitagent/ComputerAgent/discussions)\n[![GitHub stars](https://img.shields.io/github/stars/open-gitagent/ComputerAgent?style=social)](https://github.com/open-gitagent/ComputerAgent/stargazers)\n\n\u003e **Run any AI agent, anywhere, with any loop, and any memory backend.**\n\u003e\n\u003e 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.\n\n```bash\nnpx create-computeragent my-agent\ncd my-agent \u0026\u0026 npm install\nANTHROPIC_API_KEY=sk-ant-... npm start\n```\n\nThat's it. 60 seconds to a running agent.\n\nA 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.\n\n## Why ComputerAgent\n\n- **Portable agents** — agents are git repos (or inline manifests), not framework-specific Python objects. Move them between machines, between teams, between models without rewriting.\n- **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.\n- **Boring tech** — Hono on Bun/Node, Zod, vitest, MIT. No experimental frameworks. The protocol is plain HTTP+SSE; `curl` can drive it.\n- **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.\n- **Live-tested** — every substrate × every engine × every memory backend verified end-to-end against the real Anthropic API.\n\nComputerAgent decomposes the agent stack into **four orthogonal axes** — any combination works through the same SDK call:\n\n- **WHAT** — agent identity. Default loader: [GitAgentProtocol](https://github.com/open-gitagent/gitagent-protocol). Add your own with an `IdentityLoader`.\n- **HOW** — the agentic loop. Two engines today: `@anthropic-ai/claude-agent-sdk` and `gitclaw` (gitagent). Add your own with an `EngineDriver`.\n- **WHERE** — the substrate. Three today: local subprocess, [E2B](https://e2b.dev) cloud sandbox, and [VZVirtualMachine via Tart](https://tart.run/). Add your own with a `Substrate`.\n- **REMEMBER** — session storage. Three today: in-memory, file (JSONL), MongoDB. Add your own with a `SessionStore`.\n\n275 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.\n\n## 60-second getting started\n\nTwo ways. Either scaffolds a runnable project; pick one.\n\n**Fastest — `npx create-computeragent`:**\n\n```bash\nnpx create-computeragent my-agent\ncd my-agent \u0026\u0026 npm install\nANTHROPIC_API_KEY=sk-ant-... npm start\n```\n\n**Or wire it up yourself:**\n\n```bash\nnpm install computeragent\n```\n\n```ts\n// my-first-agent.ts\nimport { runTask, LocalSubstrate } from \"computeragent\";\n\nconst result = await runTask({\n  source: {\n    type: \"inline\",\n    manifest: { name: \"hello\", version: \"0.1.0\" },\n    files: {\n      \"agent.yaml\": [\n        'spec_version: \"0.1.0\"',\n        \"name: hello\",\n        \"version: 0.1.0\",\n        \"model: { preferred: claude-haiku-4-5-20251001 }\",\n        \"runtime: { max_turns: 2 }\",\n      ].join(\"\\n\"),\n      \"SOUL.md\": \"Respond in one short sentence.\",\n    },\n  },\n  harness: \"claude-agent-sdk\",\n  envs: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },\n  runtime: new LocalSubstrate(),\n  message: \"Say hi.\",\n});\n\nconsole.log(result.ended.reason);   // \"complete\"\n```\n\n```bash\nANTHROPIC_API_KEY=sk-... node --experimental-strip-types my-first-agent.ts\n```\n\nThat's it. No harness server to boot, no session lifecycle to manage — `runTask` handles everything and tears the substrate down before returning.\n\nThe `computeragent` umbrella package gives you the SDK + `LocalSubstrate` in one install. For other substrates / engines / memory backends, install the scoped packages alongside (see [Packages](#packages)).\n\n## Swap the substrate. Same code.\n\n```ts\nimport { E2BSubstrate }   from \"@computeragent/runtime-e2b\";\nimport { VZVMSubstrate }  from \"@computeragent/runtime-vzvm\";\nimport { LocalSubstrate } from \"@computeragent/runtime-local\";\n\nruntime: new LocalSubstrate(),                                          // host process\nruntime: new E2BSubstrate({ apiKey: process.env.E2B_API_KEY! }),        // cloud sandbox\nruntime: new VZVMSubstrate({                                            // Apple Silicon VM\n  baseImage: \"ghcr.io/cirruslabs/ubuntu:latest\",\n  sshUser: \"admin\", sshPassword: \"admin\",\n}),\n```\n\n## Swap the memory. Same agent, different backend.\n\n```ts\n// In-process memory (default — no setup):\nsessionStore: { kind: \"memory\" }\n\n// JSONL on disk:\nsessionStore: { kind: \"file\", options: { root: \"./sessions\" } }\n\n// MongoDB — survives across processes / hosts:\nsessionStore: { kind: \"mongo\" }\n//   ^ resolved server-side via createHarnessServer({\n//       sessionStores: { mongo: mongoSessionStoreBuilder({ url: process.env.MONGO_URL! }) }\n//     })\n```\n\nPass `sessionId: \"\u003cprevious\u003e\"` 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`](./examples/wedge16-mongo-resume-demo.ts) and [`examples/wedge16-gitagent-mongo-demo.ts`](./examples/wedge16-gitagent-mongo-demo.ts).\n\n## Swap the engine. Same SDK call.\n\n```ts\nharness: \"claude-agent-sdk\",  // wraps @anthropic-ai/claude-agent-sdk\nharness: \"gitagent\",          // wraps gitclaw (open-gitagent/gitagent)\n```\n\n## Curl works too\n\nThe protocol is plain HTTP+SSE. Anything that speaks HTTP can drive it:\n\n```bash\nbun run examples/wedge1-server.ts \u0026\nbash examples/wedge1-curl.sh\nbash examples/wedge1-fs-tour.sh    # agent writes a file; curl /fs/* to inspect\n```\n\n## CLI\n\n```bash\ncomputeragent health\ncomputeragent run github.com/org/my-agent -m \"your message\"\n```\n\n## Status\n\n| Wedge | What it ships | Status |\n|---|---|---|\n| 1 — The Standard | Harness Protocol + `harness-server` framework + GAP loader + 2 engines | ✅ |\n| 1.5 — Hardening | Last-Event-ID replay buffer, `AuditSink`, `AuthHandler`, conformance suite, GAP compliance/tools/sub-agents/hooks | ✅ |\n| 1.6 — Swappable session memory | `SessionStore` port + Memory/File/Mongo/SQLite backends + per-engine replay | ✅ |\n| 2 — Client SDK | `@computeragent/sdk` — typed TS client + `runTask` one-shot helper + `await using` | ✅ |\n| 2.1 — CLI | `computeragent run …` | ✅ |\n| 3 — Substrates | `runtime-local`, `runtime-e2b`, `runtime-vzvm` | ✅ |\n\nSee [`PLAN.md`](./PLAN.md) for the full architecture history.\n\n## Packages\n\n| Package | Role |\n|---|---|\n| **`computeragent`** | Umbrella — re-exports SDK + `LocalSubstrate`. The one-line install. |\n| `create-computeragent` | `npx create-computeragent my-agent` scaffolder |\n| `@computeragent/protocol` | Type defs + zod schemas + `EngineDriver` / `IdentityLoader` / `SessionStore` contracts |\n| `@computeragent/harness-server` | Generic HTTP+SSE framework with workspace FS API + built-in stores (Memory, File) |\n| `@computeragent/engine-claude-agent-sdk` | Wraps `@anthropic-ai/claude-agent-sdk` |\n| `@computeragent/engine-gitagent` | Wraps `gitclaw` ([open-gitagent/gitagent](https://github.com/open-gitagent/gitagent)) — synthesizes resume via `session-replay` |\n| `@computeragent/identity-gitagentprotocol` | Loads GitAgentProtocol repos |\n| `@computeragent/runtime-local` | Subprocess pool on the host |\n| `@computeragent/runtime-e2b` | Cloud sandbox via [E2B](https://e2b.dev) |\n| `@computeragent/runtime-vzvm` | Linux VM on Apple Silicon via [Tart](https://tart.run/) |\n| `@computeragent/session-store-mongo` | MongoDB-backed `SessionStore` |\n| `@computeragent/session-store-sqlite` | SQLite-backed `SessionStore` |\n| `@computeragent/sdk` | The user-facing client (`ComputerAgent`, `ChatHandle`, `runTask`) |\n| `@computeragent/cli` | `computeragent` binary |\n| `@computeragent/testing` | Mocks + SSE helpers + the conformance suite (`conformanceCases`, `runConformanceSuite`) |\n\n## Architecture in three minutes\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/architecture-diagram.png\" alt=\"ComputerAgent — Architecture Overview\" width=\"900\"\u003e\n\u003c/p\u003e\n\nTen 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.\n\nThe protocol is the artifact. Engines, identity loaders, substrates, and session stores are plug-ins.\n\n## Adding your own plug-in\n\nEvery port follows the same shape: implement a small interface, register at `createHarnessServer({...})` boot. No fork required.\n\n```ts\nimport { createHarnessServer } from \"@computeragent/harness-server\";\nimport { mongoSessionStoreBuilder } from \"@computeragent/session-store-mongo\";\n\ncreateHarnessServer({\n  engines: {\n    \"claude-agent-sdk\": new ClaudeAgentEngine(),\n    \"your-engine\":      new YourEngine(),     // implements EngineDriver\n  },\n  identityLoaders: {\n    gitagentprotocol: new GitAgentProtocolLoader(),\n    \"your-format\":    new YourLoader(),       // implements IdentityLoader\n  },\n  sessionStores: {\n    mongo: mongoSessionStoreBuilder({ url: process.env.MONGO_URL! }),\n    redis: (cfg) =\u003e new YourRedisStore(cfg),  // implements SessionStore\n  },\n  authHandler: bearerToken(verifyJwt),         // implements AuthHandler\n  auditSink:   new YourS3AuditSink(),          // implements AuditSink\n});\n```\n\nThen drive it with `curl`, the SDK, the CLI — same protocol, same wire shape.\n\n## Conformance\n\nThird-party `EngineDriver` / `IdentityLoader` / `SessionStore` implementations validate against the same suite the reference implementation runs against:\n\n```ts\nimport { conformanceCases, runConformanceSuite } from \"@computeragent/testing\";\n\nconst report = await runConformanceSuite(() =\u003e yourDriverFor(yourHarness));\nconsole.log(`${report.passed} passed, ${report.failed.length} failed`);\n```\n\nIf your implementation passes the suite, it's a drop-in replacement.\n\n## Community\n\nQuestions, ideas, build journals — head to **[Discussions](https://github.com/open-gitagent/ComputerAgent/discussions)**. Issues are for actionable bugs and feature requests.\n\nIf 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](https://github.com/open-gitagent/opengap)** — give that a star too.\n\n### Star history\n\n[![Star History Chart](https://api.star-history.com/svg?repos=open-gitagent/ComputerAgent\u0026type=Date)](https://star-history.com/#open-gitagent/ComputerAgent\u0026Date)\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-gitagent%2Fcomputeragent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-gitagent%2Fcomputeragent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-gitagent%2Fcomputeragent/lists"}