@agenticmail/enterprise

AI Agent Identity, Email & Workforce Platform for Organizations

Deploy, manage, and govern AI agents as first-class employees — each with their own email address, skills, permissions, memory, and lifecycle. Built on AgenticMail + AgenticMail.

npx @agenticmail/enterprise

One command. Interactive setup wizard. Dashboard URL in under 2 minutes.

Table of Contents

• Overview
• Quick Start
• Setup Wizard
• Architecture
• Database Backends
• Engine Modules
• Agent Runtime
• MCP Integration Adapters
• Agent Tools
• Enterprise Skills
• Dashboard
• API Reference
• Deployment
• CLI Commands
• Security
• Community Skills
• Configuration
• License

Overview

AgenticMail Enterprise turns your organization's AI agents into managed employees:

• Identity — Each agent gets a real email address, phone number, and digital identity
• Skills — 47 enterprise skill definitions (Google Workspace, Microsoft 365, custom) + 147 SaaS integration adapters
• Permissions — Fine-grained tool-level access control with 5 preset profiles
• Governance — DLP scanning, guardrails, anomaly detection, compliance reporting, action journaling with rollback
• Workforce — Shifts, schedules, on-call rotations, capacity planning, birthday automation
• Runtime — Full agent execution loop with LLM streaming, session management, sub-agents, budget gates
• Dashboard — Admin UI with dark/light themes, real-time activity tracking, agent creation wizard

By the Numbers

Quick Start

Option A: Interactive Wizard (Recommended)

npx @agenticmail/enterprise

The wizard walks you through:

1. Company Info — Name, admin email, password, subdomain selection
2. Database — Pick from 10 backends (SQLite for dev, Postgres/MySQL/MongoDB/DynamoDB/Turso for production)
3. Deployment — AgenticMail Cloud, Fly.io, Railway, Docker, or Local
4. Custom Domain — Optional: point your own domain at the dashboard
5. Domain Registration — Optional: register with AgenticMail registry for domain protection

Option B: Programmatic

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

const db = await createAdapter({
  type: 'postgres',
  connectionString: process.env.DATABASE_URL,
});
await db.migrate();

const server = createServer({
  port: 3000,
  db,
  jwtSecret: process.env.JWT_SECRET,
});

await server.start();

Setup Wizard

The interactive setup wizard (npx @agenticmail/enterprise or npx @agenticmail/enterprise setup) guides you through every step with sensible defaults.

Step 1: Company Info

• Company name
• Admin email + password (min 8 chars, requires uppercase or number)
• Subdomain selection with auto-generated suggestions (slug from company name, abbreviations, variants)
• "Generate more" option for random suffix suggestions
• Custom subdomain input with validation

Step 2: Database

Choose from 10 backends organized by category:

Each option collects the right credentials:

• SQLite: File path (default: ./agenticmail-enterprise.db)
• DynamoDB: AWS Region + Access Key ID + Secret Access Key
• Turso: Database URL + Auth Token
• All others: Connection string with format hints

Step 3: Deployment

Step 4: Custom Domain (Optional)

For non-local deployments, optionally configure a custom domain. The wizard shows DNS instructions specific to your deployment target (CNAME for cloud/Fly, reverse proxy for Docker, Railway settings).

Step 5: Domain Registration (Optional)

Registers your domain with the AgenticMail central registry:

• Generates a 256-bit deployment key (shown once, must be saved)
• Creates a DNS TXT verification challenge
• Optional immediate DNS verification (retries 5x with 10s intervals)
• Recovery via agenticmail-enterprise recover if key is available

Architecture

