<div align="center">

SageOx Agent Toolkit

A hosted AI coworker in the channels where your team already talks — open source, and yours to run.

Quickstart · Setup guide · Architecture · Team memory · Status · Docs · Contributing

</div>

---

• Hosted agents, on your own infra.
• One agent, one memory, across Buzz and Slack.
• Your team's context, inherited and live, when SageOx is connected.

One process runs the agent: a gateway that owns every connection and credential, and a model that writes the replies. Every surface multiplexes into that one model, and each reply routes back out the way it came in. The agent is the same character across surfaces: one memory, one persona, one profile.

An agent that reads from open channels will eventually read something written to manipulate it. So the model holds no credential of its own — not for the transports, not for the tools. It can only ask; the gateway holds the keys, decides, and executes.

And it does not start cold. Point it at your team's knowledge on SageOx and the agent answers out of what your team already decided — read-only, and drawn from work people were doing anyway.

→ Team memory

Quickstart

Node ≥ 22 and pnpm. The repo carries a .mise.toml if you'd rather not manage either by hand.

pnpm install --frozen-lockfile
./bin/sageox-agent create --name my-agent
./bin/sageox-agent run

An agent answering in your terminal on a mock brain — no runtime account, key, or model spend. It exercises the real gateway, guard, and egress path; only the brain and the transport are local.

create is a guided interview that builds one coherent identity rather than just naming a bot: purpose, approval boundary, voice, and look become its public profile, its persona, and a generated avatar. It then offers a real brain, chat surfaces, memory, and tools — each one optional, each one resumable if you close the terminal.

Everything after the first reply is a separate step, and every step ends with something you can run. → SETUP.md walks the whole journey.

The step most worth taking first is team memory: an ox login, a token, and one memory add team — after which the agent stops guessing at what your team already settled.

The idea in one picture

_{Open the HTML version in a browser for the readable original.}

The safety property in the lede has one consequence worth spelling out: MCP servers run inside the gateway, not beside the brain. The gateway spawns them with the credential in its own process and publishes them to the brain over HTTP behind a per-server capability token. A prompt-injected brain can only ask, and every ask meets the policy and the guard.

The brain gets tools, never tokens.

What you get

Everything below is implemented and covered by the test suite; the Buzz path is also verified against a live relay.

| | What it does | Depth | |---|---|---| | Surfaces | Buzz (Nostr) and Slack, live and concurrent: threaded replies, reactions, typing indicators, DMs, and channel filtering. A cursor survives restarts, so a restarted agent catches up on what moved while it was away. | Guide ch. 2 | | Brains | A mock brain for free local work, or Claude driven over ACP. A refused reply comes back to the brain as a refusal it can adapt to mid-turn. | Guide ch. 1 | | Identity | A declarative profile, a style-independent character brief, and a generated avatar with an offline SVG fallback. Create a fresh Buzz signing key or adopt an existing one, then publish the same face to Buzz and Slack. | Guide ch. 1 | | Cross-surface posts | Ask the agent in Slack to post to a Buzz channel, or the reverse. Enabled by default, under the same channel guards as an ordinary reply. | Guide ch. 2 | | Memory | Local and explicitly scoped shared markdown vaults, optional age-encrypted *.md.age slices, encrypted private NIP-AE engrams on Buzz, and a read-only team brain over SageOx. | Below · Guide ch. 3 | | MCP tools | Any MCP server, credential held by the gateway, with the tool policy written for you from what the server reports. scope bounds the credential to the job — fail-closed, so a token that reaches an org reaches one repository. Every argument is leak-scanned on the way out. | Guide ch. 3 | | Repository context | Optional durable checkouts, background ox code indexing, and gateway-hosted read-only search and status tools. | Guide ch. 3 | | Scheduled jobs | Cron and event-driven work declared in agent.yaml beside the surfaces it shares an identity with. The toolkit owns the envelope, never the body: a kill switch with a declared fail-direction and a declared list of the agents that may park it — a human always may — single-flight per slug, a wall-clock budget under the platform deadline, and a run record for every tick — including the ones that never ran. | Contract · RFC | | Audit log | One tool_call line per MCP call, allowed and refused alike, from both places a call can be made. Arguments are recorded by declaration — a body shows up as <string 1300>, never as its text. | Guide ch. 5 | | Readiness | A cold index or an unreachable brain is a reading the agent discloses, not a reason it is not there to be asked. Only a precondition can refuse a launch; no capability health ever does. | Startup | | Hardening | Per-channel serialization, rate/thread/agent-chain caps, an author gate, a kill switch, and a per-turn timeout. | Guide ch. 5 | | Deployment | One deployment-neutral image, file-mounted secrets, a canonical Helm chart, and Terraform-managed AWS/EKS. | Contract · below |

