Self-hosting

Most people should use the hosted service at admin.agentowl.dev; start with the Quickstart. This section is for running your own AgentOwl deployment or developing AgentOwl itself.

A deployment has three parts:

• The Worker (packages/worker) — the API, provider ingress, and queue consumer, on Cloudflare Workers with D1, KV, and Queues.
• The SMTP server (sendmailrs/) — receives mail on port 25 for <name>@<workspace>.<your-domain> addresses. See SMTP Server.
• Telnyx — phone numbers for SMS and voice. See Phone numbers.

Prerequisites

• Node.js 20+ and npm
• Access to the AgentOwl repository
• Wrangler (installed with the workspace) and a Cloudflare account to deploy
• Telnyx and Cloudflare credentials to exercise real provider traffic

1. Install the CLI

git clone https://github.com/dev-sawan-ruparel/agentowl-dev.git
cd agentowl-dev/agentowl-dev
npm install
npm run build

# Link the CLI globally
cd packages/cli
npm link

After linking, the agentowl command is available globally. To run it without linking:

cd packages/cli
npm run dev -- <command> [args]

Verify the install:

agentowl --version

2. Start the Worker locally

cd packages/worker
cp .dev.vars.example .dev.vars

Edit .dev.vars:

TELNYX_PUBLIC_KEY=<your-telnyx-public-key>
TELNYX_API_KEY=<your-telnyx-api-key>
CLOUDFLARE_API_TOKEN=<your-cloudflare-api-token>
CLOUDFLARE_ACCOUNT_ID=<your-cloudflare-account-id>
AGENTOWL_INGRESS_BASE_URL=http://localhost:8787
# Optional: AES-256 key to encrypt stored payloads (openssl rand -base64 32)
PAYLOAD_ENCRYPTION_KEY=

Apply the D1 migrations to the local database, then start the Worker:

npx wrangler d1 migrations apply agentowl --local
npm run dev
# Worker running at http://localhost:8787

wrangler dev does not apply migrations on its own. Re-run the migrations command after pulling changes that add files to packages/worker/migrations/.

3. Configure sign-in

The API accepts API keys (aok_…) and OAuth access tokens (oat_…), both issued to accounts that sign in with GitHub or Google. Configure at least one provider in .dev.vars:

GITHUB_CLIENT_ID=<oauth-app-client-id>
GITHUB_CLIENT_SECRET=<oauth-app-client-secret>
# and/or GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET
AUTH_SESSION_SECRET=<long-random-string>
# Accounts with these emails get the platform-admin role
PLATFORM_ADMIN_EMAILS=you@example.com

Register http://localhost:8787/auth/callback/github (or /auth/callback/google) as the OAuth app's callback URL. See Roles and Permissions for how roles and tokens work.

4. Connect the CLI

agentowl login --url http://localhost:8787

This opens the browser device-code flow and saves the token and URL to ~/.agentowl/config.json. For CI, create an API key and pass it directly:

agentowl login --token aok_... --url http://localhost:8787

You can also set AGENTOWL_API_URL and AGENTOWL_API_TOKEN, which take precedence over the saved config.

Check the connection:

agentowl version

If the server is reachable, this prints both the CLI and server versions.

Next steps

• Set up with the CLI — create a workspace, endpoint, bindings, and routes
• Local Development — workspace layout, environment variables, and tests
• SMTP Server — deploy sendmailrs for inbound email
• Phone numbers — connect Telnyx numbers for SMS and voice