OwnwareDocs
OwnwareEngine
View source
howto

Installation

This page installs Ownware into your own project. If you just want to see it run first, do the Quickstart.

Prerequisites — Node ≥ 22.

1. Install the package

bash
bun add ownware          # bun
npm install ownware      # npm
pnpm add ownware         # pnpm

The ownware umbrella package is the curated surface: OwnwareGateway, defineTool, profile helpers, and the in-process engine. Power users can import @ownware/loom (engine) or @ownware/cortex (kernel/gateway) directly.

Native dependencies build on install. Ownware compiles a couple of native modules (better-sqlite3, node-pty) and fetches a ripgrep binary during postinstall. On most machines this is automatic; if it fails you're missing platform build tools — see Troubleshooting.

2. Create a profile

A profile is a folder of text files. The minimum is one JSON file:

profiles/my-agent/agent.json
{
  "name": "my-agent"
}

Optionally give it a personality:

profiles/my-agent/SOUL.md
You are a concise, helpful assistant for my project.

Every other setting (model, tools, security) has a sensible default — see Profile format. The default model is anthropic:claude-sonnet-4-6.

The agent needs a model to reply. With no model key set, the run starts but never answers. Either set a provider key first (export ANTHROPIC_API_KEY=…, or ownware key add anthropic for the encrypted vault), or point the profile at a local model — add "model": "ollama:llama3.2" to agent.json and run Ollama (no key needed). See Models.

3. Serve it

serve.mjs
import { OwnwareGateway } from 'ownware'

// tls:false is for localhost only — the gateway defaults TLS *on* (see the
// warning below). Without it, this serves HTTPS and the plain http:// curl
// below would fail.
const ownware = new OwnwareGateway({ profilesDir: './profiles', port: 4000, tls: false })
await ownware.start()

console.log(`live at http://localhost:${ownware.port} — token: ${ownware.token}`)
bash
node serve.mjs

Verify it works

bash
curl -X POST http://localhost:4000/api/v1/run \
  -H "Content-Type: application/json" \
  -d '{"profileId":"my-agent","prompt":"hello"}'

You should get back JSON containing a threadId — the run has started. Stream the reply per The run API.

On a localhost bind, gateway auth is off, so no Authorization header is needed. The moment you expose the gateway beyond loopback, auth turns on (and can't be disabled) — then every request needs Authorization: Bearer <token>. See Exposing the gateway.

Where data lives

Everything the gateway stores (threads, credential vault, memory) lives in ~/.ownware/ on your machine. Override with OWNWARE_DATA_DIR. Delete the folder to reset everything.

Warning — the gateway defaults to TLS on. tls: false (as in the quickstart) is for localhost only; before exposing an agent beyond loopback, keep TLS on and read Exposing the gateway.

Next steps