omni

# CLI only
curl -fsSL https://raw.githubusercontent.com/automagik-dev/omni/main/install.sh | bash -s -- --cli

# Full server
curl -fsSL https://raw.githubusercontent.com/automagik-dev/omni/main/install.sh | bash -s -- --server

# Connect the CLI to a remote server after install
omni auth login --api-url https://your-omni-server.example.com --api-key <your-api-key>

Manual:

git clone https://github.com/automagik-dev/omni.git && cd omni
make setup    # install deps, create .env, start services

API runs at http://localhost:8882 · Swagger docs at /api/v2/docs · API key is printed in the startup banner.

# Auto-reply
omni automations create --name "welcome" \
  --trigger "message.received" \
  --action send_message --action-config '{"text":"Got it! 🐙"}'

# Webhook on connection
omni automations create --name "notify" \
  --trigger "instance.connected" \
  --action webhook --action-config '{"url":"https://your-app.example.com/hook"}'

# Route important senders to a dedicated agent
omni automations create --name "priority-route" \
  --trigger "message.received" \
  --condition '{"field":"payload.from","op":"in","value":["+15555550100"]}' \
  --action call_agent --agent-id "priority-handler" --provider-id <provider-id>

packages/
├── core/                    # Events, identity, schemas
├── db/                      # Drizzle ORM + PostgreSQL
├── api/                     # Hono + REST + OpenAPI
├── channel-sdk/             # Plugin SDK
├── channel-whatsapp/        # WhatsApp Baileys
├── channel-whatsapp-business/ # WhatsApp Cloud API (Meta)
├── channel-discord/         # Discord
├── channel-slack/           # Slack
├── channel-telegram/        # Telegram
├── channel-gupshup/         # Gupshup
├── channel-hermes/          # H3rmes (Brazilian WhatsApp gateway)
├── channel-twilio-whatsapp/ # Twilio WhatsApp
├── channel-a2a/             # A2A channel
├── channel-asc/             # ASC Brazil (ASCWhats GW, Cloud API mirror)
├── channel-asc-flow/        # ASC platform Flow (Brazilian BSP)
├── channel-harness/         # E2E agent-testing channel
├── channel-internal/        # In-process agent-to-agent routing
├── cli/                     # `omni` command
├── media-processing/        # Media sync and extraction
├── voice-client/            # Voice transport/codec library (Discord voice)
├── sdk/                     # TypeScript SDK
├── sdk-go/                  # Go SDK
└── sdk-python/              # Python SDK

send — Send messages

omni send --to "+15555550100" --text "Hello!"
omni send --to "+15555550100" --media ./photo.jpg --caption "Check this out"
omni send --to "+15555550100" --reaction "👍" --message <message-id>
omni send --to "+15555550100" --sticker ./sticker.webp
omni send --to "+15555550100" --contact --name "Example User" --phone "+15555550101"
omni send --to "+15555550100" --location --lat 37.7749 --lng -122.4194 --address "San Francisco"
omni send --to "discord-channel-id" --poll "Favorite color?" --options "Red,Blue,Green"
omni send --to "discord-channel-id" --embed --title "Alert" --description "Server rebooting" --color "#ff0000"
omni send --to "+15555550100" --presence typing

chats — Manage conversations

omni chats list --unread --sort unread
omni chats messages <chat-id> --limit 20 --rich
omni chats archive <chat-id>
omni chats participants <chat-id> --add "+15555550100"

messages — Search and manage

omni messages search "meeting tomorrow" --instance <id> --limit 10
omni messages read --chat <chat-id> --instance <id>

instances — Channel connections

omni instances list
omni instances create --name "work-whatsapp" --channel whatsapp-baileys
omni instances qr <id> --watch
omni instances create --name "ops-slack" --channel slack --slack-bot-token <bot-token> --slack-app-token <app-token>
omni instances connect <id>
omni instances sync <id> --type all --depth 30
omni instances contacts <id> --limit 50
omni instances groups <id>

Run omni instances --help for the full channel-specific command list.

persons — Contact directory

omni persons search "Example User"
omni persons get <id>
omni persons presence <id>

keys — API key management

omni keys create --name "agent-key" --scopes "messages:*,instances:read"
omni keys list --status active
omni keys revoke <id> --reason "Compromised"

providers — AI/agent providers

omni providers create --name "webhook-agent" --schema webhook --base-url "https://agent.example.com" --api-key <provider-api-key>
omni providers list
omni providers test <id>

Schemas: agno · webhook · ag-ui · claude-code · a2a · nats-genie

automations — Event-driven workflows

