@agenticmail/enterprise

Deploy and manage AI agents as employees in your organization. Full platform for configuring agent skills, permissions, deployment targets, lifecycle management, and compliance — with a web dashboard and REST API.

AgenticMail Enterprise turns AI agents into managed employees. You define what an agent can do (skills, tools, permissions), where it runs (Docker, VPS, Fly.io, Railway), and how it's supervised (approval workflows, activity tracking, audit logs). The platform handles provisioning, health monitoring, auto-recovery, and multi-tenant isolation. Each agent gets its own email, workspace, and tool access — governed by policies you control from a single dashboard.

Table of Contents

• Quick Start
• What This Does (Plain English)
• Architecture
• Setup Wizard
• Database Support
• The Engine
  • Skills & Permissions
  • Agent Configuration
  • Deployment Engine
  • Approval Workflows
  • Agent Lifecycle
  • Knowledge Base
  • Multi-Tenant Isolation
  • Activity Tracking
  • Tool Catalog
  • OpenClaw Hook
  • AgenticMail Bridge
• REST API
  • Authentication
  • Admin Endpoints
  • Engine Endpoints
• Dashboard
• Deployment
  • AgenticMail Cloud
  • Fly.io
  • Docker
  • Local Development
• Server Configuration
• Middleware
• Resilience
• Programmatic Usage
• Security
• License

Quick Start

npx @agenticmail/enterprise

The interactive wizard walks you through:

1. Company name and admin credentials
2. Database selection (10 backends supported)
3. Deployment target (Cloud, Fly.io, Docker, Railway, or Local)
4. Optional custom domain

Within 2 minutes you get a live dashboard URL with your admin account ready.

What This Does (Plain English)

Think of AgenticMail Enterprise as an HR department for AI agents.

The problem: You want to deploy AI agents that do real work — answer customer emails, research topics, write reports, manage schedules. But right now, setting up each agent means manually configuring tools, permissions, credentials, deployment, and monitoring. Scale that to 10 or 50 agents across a team, and it becomes unmanageable.

What Enterprise does:

• Hiring — You pick from 38 pre-built skill sets (email management, web research, coding, customer support, etc.) and assign them to a new agent. The platform generates all the config files, workspace setup, and tool permissions automatically.

• Onboarding — The agent gets deployed to your chosen infrastructure (a Docker container, a VPS, Fly.io, Railway, or our managed cloud). It gets its own email address, API keys, and workspace. No manual setup.

• Permissions — You control exactly what each agent can and can't do. "This agent can send emails but not access the filesystem." "This agent can browse the web but needs approval before making purchases." Five preset permission profiles (Research Assistant, Customer Support, Developer, Full Access, Sandbox) or fully custom.

• Supervision — Sensitive actions trigger approval workflows. An agent wants to send an email to a client? It gets queued for human review first. You set the policies.

• Health & Recovery — The platform monitors every agent. If one crashes, it auto-restarts. If it's stuck, it gets flagged. You see everything in the dashboard — which agents are running, what they're doing, how much they cost.

• Knowledge — Agents can share knowledge bases. Upload documents, and the platform chunks them for retrieval. Agents search the knowledge base as part of their workflow.

• Teams — Multi-tenant isolation means different teams or clients get their own agents, data, and billing. Plan tiers (Free, Team, Enterprise, Self-Hosted) enforce limits.

• Audit — Every action is logged. Who did what, when, to which resource. Compliance teams can pull reports.

In short: You focus on what your agents should do. Enterprise handles how they run, where they run, and keeping them in line.

Architecture

┌──────────────────────────────────────────────────────┐
│                    Dashboard (Web UI)                  │
│              Single HTML · React 18 · CDN             │
└─────────────────────────┬────────────────────────────┘
                          │ HTTP