┌─────────────────────────────────────────────────────────┐
│                   Admin Dashboard                        │
│              (React, dark/light themes)                   │
├─────────────────────────────────────────────────────────┤
│                    Hono API Server                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │  Auth     │  │  Admin   │  │  Engine  │              │
│  │  Routes   │  │  Routes  │  │  Routes  │              │
│  └──────────┘  └──────────┘  └──────────┘              │
├─────────────────────────────────────────────────────────┤
│                   Engine Modules (25+)                    │
│  Skills · Permissions · Lifecycle · Knowledge Base        │
│  DLP · Guardrails · Journal · Compliance · Activity      │
│  Communication · Workforce · Vault · Storage · Onboarding│
│  Policies · Memory · Approvals · Tenants · Deployer      │
│  Community Registry · Soul Library · Tool Catalog         │
├─────────────────────────────────────────────────────────┤
│                   Agent Runtime                           │
│  LLM Client · Session Manager · Tool Executor            │
│  Sub-Agent Manager · Email Channel · Follow-Up Scheduler │
├─────────────────────────────────────────────────────────┤
│              MCP Integration Framework                    │
│           147 SaaS Adapters · OAuth Connect               │
├─────────────────────────────────────────────────────────┤
│                Database Adapter Layer                     │
│  Postgres · MySQL · SQLite · MongoDB · DynamoDB · Turso  │
│  Supabase · Neon · PlanetScale · CockroachDB             │
└─────────────────────────────────────────────────────────┘

Middleware Stack

• Request ID — UUID per request for tracing
• Security Headers — CSP, HSTS, XSS protection
• CORS — Configurable origins
• Rate Limiting — Per-IP, configurable RPM (default: 120)
• IP Access Control — CIDR-based firewall
• Audit Logging — Every mutating action logged
• RBAC — Role-based access control (owner, admin, member, viewer)
• Error Handling — Structured error responses
• Circuit Breaker — Database connectivity protection
• Health Monitor — Periodic health checks with unhealthy threshold

Database Backends

All 10 backends implement the same DatabaseAdapter interface with full feature parity:

import { createAdapter, type DatabaseType } from '@agenticmail/enterprise/db';

const db = await createAdapter({
  type: 'postgres',  // or mysql, sqlite, mongodb, dynamodb, turso, supabase, neon, planetscale, cockroachdb
  connectionString: '...',
});

await db.migrate();        // Run schema migrations
await db.getStats();       // Health check
await db.createUser({...}); // CRUD operations
await db.logEvent({...});  // Audit logging

Adapter Details

Engine Database

SQL-backed deployments also get the EngineDatabase layer for engine module persistence:

const engineDbInterface = db.getEngineDB();
const engineDb = new EngineDatabase(engineDbInterface, 'postgres');
await engineDb.migrate(); // Versioned migration system

Features: DDL auto-conversion (sqliteToPostgres(), sqliteToMySQL()), dynamic table creation with ext_ prefix, agent storage tables with agt_/shared_ prefixes.

Engine Modules

The engine is the core of Enterprise — 25+ modules that power agent governance:

1. Skill Registry & Permission Engine

• 47 built-in enterprise skill definitions (Google Workspace, Microsoft 365, custom)
• Fine-grained tool-level permissions (allow/deny per tool)
• 5 preset profiles: Research Assistant, Customer Support, Developer, Full Access, Sandbox
• Skill suites for bulk assignment
• Risk level classification (low, medium, high, critical)
• Side effect tracking (read, write, delete, external, financial)

2. Agent Config Generator

• Generates workspace files (SOUL.md, AGENTS.md, etc.)
• Gateway configuration
• Channel configs (email, Slack, Teams, etc.)
• Deployment scripts per target

3. Deployment Engine

• Docker, VPS, Fly.io, Railway provisioning
• Deployment event tracking
• Live agent status monitoring

4. Approval Workflows

• Human-in-the-loop approval policies
• Escalation chains with multi-level escalation
• Time-based auto-escalation
• Approval/rejection with audit trail

5. Agent Lifecycle Manager

