Skip to main content

Getting Started

This guide gets a local OpenEve checkout from clone to a working agent run.

Requirements​

  • Node.js >=22.19.0
  • pnpm 10.x
  • Git

Optional, depending on what you run:

  • A model provider key such as OPENAI_API_KEY or OPENROUTER_API_KEY
  • Docker for the Docker sandbox or Docker deploy target
  • Railway CLI and RAILWAY_TOKEN for Railway deploys
  • Fly CLI and FLY_API_TOKEN for preview Fly deploys
  • DATABASE_URL for production Postgres state
  • OPENEVE_CONNECTION_STORE_SECRET or OPENEVE_SECRET for production file-backed connection credential stores
  • S3 or R2 credentials for production blob storage

Install And Build​

OpenEve is not yet published to npm. Install it from source by cloning the repository and building the workspace:

git clone <repo-url> openeve
cd openeve
pnpm install
pnpm build

Once the packages are published to npm, package users will be able to install the public CLI/meta package with npm install openeve instead. Until then, every command in this guide runs from a built checkout via pnpm openeve.

Run the test suite:

pnpm test

Typecheck packages without running tests:

pnpm check

Run The Minimal Agent​

The example at examples/minimal-agent/agent includes instructions, an agent definition, a local HTTP channel, tools, a skill, a schedule, a connection declaration, a sandbox declaration, a subagent, and instrumentation.

Validate it:

pnpm openeve validate examples/minimal-agent/agent

Build it:

pnpm openeve build examples/minimal-agent/agent

To keep generated example artifacts out of the example directory during experiments, add --out /private/tmp/openeve-minimal to build, run, serve, or deploy --dry-run.

Run a direct tool call locally:

pnpm openeve run examples/minimal-agent/agent \
  --message "hello from OpenEve" \
  --tool echo

When --tool is provided, the runtime simulates the model step and executes the named tool with inferred or explicit input. To run a full model turn, omit --tool and provide the API key required by the model prefix in agent.ts.

Inspect the compiled manifest:

pnpm openeve manifest examples/minimal-agent/agent

Serve the runtime locally:

pnpm openeve serve examples/minimal-agent/agent --port 3000

Then call the local runtime:

curl http://127.0.0.1:3000/health
curl http://127.0.0.1:3000/manifest
curl -X POST http://127.0.0.1:3000/runs \
  -H "content-type: application/json" \
  -d '{"message":"hello","toolName":"echo"}'

Local serve runs in dev mode, so the inspection and API-run endpoints are open on your machine. Production Node hosts require an admin auth policy or OPENEVE_ADMIN_TOKEN for /manifest, /routes, /runs, and run detail endpoints. Production POST /runs is disabled unless OPENEVE_ENABLE_API_RUNS=true is set and the request is authenticated with Authorization: Bearer <OPENEVE_ADMIN_TOKEN>.

Useful inspection endpoints:

  • GET /health and GET /healthz
  • GET /manifest (admin-authenticated in production)
  • GET /routes (admin-authenticated in production)
  • POST /runs (dev-mode only by default; opt-in and admin-authenticated in production)
  • GET /runs (admin-authenticated in production)
  • GET /runs/:id (admin-authenticated in production)
  • GET /runs/:id/events (admin-authenticated in production)
  • GET /runs/:id/timeline (admin-authenticated in production)

Create A New Agent​

Scaffold a new local agent folder:

mkdir -p scratch
pnpm openeve init scratch/agent

The scaffold includes:

scratch/agent/
  instructions.md
  agent.ts
  gateway.ts
  .env.example
  tools/
    echo.ts

Validate, build, and run it:

pnpm openeve validate scratch/agent
pnpm openeve build scratch/agent
pnpm openeve run scratch/agent --message "hello"

For a model-backed run, make sure the model provider key is available. For example, a model like openai/gpt-5.4-mini requires OPENAI_API_KEY.

Grow the agent with openeve add, which installs a provider package and wires its declaration in (a gateway.ts slot, a channels/<kind>.ts file, or subagent harness guidance), then prints the env vars to set:

pnpm openeve add slack scratch/agent      # installs @openeve/slack, scaffolds channels/slack.ts
pnpm openeve add postgres scratch/agent   # installs @openeve/postgres, sets state: adapter("postgres")
pnpm openeve add docker scratch/agent --role sandbox

The package manager is detected from lockfiles (pnpm/yarn/npm). Pass --no-install to only wire files and print the exact install command instead of running it.

Development Loop​

Start with the watch mode, which keeps a local HTTP server running and rebuilds + restarts it (on the same port) whenever the agent folder changes:

pnpm openeve dev scratch/agent --watch

While the agent is invalid, the previous server keeps running and the CLI prints the validation issues until the folder is valid again.

For one-off steps:

  1. Edit files under the agent folder.
  2. Run validate to catch shape, export, schema, route, schedule, and adapter issues. It also warns when agent.ts names a model outside the local model catalog (openeve models lists it; --no-model-check skips the check).
  3. Run build to emit .openeve/.
  4. Run run for local one-off checks.
  5. Run serve when testing HTTP channels or the inspection API.
  6. Inspect .openeve/manifest.json, .openeve/route-table.json, .openeve/schedules.json, and .openeve/preflight.json when something looks surprising.

Common Issues​

Common failures — install and build errors, a missing openeve command, model provider key errors, .openeve artifact churn, serve auth, deploy preflight, ingress secrets, and durability workers — are collected in Troubleshooting.

Next Steps​