Skip to main content

OpenEve Developer Documentation

OpenEve is a vendor-neutral, filesystem-first framework for durable AI agents. An agent should be understandable as a folder; OpenEve validates that folder, compiles it into a manifest and runtime artifact, and runs it through the adapters declared by the agent.

The docs are organized by developer job, with the shortest path first and deeper contracts later. They are inspired by the clear progression of Vercel Eve-style agent docs and Hermes-style agent documentation, but they document OpenEve's portable gateway, adapter, and runtime model.

Start Here​

  1. Getting Started - clone the repo, build it, run the example agent, create a new agent, and inspect the compiled artifact.
  2. Building Agents - learn the agent folder shape and author instructions, tools, skills, channels, schedules, trigger handlers, connections, subagents, and instrumentation.
  3. Customizing Agents - customize context, gateway adapters, tools, skills, self-improvement, channels, sandboxes, and connection auth.
  4. Runtime And Deployment - understand the compiler output, durable runtime lifecycle, HTTP endpoints, preflight checks, and deploy targets.
  5. Troubleshooting - diagnose install, CLI, model-key, auth, preflight, ingress, and durability-worker failures.
  6. Contributing - work on the OpenEve framework itself and keep developer docs current.

Reference Docs​

  • Framework Guide - current framework contracts, manifest shape, runtime guarantees, package boundaries, and adapter boundaries.
  • Configuration Reference - every define* config shape, per-file compiler contract, and OPENEVE_* environment variable.
  • Adapters - provider helpers, channel packages, sandbox options, state/blob adapters, and required environment variables.
  • Authoring Adapters - implement new channels, sandboxes, blob stores, deploy targets, harnesses, and state stores, and package them as providers.
  • Architecture And Auditability - module ownership, security-sensitive flows, and line-count exceptions.
  • Photon iMessage Channel - Photon/Spectrum channel setup, typing lifecycle, rich tools, and file handling.

Internal planning notes, deployment evidence, and sibling-repo research live outside the public developer docs under docs/internal/.

Mental Model​

agent/ folder      what the agent is
compiler           validates the folder and emits a manifest plus .openeve artifact
runtime            executes runs durably and records events, tools, deliveries, and recovery state
gateway.ts         chooses deploy, runtime, state, blob, sandbox, scheduler, and observability adapters
provider packages  add optional channels, sandboxes, state, blob, and deploy helpers

The simple path is deliberately small: instructions.md and agent.ts are the only required files. The advanced path stays explicit: add one file in the relevant folder when you need a tool, skill, channel, schedule, trigger handler, connection, sandbox, subagent, or instrumentation hook.

Current Repo Status​

OpenEve is a TypeScript monorepo with a public package plan:

  • openeve is the public CLI/meta package.
  • @openeve/core, @openeve/compiler, @openeve/runtime, @openeve/node, and provider packages are scoped public packages.
  • The workspace root is private infrastructure only and is named @openeve/monorepo.

The packages are not yet published to npm. When working inside this repo, build first and run the CLI through:

pnpm openeve <command> <agent-root>

(pnpm openeve resolves to the workspace @openeve/cli binary, which runs from built output, so pnpm build must run first.)

Once the packages are published to npm, the package-user syntax will be:

openeve <command> <agent-root>

Generated outputs such as .openeve/, package dist/, caches, and local env files should not be committed.