OwnwareDocs
OwnwareEngine
View source

Ownware

Open-source, self-hostable agent platform: build an agent as a text profile (a folder with agent.json + SOUL.md), serve it with one class (OwnwareGateway) as an HTTP+SSE service, and reach it from anywhere — terminals, web apps, Telegram, Slack — over one wire contract. Keyless local models via Ollama; Anthropic/OpenAI/Google/OpenRouter with one env var.

Packages: ownware (umbrella, the quickstart surface), @ownware/loom (agent runtime engine — loop, streaming, tools, zone security), @ownware/cortex (kernel & gateway — profiles, threads, SSE, connectors, vault, schedules), @ownware/shuttle (messaging channel adapters). Monorepo uses bun and Node ≥ 22: bun install && bun run build. Runnable example: examples/quickstart/.

Getting started

  • Quickstart: a live agent in three commands, no API key required
  • Installation: add Ownware to your own project and serve a profile
  • Thinking in Ownware: the mental model — profile, engine, gateway, channel — and where security lives

Building agents

  • Agents & profiles: an agent is a folder of text files; when to use profiles and how to serve them
  • Profile format: the profile directory and every commonly-used agent.json field (presets, security levels, connectors)
  • Hooks: declare lifecycle hooks in agent.json — audit webhooks, run archives, pause-for-approval (chat/web/terminal decision), per-model-call metering, operator-gated command hooks, and which mechanism to pick when
  • Hooks cookbook: copy-paste recipes for everyday jobs — approve-from-phone, finish notifications, per-client audit files, usage metering for billing, failure paging, custom check scripts, local debugging

Gateway & wire contract

  • Gateway: OwnwareGateway options, bearer-token auth, TLS default, where data lives (~/.ownware)
  • The run API: POST /api/v1/run, SSE event stream (+ event vocabulary), POST /resume for permissions, GET /models
  • Exposing the gateway: the bind-safety invariant (non-loopback forces auth+TLS), the persistent gateway-token file, TLS/proxy patterns

Security & configuration

  • Security overview: zones + combination rules, credential vault (engine only sees opaque handles), permission gates, unattended-run safety levels, channel pairing
  • Configuration reference: every OWNWARE_* env var and the GatewayOptions that matter in production

Capabilities

  • Tools & connectors: built-in presets, any MCP server, Composio SaaS toolkits, custom defineTool files
  • Models: provider:model strings, keyless Ollama path, provider env vars, model discovery
  • Channels: Shuttle adapters — Telegram, Slack, Discord, WhatsApp, SMS — session keys, delivery, group policies; ownware channel add + one-process ownware serve; schedules deliver to channels via ownware schedule add --deliver

Optional