• State machine: provisioning → active → paused → stopped → decommissioned
• Health checks and auto-recovery
• Budget controls with alerts and hard limits
• Usage tracking (tokens, cost, API calls)
• Birthday automation (sends birthday emails to agents on their DOB)

6. Knowledge Base

• Document ingestion and chunking
• BM25F text search (extracted to shared library)
• RAG retrieval for agent context
• Multi-knowledge-base support per org

7. Multi-Tenant Isolation

• Organization management with plan enforcement
• 4 plan tiers: Free (3 agents), Team (25), Enterprise (unlimited), Self-Hosted (unlimited)
• Feature gates per plan
• SSO configuration (Google, Microsoft, GitHub, Okta, SAML, LDAP)
• Usage quotas and billing

8. Real-Time Activity Tracking

• Live tool call recording
• Conversation logging
• Agent timelines
• Cost tracking per agent/org

9. Tool Catalog

• 86+ cataloged tool IDs across all AgenticMail packages
• Tool-to-skill mapping
• Dynamic tool policy generation

10. Data Loss Prevention (DLP)

• Content scanning rules (PII, credentials, sensitive data)
• Violation tracking and alerting
• Configurable rule sets per org

11. Agent-to-Agent Communication

• Message bus (direct, broadcast, topic-based)
• Task assignment and delegation
• Priority levels (normal, high, urgent)
• Agent email registry integration

12. Guardrails & Anomaly Detection

• Real-time intervention system
• Configurable anomaly rules (rate limits, cost thresholds, pattern matching)
• Auto-stop agents on violation
• Onboarding gate checks
• Workforce off-duty enforcement

13. Action Journal & Rollback

• Every agent action journaled with before/after state
• Rollback capability for reversible actions
• Audit trail with timestamps and actor

14. Compliance Reporting

• SOC2, GDPR, HIPAA report generation
• Data retention policies
• Access audit reports

15. Community Skill Registry (Marketplace)

• Install community skills from the marketplace
• Automatic periodic sync from GitHub (every 6 hours)
• Skill reviews and ratings
• Local directory loading for development
• Validation CLI for skill authors

16. Workforce Management

• Shift schedules and on-call rotations
• Capacity planning
• Off-duty enforcement via guardrails
• Work-life balance rules

17. Organization Policies

• Global and per-org policy configuration
• Policy import/export
• Compliance policy templates

18. Agent Memory

• Long-term memory persistence
• Memory queries and search
• Cross-session continuity

19. Onboarding Manager

• Agent onboarding workflows
• Onboarding gates (must complete before agent goes live)
• Policy acknowledgment tracking

20. Secure Vault

• Encrypted credential storage
• API key management
• OAuth token management
• DLP-integrated access control

21. Storage Manager

• Dynamic table management for agents
• Agent-scoped tables (agt_ prefix)
• Shared tables (shared_ prefix)
• 28 storage actions (create, query, aggregate, import/export, raw SQL, etc.)

22. Soul Library

• 51 personality templates across 14 categories
• Search and browse templates
• Custom soul creation

23. Knowledge Contribution Manager

• Agents contribute learned knowledge back to org knowledge bases
• Scheduled aggregation

24. Skill Auto-Updater

• Monitors community skill registry for updates
• Auto-applies compatible updates
• Scheduled update checks

25. OAuth Connect

• OAuth flow management for SaaS integrations
• Token storage in vault
• Refresh token rotation

Agent Runtime

Full standalone agent execution runtime — run agents entirely in-process without AgenticMail:

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

const runtime = createAgentRuntime({
  engineDb: db,
  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY },
});

await runtime.start();

const session = await runtime.spawnSession({
  agentId: 'agent-1',
  message: 'Research Q3 revenue trends and draft a summary email',
});

Runtime Features