┌─────────────────────────▼────────────────────────────┐
│                   Hono API Server                     │
│                                                       │
│  ┌─────────┐  ┌──────────┐  ┌──────────────────────┐ │
│  │  Auth    │  │  Admin   │  │       Engine          │ │
│  │  Routes  │  │  Routes  │  │                       │ │
│  │         │  │          │  │  Skills · Permissions  │ │
│  │  JWT    │  │  Users   │  │  Config · Deployer    │ │
│  │  Login  │  │  Agents  │  │  Approvals · Lifecycle│ │
│  │  Keys   │  │  Audit   │  │  Knowledge · Tenants  │ │
│  │         │  │  Keys    │  │  Activity · Hook      │ │
│  └─────────┘  └──────────┘  └──────────────────────┘ │
│                                                       │
│  ┌─────────────────────────────────────────────────┐  │
│  │               Middleware Stack                    │  │
│  │  Rate Limit · CORS · Security Headers · Audit   │  │
│  │  Request ID · Error Handler · RBAC              │  │
│  └─────────────────────────────────────────────────┘  │
│                                                       │
│  ┌─────────────────────────────────────────────────┐  │
│  │               Resilience Layer                   │  │
│  │  Circuit Breaker · Health Monitor · Retry       │  │
│  │  Rate Limiter · Keyed Rate Limiter              │  │
│  └─────────────────────────────────────────────────┘  │
└─────────────────────────┬────────────────────────────┘
                          │
┌─────────────────────────▼────────────────────────────┐
│              Database Adapter (Abstract)               │
│                                                       │
│  SQLite · Postgres · MySQL · MongoDB · DynamoDB      │
│  Turso · Supabase · Neon · PlanetScale · CockroachDB │
└──────────────────────────────────────────────────────┘

Setup Wizard

The CLI wizard (npx @agenticmail/enterprise) runs in 4 steps:

Step 1: Company Info

• Company name (used to generate your subdomain)
• Admin email and password

Step 2: Database

Choose from 10 supported backends. Each asks for its specific connection details:

• SQLite — file path (default: ./agenticmail-enterprise.db)
• PostgreSQL / Supabase / Neon / CockroachDB — connection string
• MySQL / PlanetScale — connection string
• MongoDB — connection URI
• DynamoDB — AWS region + credentials
• Turso / LibSQL — database URL + auth token

Step 3: Deployment Target

• AgenticMail Cloud — managed hosting, instant URL (company.agenticmail.cloud)
• Fly.io — generates fly.toml, you deploy to your Fly account
• Railway — generates Railway config
• Docker — generates docker-compose.yml for self-hosting
• Local — starts the server immediately on localhost (dev/testing)

Step 4: Custom Domain (optional)

Add a custom domain (e.g., agents.acme.com) with CNAME setup instructions.

Database Support

Enterprise uses an abstract DatabaseAdapter interface. All 10 backends implement the same methods — you pick the one that fits your infrastructure.

Adapter Pattern

Every adapter extends DatabaseAdapter and implements:

// Core operations
migrate(): Promise<void>
disconnect(): Promise<void>
getStats(): Promise<Stats>

// Users
createUser(input: UserInput): Promise<User>
getUserByEmail(email: string): Promise<User | null>
validatePassword(email: string, password: string): Promise<User | null>

// Agents
createAgent(input: AgentInput): Promise<Agent>
listAgents(filters?): Promise<Agent[]>
getAgent(id: string): Promise<Agent | null>
updateAgent(id: string, updates): Promise<Agent>
deleteAgent(id: string): Promise<void>

// API Keys
createApiKey(input: ApiKeyInput): Promise<ApiKey>
validateApiKey(key: string): Promise<ApiKey | null>
revokeApiKey(id: string): Promise<void>

// Audit Log
logEvent(event: AuditEvent): Promise<void>
getAuditLog(filters: AuditFilters): Promise<AuditEvent[]>

// Settings
getSettings(): Promise<CompanySettings>
updateSettings(updates): Promise<CompanySettings>

MongoDB Notes

• Uses _id field directly (stores randomUUID() as _id)
• Indexes created on email, apiKey, createdAt

DynamoDB Notes