omni automations create --name "Auto-reply" --trigger "message.received" \
  --action send_message --action-config '{"text":"Got it!"}'
omni automations list --enabled
omni automations test <id> --event <event-id>   # dry-run against a real journaled event: condition verdicts, no side effects

Actions: webhook · send_message · emit_event · log · call_agent

access — Access control

omni access create --type deny --instance <id> --phone "+15555550100" --action block
omni access list --instance <id>
omni access check --instance <id> --user "+15555550100"

Modes: disabled · blocklist · allowlist

webhooks — External event sources

omni webhooks create --name "github-events" \
  --signature-algorithm hmac-sha256 --signature-header "X-Hub-Signature-256" --signature-prefix "sha256=" \
  --signature-secret-env GITHUB_WEBHOOK_SECRET \
  --event-type-mapping '{"source":"header","header":"X-GitHub-Event"}' \
  --idempotency-key-template "github:{headers.x-github-delivery}"
omni webhooks heartbeat github-events            # connector liveness check-in
omni webhooks trigger --type "custom.event" --payload '{"key":"value"}'

Sources receive on the public POST /api/v2/webhooks/ingress/:source endpoint (signature required). See the GitHub and ClickUp recipes.

schedule — Scheduled messages

omni schedule send <instance> <chat-id> "Stand-up in 10" --at 2h   # ISO timestamp or 30m/2h/3d
omni schedule list <instance>
omni schedule cancel <id>

Delivery is native where the channel supports it (Slack, text-only); everywhere else a local sweeper sends at the scheduled time.

tenants — Platform tenant control plane

omni tenants create --slug acme --name "Acme" --max-key-ttl 7776000 --max-key-rate 100 --max-key-budget 1000 --reason "onboarding"
omni tenants keys issue-root <tenant-id> --principal <uuid> --membership <uuid> --role tenant-owner \
  --name root --scopes "tenant:*" --expires 2026-12-01 --rate-limit 100 --budget 1000 --reason "bootstrap"
omni multitenancy status

Requires a PLATFORM-class credential and OMNI_MULTITENANCY_ENABLED=true; every command takes an audited --reason. Omni runs single-tenant by default — see platform credential bootstrap.

omni update -y                                  # update CLI; restart only services that were already online
omni update -y --no-restart                     # update CLI only; skip restarts and API-port health check
omni status                                     # verify runtime health
omni doctor                                     # diagnose embedded runtime issues
omni doctor --fix                               # repair safe runtime drift in-place
omni auth login --api-key <your-api-key>        # authenticate
omni config set defaultInstance <id>            # CLI settings
omni events list --type "message.*" --since 2h  # event history (trailing-* globs)
omni events types                               # observed event types: volume, schema, subscribers
omni events stream --pretty                     # live tail, one colored line per event
omni events trace <event-id>                    # causation chain
omni events wait --type "custom.x.*" --timeout 60  # block until a matching event
omni events schema register <type> --file s.json   # register a payload schema
omni events schema validate <type> --file p.json   # dry-run a payload, no event emitted
omni events consumers create <name> --type "custom.x.*"  # durable cursor
omni events follow --consumer <name>            # durable tail
omni events replay --start --since 2024-01-01   # replay events
omni journey show <correlation-id>              # per-message latency timeline
omni batch create --instance <id> --type targeted_chat_sync --chat <chat-id>
omni resync --instance <id>                     # history backfill
omni logs list --level error --limit 50         # server logs
omni dead-letters list --limit 20               # failed events

omni update can exit non-zero after install only when restart runs (services were already online): in that path it checks API health on the configured API port and fails on restart or health-check errors.

omni doctor --fix never deletes database data. It repairs safe runtime drift such as PM2 state, stored env, and CLI config; destructive cleanup remains manual.

API key is generated on first boot and shown once in the startup banner.

omni keys create --name "admin" --scopes "*"
omni keys create --name "reader" --scopes "messages:read,chats:read"
omni keys create --name "channel-only" --scopes "messages:*" --instances "uuid1,uuid2"

Scopes use the namespace:action pattern: messages:*, instances:read, * for full access.

Namespaces include: messages, chats, instances, persons, events, access, settings, providers, automations, webhooks, keys, logs, and batch.

Set *_MANAGED=false for external services. Full list: .env.example.

Managed NATS listens on loopback only once omni-nats is (re)created by omni start, omni install or a later omni update (omni restart keeps the previous arguments and warns when they differ). After upgrading an existing install, run omni stop && omni start once. Set NATS_HOST / server.natsHost to 0.0.0.0 only when other hosts must connect, and protect it (NATS auth/TLS or a private network). Apply with omni stop && omni start. See docs/guides/install.md.