• LLM Client — Multi-provider (Anthropic, OpenAI, custom), streaming, retry with exponential backoff
• Session Manager — Incremental message persistence, crash recovery, session resume on startup
• Tool Executor — 28 built-in tools with security sandboxing
• Sub-Agent Manager — Spawn child agents for parallel work
• Email Channel — Bi-directional email communication
• Follow-Up Scheduler — Schedule agent follow-ups and reminders
• Budget Gates — Cost check before every LLM call
• Gateway Integration — Register as AgenticMail plugin for hybrid deployments
• Heartbeat — Stale session detection and cleanup
• SSE Streaming — Real-time event streaming for dashboard

Supported LLM Providers

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

// Built-in: anthropic, openai
// Custom providers can be registered via PROVIDER_REGISTRY

MCP Integration Adapters

147 pre-built adapters for connecting agents to SaaS tools via Model Context Protocol:

MCP Framework

import { SkillMCPFramework } from '@agenticmail/enterprise/mcp';

// Each adapter provides:
// - Tool definitions (name, description, parameters, schema)
// - API executor with credential resolution
// - OAuth flow configuration
// - Rate limit handling

The framework includes:

• API Executor — HTTP client with retry, rate limiting, pagination
• Credential Resolver — Pulls secrets from Vault, env, or OAuth tokens
• AWS SigV4 — Native AWS request signing for DynamoDB, S3, etc.

Agent Tools

28 built-in tools available to agents running in the Enterprise runtime:

Tools include a security middleware layer for permission checking and DLP scanning.

Enterprise Skills

47 pre-built skill definitions organized into 3 suites:

Google Workspace (14 skills)

Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Meet, Chat, Keep, Sites, Groups, Admin, Vault

Microsoft 365 (17 skills)

Outlook, Teams, OneDrive, Word, Excel, PowerPoint, SharePoint, Planner, Todo, OneNote, Forms, Bookings, Power BI, Power Automate, Whiteboard, Copilot, Admin

Enterprise Custom (16 skills)

Calendar, Code Sandbox, Database, Diff, Documents, Finance, HTTP, Knowledge Search, Logs, Notifications, Security Scan, Spreadsheet, Translation, Vision, Web Research, Workflow

Each skill definition includes:

• Tool list with parameter schemas
• Required configuration fields
• Risk level and side effect classification
• Category and description

Dashboard

React-based admin dashboard served from the enterprise server:

• Dark/Light themes — Professional design with CSS custom properties
• Dynamic brand color — Uses settings.primaryColor throughout
• Agent management — Create, configure, start/stop, monitor
• Real-time activity — Live tool calls, conversations, cost
• Knowledge bases — Upload, manage, search documents
• Approval workflows — Review and approve/reject pending requests
• Compliance — View reports, DLP violations, audit logs
• Settings — Company info, SSO, security, billing
• Onboarding — Agent creation wizard with soul template selection

API Reference

The API is organized into 3 major sections:

