ownware

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/ownware-lockup-dark.svg"> <img src="docs/assets/ownware-lockup.svg" alt="Ownware" width="380"> </picture> </p> <p align="center"> <strong>The open agent runtime for products you own.</strong><br> <em>A self-hosted harness and operational backend in one package: portable agent profiles, a production-shaped loop, durable threads, permission gates, storage, and one typed streaming API.</em> </p> <p align="center"> <a href="https://docs.ownware.dev"><img src="https://img.shields.io/badge/Docs-docs.ownware.dev-3E5CE0.svg?style=for-the-badge&logo=readthedocs&logoColor=white" alt="Documentation"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=for-the-badge" alt="Apache-2.0"></a> <img src="https://img.shields.io/badge/Node-%E2%89%A522-339933.svg?style=for-the-badge&logo=nodedotjs&logoColor=white" alt="Node ≥ 22"> <img src="https://img.shields.io/badge/runtime-bun-f9f1e1.svg?style=for-the-badge&logo=bun&logoColor=black" alt="bun"> <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge" alt="PRs welcome"></a> </p> <p align="center"> <a href="https://docs.ownware.dev"><strong>📖 Read the docs → docs.ownware.dev</strong></a> </p> --- ## The runtime behind your agent product A model call is not an agent product. The production boundary also needs a reliable loop, tool execution, durable conversations, resumable streaming, approvals, credentials, storage, and an API every client can use. **Ownware ships that boundary as one open-source process or one class.** Define an agent as ordinary text files, run it on infrastructure you control, and build your application against a typed HTTP+SSE contract. The CLI, SDK, React bindings, schedules, and messaging adapters are all clients of that same runtime. - **Profile in.** `agent.json`, `SOUL.md`, skills, and tools form a portable, reviewable agent definition. - **Durable service out.** Threads, checkpoints, permission continuation, storage, schedules, and streaming are already wired. - **Your product around it.** Bring your own interface, business logic, and supported model route without forking the runtime. If this resonates: **⭐ star the repo** — it's how a solo-dev project gets seen — and [come build it with me](#give-us-a-hand). ## Why Ownware exists Most agent projects begin with a loop and quickly become a backend project: thread state, retries, permissions, secrets, reconnects, model routing, and the contract between the runtime and every UI. Each is easy to sketch and expensive to operate honestly. Ownware makes that operational boundary reusable. It owns the loop, exposes the runtime through a stable contract, and keeps product-specific UI and business logic outside the core. **Freeware was free. Shareware was shared. Ownware is owned:** you run it, inspect it, extend it, and keep the durable agent asset on infrastructure you control. Everything here is **free and open (Apache-2.0)** — the runtime, gateway, client contracts, adapters, and security primitives. --- ## How it works ``` 1. DEFINE the agent as ordinary files → 2. RUN the complete runtime → 3. BUILD on one contract (a portable profile) (one process or class) (HTTP+SSE) ``` - **Provider-neutral by contract.** Use a documented cloud route, an OpenAI-compatible endpoint, or fully local [Ollama](https://ollama.com). The first answer can work **without an API key**. - **Yours.** Self-hosted; provider credentials remain inside your runtime's encrypted vault. Providers and tools you choose receive the data sent for those calls. SQLite is the zero-configuration default; library deployments can explicitly select tenant-owned PostgreSQL while local protected artifacts stay on your infrastructure. - **Safe by default.** Exposing beyond localhost force-enables auth + TLS; an unsafe bind refuses to boot. Dangerous tool calls pause and ask first. - **One wire contract.** The CLI, SDK, your application, and optional adapters all talk to the agent the same way. Learn it once; keep product logic out of the runtime. ### A harness and operational backend in one runtime Ownware includes the execution loop—streaming, parallel tool orchestration, sub-agents, compaction, retries, and MCP—and the service boundary around it: durable threads, resumable events, credentials, schedules, storage, auth, and typed clients. Use the engine directly when you need an in-process harness, or start the gateway when your product needs a long-running agent service. That combination is the point. Ownware does not need every framework or SDK to lack these features; it gives adopters one inspectable, Apache-2.0 runtime where the loop, the operational backend, and the public contract are designed together. > **Status:** early and moving fast. The package is live on npm (`npm i -g ownware`); > contributors can also run it from source (below). The engine, gateway, channels, and > security are built and covered by an automated test suite (7,000+ tests across the > packages); the five channel adapters are at varying maturity. It's early software — > expect rough edges and tell us where you hit them. ## Step 0 — Install Requires Node ≥ 22 (plus [bun](https://bun.com) ≥ 1.3 if you build from source). ```bash npm install -g ownware # or: bun add -g ownware · pnpm add -g ownware ``` Now you have the `ownware` command. Check it: `ownware --help`. > 📦 **Contributing, or want the bleeding edge?** Run it from source — the same > commands, just prefixed with `bun run`: > ```bash > git clone https://github.com/ownware-ai/ownware.git && cd ownware > bun install && bun run build # then use `bun run ownware …` in place of `ownware …` > ``` ## Step 1 — Build your agent (it's just a folder of text) ```bash ownware init ``` That drops a starter agent into `./profiles/assistant/`: ``` profiles/assistant/ ├── agent.json # WHAT it can do — model, tools, security └── SOUL.md # WHO it is — personality and rules (plain markdown) ``` **Editing these files IS building the agent.** No SDK, no build step, no wizard. Open `SOUL.md` and change its personality. Open `agent.json` and: - pick a supported model route — `"openai:gpt-5.5"`, `"anthropic:claude-sonnet-4-6"`, `"ollama:llama3.2"` (local, free)… - give it tools — built-in presets (files, shell, web), **MCP servers over supported transports**, 400+ SaaS apps via Composio, or your own custom tool files - set its security — permission mode, security level, allow/deny lists Add `skills/` (markdown how-tos) and `AGENTS.md` (its memory) as it grows. Because an agent is text, you can version it in git, review it in a PR, and share it like a package — [`profiles/`](profiles) ships ready-made examples (law, finance, research, security, trading…). Full format: [docs/agents/profile-format.md](docs/agents/profile-format.md) **Now talk to it — right here, no server:** ```bash ownware key add openai # save a key once (or go keyless with Ollama) ownware run assistant "hello — introduce yourself" ``` `ownware run` assembles the agent and streams its reply straight to your terminal — no gateway, no glue. That's the whole build → talk loop. (Prefer another folder as its workspace? `ownware run assistant -w ./my-app "…"`.) Every command: [**the `ownware` CLI reference →**](docs/reference/cli.md) ## Step 2 — Serve it (one process, locally today, anywhere tomorrow) You only need this when something *else* has to reach the agent — Slack, a web app, a schedule. It's the same agent, now a service: ```bash ownware serve ``` Your agent is now a **live HTTP+SSE service** at `http://localhost:3011` — runs and streaming replies, persistent conversation threads, the credential vault, permission approvals, schedules, channels: the whole backend in one process. `serve` prints a copy-paste curl that answers immediately: ```bash curl -X POST http://localhost:3011/api/v1/run \ -H 'Content-Type: application/json' \ -d '{"profileId":"assistant","prompt":"hello"}' ``` **No API key?** Install Ollama (`ollama pull llama3.2`) and it answers fully local. Have a key? `ownware key add openai` (or `anthropic` · `google` · `openrouter`) stores it encrypted. ### How deployment works (today) The default CLI deployment is deliberately **one ordinary Node process + one data folder** (`~/.ownware`) using SQLite. Deploying = running that same command on any machine — a VPS, a Raspberry Pi, a container: ```bash ownware serve --host 0.0.0.0 --port 3011 ``` The moment the bind leaves localhost, Ownware's **bind-safety invariant** kicks in automatically: auth forced ON (clients need `Authorization: Bearer <token>` — printed at boot, persisted at `~/.ownware/gateway-token`), TLS forced ON, and disabling either **refuses to boot**. There is no accidentally-open deployment. For browsers / real domains, put a reverse proxy or tunnel (Caddy, nginx, Tailscale, cloudflared) in front — [docs/gateway/exposing.md](docs/gateway/exposing.md). Library deployments can instead use a tenant-owned PostgreSQL database; see [gateway storage](docs/gateway/storage.md). **Single-click deploy?** Not yet — honestly. Today it's *one command*, not one click. PostgreSQL deployments must also provision or connect the database. If it runs Node, it runs Ownware now. ## Step 3 — Build against one contract **Raw HTTP.** Any language: `POST /api/v1/run` starts a run, an SSE stream delivers the reply token by token. Fully specified in [`packages/client/spec/`](packages/client/spec) (OpenAPI + AsyncAPI). **The SDK.** [`@ownware/client`](packages/client): zero dependencies, Node *and* browser: ```ts import { OwnwareClient } from '@ownware/client' const agent = new OwnwareClient({ baseUrl: 'http://localhost:3011' }) const { threadId } = await agent.run({ profileId: 'assistant', prompt: 'hello' }) for await (const ev of agent.streamReply(threadId)) { if (ev.type === 'delta') process.stdout.write(ev.text) } ``` **Optional messaging adapters.** The same agent answers in Slack, Telegram, Discord, WhatsApp, SMS — `ownware serve` runs the channels in-process, no second deployment: ```bash ownware channel add slack --profile assistant --bot-token xoxb-… --app-token xapp-… ownware serve # gateway + Slack, one process ``` Unknown senders are held behind fail-closed pairing until you `ownware channel approve` them — your agent doesn't talk to strangers. **Scheduled runs.** Start work on a schedule and optionally deliver the result: ```bash ownware schedule add --profile assistant --name morning \ --prompt "summarize my inbox" --daily 08:30 --deliver slack:#general ``` Every morning at 08:30 the agent runs and posts its answer to `#general`. Quiet days stay quiet; failures are reported honestly — `ownware schedule runs <id>` shows the true ledger, never a silent drop. ## Step 4 — Build your own application on top The gateway is a full agent backend; your product only needs a frontend (or another backend) that speaks the wire contract. You need exactly three things: the **URL**, the **token** (when exposed), and a client — `@ownware/client` or plain fetch in any language. | Call | What it does | |---|---| | `run({ profileId, prompt, threadId? })` | Send a message. Same `threadId` = same conversation. | | `streamReply(threadId)` | One reply as streaming text deltas → done. | | `events(threadId)` | The RAW stream — tool calls, thinking, permission requests. Build rich UIs from this. | | `resume(threadId, { action })` | Answer a `permission.request` — approve/deny in *your* UI. | | `abort(threadId)` | Stop button. | | `providerHubModels({ scope: 'connected' })` / `health()` | Canonical model routes with live connection state and prices / liveness. | That's enough for a support widget, an internal copilot, a mobile app, a voice bot. Threads give every user a continuous, isolated conversation; dropped connections resume from the last event; the permission flow lets your app surface approvals natively. Non-JS teams generate clients from the [OpenAPI/AsyncAPI spec](packages/client/spec). Prefer to stay in-process? The whole backend is a library: ```ts import { OwnwareGateway } from 'ownware' const agent = new OwnwareGateway({ profilesDir: './profiles', port: 4000 }) await agent.start() ``` ## Everything in the kit today (all free, all open) <table> <tr><td><b>Agents as text</b></td><td>A profile is a folder — <code>agent.json</code> + <code>SOUL.md</code> + skills + memory. Version it, review it, share it. Bundled examples in <a href="profiles"><code>profiles/</code></a>.</td></tr> <tr><td><b>Multiple model routes, keyless first</b></td><td>Anthropic, OpenAI, Google, OpenRouter, OpenAI-compatible endpoints, or local Ollama. A local first answer needs no API key; cloud keys live in an encrypted vault (<code>ownware key add</code>).</td></tr> <tr><td><b>A real agent engine</b></td><td>Provider-agnostic loop with streaming, parallel tool orchestration, retry with backoff, checkpointing — production plumbing, not a demo loop.</td></tr> <tr><td><b>Batteries-included tools</b></td><td>Your agent works out of the box: <b>filesystem</b> (read/write/edit/glob/grep), <b>shell</b> (guarded, with persistent sessions), <b>real browser automation</b> (Playwright-backed — navigate, click, extract), <b>web search + fetch</b>, task lists, memory, ask-the-user. <b>Image generation</b> and <b>speech</b> (TTS/STT) are bring-your-own-provider hooks.</td></tr> <tr><td><b>Extensible tools</b></td><td>MCP servers (stdio or URL), Composio's SaaS catalogue, or your own custom tool files (<code>defineTool</code>) — declared in <code>agent.json</code>, without changing the engine.</td></tr> <tr><td><b>Multi-agent</b></td><td>Agents spawn sub-agents: isolated workers for parallel workstreams, forked contexts, a coordinator protocol — one agent can run a team.</td></tr> <tr><td><b>Never dies at the context limit</b></td><td>Pluggable compaction strategies — summarize, sliding window, truncate, tool-result drop, hierarchical — so long-running tasks keep going instead of hitting a wall.</td></tr> <tr><td><b>One-process backend</b></td><td><code>ownware serve</code>: HTTP/2 + SSE gateway, persistent threads, resumable streams, schedules, vault, auth — the whole backend as one process or one class.</td></tr> <tr><td><b>Messaging channels</b></td><td>Slack, Telegram, Discord, WhatsApp, SMS — run in-process with <code>ownware serve</code>; fail-closed pairing for unknown senders.</td></tr> <tr><td><b>Proactive schedules</b></td><td>Daily / interval / one-off runs (timezone- and DST-correct) that deliver results to a channel — with an honest run ledger.</td></tr> <tr><td><b>SDK + wire spec</b></td><td><code>@ownware/client</code>: zero-dep, Node + browser. OpenAPI + AsyncAPI specs for every other language.</td></tr> <tr><td><b>Security stack</b></td><td>Bind safety (no unsafe boot), credential vault (engine only sees opaque handles), 7-level zones + combination rules, human-in-the-loop permission gates, draft-approval for unattended runs. Core and free, forever.</td></tr> <tr><td><b>CLI</b></td><td><code>ownware profile · run · serve · key · channel · schedule</code> — build, talk to, and deploy an agent from one command; full <a href="docs/reference/cli.md">CLI reference</a>. No wizard.</td></tr> </table> ## Safe by default (the reason your boss says yes) Security primitives are core and free — never a paid tier: bind safety (non-loopback forces auth + TLS), the encrypted credential vault (no secret ever in plaintext — not in events, logs, or the DB), zone classification with combination rules (catches *read a secret, then call the network*), and permission gates wired into the public contract so every client can render approve/deny. It's the closer, not the headline — the reason the answer is *yes* when compliance asks "can we actually deploy this?" Full story: [docs/security/overview.md](docs/security/overview.md) ## Project status Built and test-covered today: the engine and gateway, portable profile format, CLI, keyless local first answer, bind safety, SQLite and PostgreSQL storage, `@ownware/client` plus OpenAPI/AsyncAPI specs, headless and React chat bindings, schedules, and five optional messaging adapters. It is installable from npm (`npm i -g ownware`) and remains early software: expect rough edges, verify the capability envelope you depend on, and report failures precisely. ## Give us a hand Ownware is one person and a big goal: **make the runtime beneath agent products open, portable, and owned by the people who run it.** If you're like-minded: - **⭐ Star the repo** — visibility is oxygen for a solo project. - **Open an issue** — tell me the agent you tried to build and where the kit fought you. Activation friction is a bug. - **Send a PR** — [CONTRIBUTING.md](CONTRIBUTING.md) has the setup and the hard rules; [VISION.md](VISION.md) defines the runtime boundary and the "what we won't merge" list — two minutes there saves a wasted PR. Great first contributions: a new channel adapter (a channel is a thin client of one contract — a weekend, not a fork), an example profile for your industry, or a precise docs fix. Everyone interacting here is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md). ## Docs by goal | You want to… | Read | |---|---| | See it run in 5 minutes | [Step 0](#step-0--install) above, or the [quickstart](docs/getting-started/quickstart.md) | | Every `ownware` command | [docs/reference/cli.md](docs/reference/cli.md) | | Build / customize an agent | [docs/agents/profile-format.md](docs/agents/profile-format.md) | | Put it on a server safely | [docs/gateway/exposing.md](docs/gateway/exposing.md) | | Understand the security model | [docs/security/overview.md](docs/security/overview.md) | | Build an app on the API | [packages/client/spec](packages/client/spec) (OpenAPI + AsyncAPI) | | Configure every knob | [docs/reference/configuration.md](docs/reference/configuration.md) | | Get a quick answer / fix a problem | [docs/faq.md](docs/faq.md) · [docs/troubleshooting.md](docs/troubleshooting.md) | | Everything else | [docs/index.md](docs/index.md) | ## Development ```bash bun run build # all packages, dependency order bun run typecheck # every package bun run test # every suite (LLM/network e2e lanes are env-gated) bun run smoke # keyless first-run canary: boot + health + models ``` Local operational data lives in `~/.ownware/` (`OWNWARE_DATA_DIR` overrides); durable application state can use SQLite there or a tenant-owned PostgreSQL database. See [gateway storage](docs/gateway/storage.md). Security reports: [SECURITY.md](SECURITY.md). ## License [Apache-2.0](LICENSE) — free for any use, including commercial.