Local Development

This document covers the practical setup for working on AgentOwl locally.

Prerequisites

• Node.js 20+ recommended
• npm
• A Cloudflare account and Wrangler credentials if you want real Worker resources

Install dependencies

npm install

Workspace commands

From the repository root:

npm run build
npm run lint
npm test

Package-specific development commands:

npm run dev -w @agentowl/worker
npm run dev -w @agentowl/cli -- --help

Worker setup

The Worker uses the bindings defined in packages/worker/wrangler.toml:

• D1 database bound as DB
• KV namespace bound as RUNTIME_CONFIG
• Queue producer/consumer bound as EVENTS_QUEUE

The checked-in file contains placeholder resource IDs. Before using real Cloudflare resources, replace them with your environment-specific IDs.

Environment variables

The Worker can optionally use these environment variables:

• TELNYX_PUBLIC_KEY
• TELNYX_API_KEY
• CLOUDFLARE_API_TOKEN
• CLOUDFLARE_ACCOUNT_ID
• AGENTOWL_INGRESS_BASE_URL

These are defined in packages/worker/src/env.ts.

Database schema

The initial D1 schema is defined in packages/worker/migrations/0001_initial_schema.sql.

It creates tables for:

• tenants
• bindings
• endpoints
• routes
• policies
• events
• payload references
• config snapshots

If you are bootstrapping a fresh environment, apply the Worker migrations before exercising API flows that persist state.

Running the CLI against local Worker

The CLI defaults to http://localhost:8787. You can also set the target explicitly:

AGENTOWL_API_URL=http://localhost:8787 npm run dev -w @agentowl/cli -- version
AGENTOWL_API_URL=http://localhost:8787 npm run dev -w @agentowl/cli -- tenant list

Useful first commands

Create a tenant:

AGENTOWL_API_URL=http://localhost:8787 npm run dev -w @agentowl/cli -- tenant create acme --display-name "Acme"

Create a webhook endpoint:

AGENTOWL_API_URL=http://localhost:8787 npm run dev -w @agentowl/cli -- endpoint create webhook inbound-webhook https://example.com/hook --tenant <tenant_id>

Create an email binding:

AGENTOWL_API_URL=http://localhost:8787 npm run dev -w @agentowl/cli -- email bind <tenant_id> inbox@example.com

Create an SMS binding:

AGENTOWL_API_URL=http://localhost:8787 npm run dev -w @agentowl/cli -- messaging bind <tenant_id> --capability sms

Route a binding to an endpoint:

AGENTOWL_API_URL=http://localhost:8787 npm run dev -w @agentowl/cli -- route create --tenant <tenant_id> --binding <binding_id> --endpoint <endpoint_id>

Notes on local confidence

Local code-level tests cover a good amount of API and service behavior, but not every external provider path is fully exercised in a realistic environment.

For changes touching any of the following, prefer verifying both tests and a manual local flow:

• Ingress handlers
• Routing behavior
• Replay behavior
• Provider adapters
• Runtime config publication