Auth Routes (/api/auth/*)

• POST /api/auth/login — Login with email/password
• POST /api/auth/refresh — Refresh JWT tokens
• POST /api/auth/logout — Logout (invalidate cookies)
• SSO callback routes for Google, Microsoft, GitHub, Okta

Admin Routes (/api/admin/*)

• Agent CRUD, user management, settings, audit log
• Bridge API for unified agent management (/api/admin/bridge/agents)

Engine Routes (/api/engine/*)

328 routes across 22 sub-apps:

Deployment

Docker

npx @agenticmail/enterprise  # Select "Docker" in Step 3
docker compose up -d

Generates docker-compose.yml + .env with all secrets.

Fly.io

npx @agenticmail/enterprise  # Select "Fly.io" in Step 3
fly launch --copy-config
fly secrets set DATABASE_URL="..." JWT_SECRET="..."
fly deploy

Railway

npx @agenticmail/enterprise  # Select "Railway" in Step 3
railway init && railway link && railway up

AgenticMail Cloud

npx @agenticmail/enterprise  # Select "AgenticMail Cloud" in Step 3
# Instant URL: subdomain.agenticmail.io

Local / Development

npx @agenticmail/enterprise  # Select "Local" in Step 3
# Server starts on http://localhost:3000

Or with pm2 for production:

pm2 start dist/cli.js --name agenticmail-enterprise --watch

CLI Commands

# Interactive setup wizard (default)
npx @agenticmail/enterprise

# Validate a community skill manifest
npx @agenticmail/enterprise validate ./community-skills/my-skill/
npx @agenticmail/enterprise validate --all
npx @agenticmail/enterprise validate --json

# AI-assisted skill scaffolding
npx @agenticmail/enterprise build-skill

# Submit a skill to the marketplace
npx @agenticmail/enterprise submit-skill ./community-skills/my-skill/

# Recover a domain registration on a new machine
npx @agenticmail/enterprise recover --domain agents.agenticmail.io --key <hex>

# Check DNS verification status
npx @agenticmail/enterprise verify-domain
npx @agenticmail/enterprise verify-domain --domain agents.agenticmail.io

Security

Authentication

• httpOnly cookies — em_session, em_refresh, em_csrf (not localStorage JWT)
• CSRF protection — Double-submit cookie pattern
• SSO — Google, Microsoft, GitHub, Okta, SAML 2.0, LDAP
• Password hashing — bcrypt with cost factor 12
• JWT — Short-lived access tokens + long-lived refresh tokens

Authorization

• RBAC — 4 roles: owner, admin, member, viewer
• Per-tool permissions — Allow/deny at individual tool level
• Approval workflows — Human-in-the-loop for sensitive operations
• Budget gates — Hard cost limits per agent

Data Protection

• DLP Engine — Content scanning for PII, credentials, sensitive data
• Secure Vault — Encrypted credential storage with access control
• Egress Filter — Outbound request filtering
• IP Firewall — CIDR-based access control
• Audit Logging — Every mutating action logged with actor, timestamp, details

Infrastructure

• Rate Limiting — Per-IP, configurable
• Circuit Breaker — Database connectivity protection
• Security Headers — CSP, HSTS, X-Frame-Options, X-Content-Type-Options
• Domain Lock — Cryptographic domain registration to prevent unauthorized duplication

Community Skills

Build and share skills through the community marketplace:

Creating a Skill

npx @agenticmail/enterprise build-skill

The AI-assisted scaffolding tool generates:

• manifest.json — Skill metadata, tools, permissions, config fields
• Tool implementations
• README with usage instructions

Skill Manifest Format

{
  "name": "my-skill",
  "version": "1.0.0",
  "description": "What this skill does",
  "author": "your-name",
  "license": "MIT",
  "category": "productivity",
  "tools": [
    {
      "name": "my_tool",
      "description": "What this tool does",
      "parameters": { ... },
      "riskLevel": "low",
      "sideEffects": ["read"]
    }
  ],
  "config": [
    { "name": "API_KEY", "type": "secret", "required": true }
  ]
}

Validating

npx @agenticmail/enterprise validate ./community-skills/my-skill/

Submitting

npx @agenticmail/enterprise submit-skill ./community-skills/my-skill/

Skills are synced from the GitHub repository every 6 hours to all deployments.

Configuration

Environment Variables

Server Config (Programmatic)

createServer({
  port: 3000,
  db: adapter,
  jwtSecret: 'your-secret',
  corsOrigins: ['https://your-domain.com'],
  rateLimit: 120,
  trustedProxies: ['10.0.0.0/8'],
  logging: true,
  runtime: {
    enabled: true,
    defaultModel: { provider: 'anthropic', modelId: 'claude-sonnet-4-20250514' },
    apiKeys: { anthropic: '...' },
  },
});

Requirements

• Node.js 18+
• Database — Any of the 10 supported backends
• LLM API Key — Anthropic or OpenAI (for agent runtime)

License

MIT — See LICENSE

Built by AgenticMail · GitHub · AgenticMail