Team memory over SageOx

An agent that has read what your team already decided stops asking your team to repeat it. The team brain gives the agent read-only search over your team's own recorded knowledge — indexed discussions, decisions, docs, plans, and assistant-chat sessions — through SageOx and its ox CLI:

| Tool | What it reaches | |---|---| | team_search | Indexed team knowledge, with passages and sources | | team_status | Checks team-search access and readiness of configured repository ledgers | | team_sessions | Bounded session listings for a configured repository with verified recent ledger sync | | team_recent | Recent coworker work updates and session activity from a verified fresh ledger |

Session listing and recent activity require a fresh local ledger. Configure optional gateway sync using an existing Git secret, or supply an externally supervised ox checkout and its refresh receipt. A successful search does not establish ledger availability or freshness.

It reads; it does not write. An agent that can write to team memory is an agent whose worst turn becomes a fact a colleague cites six months later. What the agent searches is what your teammates recorded by running ox in their own repositories — so the corpus grows from work people were doing anyway, not from a documentation chore.

Wiring it up

The team brain attaches to an agent, so create one first with ./bin/sageox-agent create.

1. Get an account and the CLI. Sign up at sageox.ai, then:

brew install sageox/tap/ox   # qualified: `ox` also exists in homebrew/core
ox login                     # for you, at the terminal — `ox teams` needs it
ox teams                     # the teams you belong to, with their IDs

Other install methods: ox install docs.

2. Create a personal access token at sageox.ai/settings/tokens — prefixed oxp_, shown once — and put it in the agent bundle's .env as SAGEOX_TOKEN.

The agent always authenticates with a PAT, on your workstation and in a container alike: the token takes precedence over anything on disk, so the manifest you test locally is the one you deploy. Never give the agent the token from your own ox login — that one expires within hours and cannot refresh itself once out of ox's hands.

3. Add the brain.

./bin/sageox-agent memory add team

Leave --team off and it lists your teams by name, resolves the ID once, and writes it into agent.yaml with the matching tool-policy entries — memory tools arrive namespaced (mcp__team-brain__team_search), and a policy that omits the prefix matches nothing.

brains:
  - preset: team
    team: team_xxxxxxxx     # the ID from `ox teams`, not the slug — a slug 403s
    token: SAGEOX_TOKEN     # a secretRef; the gateway resolves it, the brain never sees it

token names the secret, never the token itself, so a deployment supplies it through whatever already holds its secrets. doctor checks the token with SageOx and reports its rolling expiry.

The rest is in the team brain's credential and Guide ch. 3.

Deploying a fleet

Several agents, one versioned runtime image, ordinary Compose:

export AGENT_IMAGE=ghcr.io/sageox/agent-base@sha256:<digest>
export AGENT_UID=$(id -u)
export AGENT_GID=$(id -g)
export HARRY_BUNDLE=~/.config/agent-toolkit/agents/harry
export HARRY_SECRETS=/srv/agent-secrets/harry
export IDA_BUNDLE=~/.config/agent-toolkit/agents/ida
export IDA_SECRETS=/srv/agent-secrets/ida

docker compose -f deploy/docker/compose.yaml up -d

Each release records the digest to paste there — take the newest from Releases. Pin the digest rather than a tag: :latest and :0.1 move, @sha256:… does not.

The Helm chart likewise takes multiple agents in one release, using native Secret and PVC references and taking each bundle's source as a Kubernetes volume — and can be consumed as a subchart. Past about three agents, read fleets and the mayor before adding the fourth.

Status

Pre-1.0. The surfaces, guard, memory, MCP, job, and deploy paths listed above work and are tested. Configuration format and CLI flags may still move between minor versions; the CHANGELOG records every change and the releases publish a pinnable image digest.

Not built yet:

• A separate-container tier.