• Single-table design with PK prefix pattern (USER#, AGENT#, KEY#, AUDIT#)
• GSI1 for secondary access patterns
• All entities in one table for cost efficiency

Creating a Custom Adapter

import { DatabaseAdapter } from '@agenticmail/enterprise';

class MyAdapter extends DatabaseAdapter {
  async migrate() { /* create tables/collections */ }
  async createUser(input) { /* ... */ }
  // ... implement all abstract methods
}

The Engine

The Engine is the brain of Enterprise — 11 subsystems that handle everything from "what can this agent do?" to "deploy it to production and watch it run."

1. Skills & Permissions

38 built-in skills organized into categories:

Each skill defines:

• Tools — which tool IDs are included (mapped to real OpenClaw + AgenticMail tool IDs)
• Config fields — what settings the skill needs (API keys, hostnames, etc.)
• Risk level — low, medium, high, critical
• Side effects — what the skill can affect (network, filesystem, email, etc.)

5 preset permission profiles:

How permissions work:

const engine = new PermissionEngine();

// Check if an agent can use a tool
const result = engine.checkPermission(agentProfile, 'agenticmail_send');
// → { allowed: true, reason: 'Granted by Email Management skill' }

// Or with approval required
const result2 = engine.checkPermission(agentProfile, 'exec');
// → { allowed: false, requiresApproval: true, reason: 'Code Execution requires admin approval' }

2. Agent Configuration

Generates all the files an agent needs to run:

• SOUL.md — personality, tone, boundaries
• AGENTS.md — workspace conventions
• USER.md — who the agent serves
• TOOLS.md — environment-specific tool notes
• Gateway config — OpenClaw openclaw.json with plugins, channels, tool policies
• Deploy scripts — Dockerfile, docker-compose, startup scripts

const generator = new AgentConfigGenerator();
const config = generator.generate({
  name: 'support-bot',
  role: 'Customer Support Agent',
  skills: ['email-management', 'crm', 'knowledge-base'],
  channels: [{ type: 'email' }, { type: 'slack', webhook: '...' }],
  deployment: { target: 'docker' },
});
// → { workspace: { 'SOUL.md': '...', ... }, gateway: { ... }, deploy: { ... } }

3. Deployment Engine

Provisions and manages agent infrastructure:

• Docker — Generates Dockerfile + compose, builds image, starts container
• VPS — SSH into a server, install dependencies, configure systemd service
• Fly.io — Creates Fly app, sets secrets, deploys
• Railway — Generates Railway config, links project

Each deployment goes through phases:

1. Validate — check config, verify credentials
2. Provision — create infrastructure resources
3. Configure — write config files, set environment variables
4. Deploy — push code/image, start the agent
5. Verify — health check, confirm agent is responding

const deployer = new DeploymentEngine();
const result = await deployer.deploy({
  agentId: 'agent-123',
  target: 'docker',
  config: { /* ... */ },
});
// → { status: 'deployed', url: 'http://...', phases: [...] }

4. Approval Workflows

Human-in-the-loop for sensitive operations:

• Define policies — which actions need approval and from whom
• Agents request approval when they hit a policy boundary
• Admins approve or reject from the dashboard or via API
• Supports auto-approve rules (e.g., "auto-approve emails to internal domains")
• Escalation — unreviewed requests escalate after a configurable timeout

const approvals = new ApprovalEngine(db);

// Create a policy
await approvals.createPolicy({
  action: 'send_external_email',
  requiredRole: 'admin',
  autoApproveRules: [{ condition: 'recipient_domain', value: 'acme.com' }],
});

// Agent requests approval
const request = await approvals.request({
  agentId: 'agent-123',
  action: 'send_external_email',
  details: { to: 'client@external.com', subject: '...' },
});
// → { id: 'req-456', status: 'pending' }

// Admin approves
await approvals.decide(request.id, { approved: true, decidedBy: 'admin-1' });

5. Agent Lifecycle

State machine for agent lifecycle management:

  created → provisioning → running → paused → running
                                   → stopped → archived
                                   → error → running (auto-recovery)

• Health checks — periodic pings, response time tracking, error rate monitoring
• Auto-recovery — configurable restart attempts on failure
• Usage tracking — token consumption, API calls, cost estimation
• Events — every state transition logged with timestamp and reason

const lifecycle = new AgentLifecycleManager(db);

// Get agent status
const agent = await lifecycle.getAgent('agent-123');
// → { state: 'running', health: { status: 'healthy', lastCheck: '...', uptime: 86400 }, usage: { tokens: 1500000, cost: 12.50 } }

// Pause an agent
await lifecycle.transition('agent-123', 'pause', { reason: 'Maintenance window' });

// Resume
await lifecycle.transition('agent-123', 'resume');

6. Knowledge Base

Document ingestion and retrieval for agent knowledge:

• Upload documents — PDF, Markdown, plain text, HTML
• Chunking — automatic splitting into retrievable segments
• Search — semantic search across knowledge bases
• Per-agent or shared — knowledge bases can be private or shared across agents

const kb = new KnowledgeBaseEngine(db);

// Create a knowledge base
const base = await kb.create({ name: 'Company Policies', agentIds: ['agent-1', 'agent-2'] });

// Add a document
await kb.addDocument(base.id, { title: 'PTO Policy', content: '...', format: 'markdown' });

// Search
const results = await kb.search(base.id, 'how many vacation days');
// → [{ chunk: '...', score: 0.92, document: 'PTO Policy' }]

7. Multi-Tenant Isolation

Organizations, plans, and resource limits:

Plan Tiers:

const tenants = new TenantManager(db);

// Create an organization
const org = await tenants.createOrg({ name: 'Acme Inc', plan: 'team', adminEmail: 'admin@acme.com' });

// Check limits
const canCreate = await tenants.checkLimit(org.id, 'agents');
// → { allowed: true, current: 5, limit: 25 }

// Get usage
const usage = await tenants.getUsage(org.id);
// → { agents: 5, users: 3, knowledgeBases: 2, storageBytes: 10485760 }

8. Activity Tracking

Real-time monitoring of everything agents do:

• Tool calls — which tools, when, duration, success/failure
• Conversations — message count, token usage, cost
• Timeline — chronological view of all agent activity
• Aggregations — daily/weekly/monthly summaries

const activity = new ActivityTracker(db);

// Record a tool call
await activity.recordToolCall({
  agentId: 'agent-123',
  tool: 'agenticmail_send',
  duration: 450,
  success: true,
  metadata: { to: 'user@example.com' },
});

// Get agent timeline
const timeline = await activity.getTimeline('agent-123', { limit: 50 });
// → [{ type: 'tool_call', tool: '...', timestamp: '...', ... }, ...]

// Get stats
const stats = await activity.getStats('agent-123', { period: 'day' });
// → { toolCalls: 142, conversations: 8, tokensUsed: 450000, estimatedCost: 3.75 }

9. Tool Catalog

Maps real OpenClaw and AgenticMail tool IDs to skills:

• 167 total tools cataloged (63 OpenClaw core + 62 AgenticMail MCP + 42 shell commands)
• Each tool mapped to one or more skills
• Used by the Permission Engine to resolve skill → tool access

import { ALL_TOOLS, getToolsBySkill, generateOpenClawToolPolicy } from '@agenticmail/enterprise';

// Get all tools for a skill
const emailTools = getToolsBySkill('email-management');
// → ['agenticmail_send', 'agenticmail_inbox', 'agenticmail_reply', ...]

// Generate OpenClaw tool policy
const policy = generateOpenClawToolPolicy(['email-management', 'web-search']);
// → { allow: ['agenticmail_send', ...], deny: [...] }

10. OpenClaw Hook

Middleware that integrates with OpenClaw's plugin system:

• Permission enforcement — checks every tool call against the agent's permission profile
• Activity logging — records tool calls to the activity tracker
• Approval gating — blocks tool calls that require approval
• Permission caching — avoids repeated DB lookups on high-frequency calls

import { createEnterpriseHook } from '@agenticmail/enterprise';

const hook = createEnterpriseHook({
  apiUrl: 'http://localhost:3000',
  apiKey: 'ek_...',
  agentId: 'agent-123',
});

// In OpenClaw plugin:
// hook.beforeToolCall(toolName, args) → { allowed, requiresApproval, reason }
// hook.afterToolCall(toolName, result, duration) → void (logs activity)

11. AgenticMail Bridge

Connects the Engine to an existing AgenticMail instance:

• Account sync — creates/manages agent email accounts
• Tool interception — wraps AgenticMail tool calls with permission checks
• Event forwarding — pipes AgenticMail events (new email, task completion) to the activity tracker

import { createAgenticMailBridge } from '@agenticmail/enterprise';

const bridge = createAgenticMailBridge({
  agenticmailUrl: 'http://localhost:3100',
  masterKey: 'mk_...',
});

// Sync an agent's email account
await bridge.ensureAgent({ name: 'support-bot', role: 'customer-support' });

REST API

Authentication

Two methods:

JWT Token (for dashboard users):

POST /auth/login
{ "email": "admin@acme.com", "password": "..." }
→ { "token": "eyJ...", "user": { ... } }

# Then:
Authorization: Bearer eyJ...

API Key (for programmatic access):

X-API-Key: ek_abc123...

API keys have scoped permissions and are created through the admin API.

Admin Endpoints

Engine Endpoints

Dashboard

The admin dashboard is a single HTML file using React 18 from CDN — no build step required. It includes:

• Login page with JWT authentication
• Overview with agent counts, activity stats, system health
• Agent management — create, configure, deploy, monitor
• Audit log — searchable, filterable event history
• API key management — create scoped keys, revoke
• Settings — company info, custom domain, plan management
• Dark and light mode themes

The dashboard is served automatically at /dashboard when the server starts. It communicates with the API using the same JWT/API key auth as any other client.

Building Your Own Frontend

The dashboard is a reference implementation. You can build your own UI by hitting the REST API directly. Every API response follows a consistent format:

{
  "data": { ... },
  "meta": { "total": 42, "page": 1, "limit": 20 }
}

Errors:

{
  "error": "Description of what went wrong",
  "code": "VALIDATION_ERROR",
  "details": { ... }
}

Deployment

AgenticMail Cloud

Managed hosting on Fly.io infrastructure. Instant URL at company.agenticmail.cloud.

npx @agenticmail/enterprise
# → Select "AgenticMail Cloud"
# → Dashboard live at https://acme.agenticmail.cloud

Optional custom domain via CNAME:

agents.acme.com → acme.agenticmail.cloud

Fly.io

Deploy to your own Fly.io account:

npx @agenticmail/enterprise
# → Select "Fly.io"
# → Generates fly.toml

fly launch --copy-config
fly secrets set DATABASE_URL="..." JWT_SECRET="..."
fly deploy

Docker

Self-hosted with Docker Compose:

npx @agenticmail/enterprise
# → Select "Docker"
# → Generates docker-compose.yml

docker compose up -d
# → Dashboard at http://localhost:3000

Local Development

Start immediately for testing:

npx @agenticmail/enterprise
# → Select "Local"
# → Server runs on http://localhost:3000

Server Configuration

import { createAdapter, createServer } from '@agenticmail/enterprise';

const db = await createAdapter({
  type: 'postgres',
  connectionString: 'postgresql://user:pass@host:5432/db',
});
await db.migrate();

const server = createServer({
  port: 3000,
  db,
  jwtSecret: 'your-secret-here',

  // Optional
  corsOrigins: ['https://app.acme.com'],
  rateLimit: 120,            // requests per minute per IP
  trustedProxies: ['10.0.0.0/8'],
  logging: true,
});

await server.start();

Middleware

All middleware is exported for use in custom server setups:

Resilience

Built-in resilience primitives:

import { CircuitBreaker, withRetry, HealthMonitor } from '@agenticmail/enterprise';

// Circuit breaker wrapping a database call
const breaker = new CircuitBreaker({ failureThreshold: 5, recoveryTimeMs: 30000 });
const result = await breaker.execute(() => db.query('SELECT ...'));

// Retry with backoff
const data = await withRetry(() => fetch('https://api.example.com'), {
  maxRetries: 3,
  baseDelayMs: 1000,
  backoffMultiplier: 2,
});

Programmatic Usage

Use Enterprise as a library in your own application:

import {
  // Database
  createAdapter,
  
  // Server
  createServer,
  
  // Engine
  PermissionEngine,
  BUILTIN_SKILLS,
  PRESET_PROFILES,
  AgentConfigGenerator,
  DeploymentEngine,
  ApprovalEngine,
  AgentLifecycleManager,
  KnowledgeBaseEngine,
  TenantManager,
  ActivityTracker,
  
  // Tool catalog
  ALL_TOOLS,
  getToolsBySkill,
  generateOpenClawToolPolicy,
  
  // Engine persistence
  EngineDatabase,
  
  // OpenClaw integration
  createEnterpriseHook,
  createAgenticMailBridge,
  
  // Resilience
  CircuitBreaker,
  withRetry,
  HealthMonitor,
  
  // Middleware (for custom servers)
  rateLimiter,
  auditLogger,
  requireRole,
} from '@agenticmail/enterprise';

Security

• JWT authentication with configurable secret and expiry
• API key authentication with scoped permissions
• RBAC — owner, admin, member, viewer roles
• Rate limiting — per-IP, configurable limits
• Audit logging — every mutation logged with actor, action, resource, timestamp
• Outbound email scanning — inherited from AgenticMail core (blocks PII, credentials, secrets)
• Security headers — CSP, HSTS, X-Frame-Options, X-Content-Type-Options
• Input validation — all API inputs validated before processing
• Circuit breaker — protects against cascading failures
• Graceful shutdown — clean connection teardown on SIGINT/SIGTERM

Project Structure

packages/enterprise/src/
├── cli.ts                    # Setup wizard (npx entry point)
├── server.ts                 # Hono API server
├── index.ts                  # Public exports
│
├── setup/                    # Setup wizard modules
│   ├── index.ts              # Wizard orchestrator
│   ├── company.ts            # Step 1: Company info prompts
│   ├── database.ts           # Step 2: Database selection + config
│   ├── deployment.ts         # Step 3: Deployment target
│   ├── domain.ts             # Step 4: Custom domain
│   └── provision.ts          # Provisioning logic (DB, admin, deploy)
│
├── auth/
│   └── routes.ts             # Login, token refresh, password reset
│
├── admin/
│   └── routes.ts             # User/agent/key/audit CRUD
│
├── middleware/
│   └── index.ts              # All middleware exports
│
├── db/                       # Database adapters
│   ├── adapter.ts            # Abstract DatabaseAdapter
│   ├── factory.ts            # createAdapter() + getSupportedDatabases()
│   ├── sql-schema.ts         # Shared SQL DDL
│   ├── sqlite.ts
│   ├── postgres.ts
│   ├── mysql.ts
│   ├── mongodb.ts
│   ├── dynamodb.ts
│   └── turso.ts
│
├── engine/                   # Agent deployment platform
│   ├── index.ts              # Public API (re-exports)
│   ├── skills.ts             # 38 skills, 5 presets
│   ├── agent-config.ts       # Config generator
│   ├── deployer.ts           # Deployment engine
│   ├── approvals.ts          # Approval workflows
│   ├── lifecycle.ts          # Agent state machine
│   ├── knowledge.ts          # Knowledge base
│   ├── tenant.ts             # Multi-tenant manager
│   ├── activity.ts           # Activity tracker
│   ├── tool-catalog.ts       # Tool ID catalog
│   ├── openclaw-hook.ts      # OpenClaw integration
│   ├── agenticmail-bridge.ts # AgenticMail integration
│   ├── db-adapter.ts         # Engine DB persistence
│   ├── db-schema.ts          # Engine DDL + migrations
│   └── routes.ts             # Engine REST API
│
├── deploy/                   # Deployment configs
│   ├── managed.ts            # Cloud deploy + Docker/Fly/Railway generators
│   └── fly.ts                # Fly.io API client
│
├── dashboard/
│   └── index.html            # Admin UI (single HTML, React 18)
│
├── lib/
│   └── resilience.ts         # CircuitBreaker, HealthMonitor, Retry, RateLimiter
│
└── ui/                       # (future) Component library

Author

Created by Ope Olatunji.

Part of the AgenticMail project — the first platform to give AI agents real email addresses and phone numbers.

• GitHub: @ope-olatunji
• Website: agenticmail.io
• Twitter: @agenticmail

License

MIT — see LICENSE