The Humagen spec¶
Humagen is configured in one language: versioned YAML documents (JSON works too) of two kinds, each with one owner.
| Kind | Says | Owned by | Takes effect |
|---|---|---|---|
System |
how and where Humagen runs: listeners, sign-in, stores, bus, files, limits, extensions | whoever runs the process: a laptop, compose, Helm values | at start |
Platform |
what one workspace offers: its models, tools, agents, Slack and GitHub, settings | that workspace's admins | at start, with the console building on it |
Both can live in one humagen.yaml, separated by ---, or in separate files.
Two commands use it. humagen start runs the platform here; humagen deploy runs it
where the System document's deploy slot says (here, a Docker Compose project,
or a Kubernetes cluster). Both read -f PATH (repeatable; a directory reads its
*.yaml, *.yml and *.json). With no -f they read humagen.yaml from
HUMAGEN_HOME, else the user config directory, and humagen start runs on defaults,
with example agents, if there is none. humagen setup writes one by asking a few
questions.
humagen serve is the command for a server: what the image, the chart and the
compose project run. It reads only the files -f names, seeds nothing, never
asks, and signs in with oidc unless a flag or a System document says
otherwise. A System document sets sign-in like any other field, so one that
leaves auth out is dev, which answers only on loopback; Platform documents
alone leave serve on oidc.
Four rules hold for every field:
- Every field has a working default. No file is a running platform on a laptop: development sign-in on loopback, memory stores, files on disk.
- A secret is a reference, never a value. A credential is written
{ref: env:NAME},{ref: keychain:SERVICE/ACCOUNT}or{ref: op://VAULT/ITEM/FIELD}, read when it is used and never stored. A bare string where a secret belongs is refused.env:HUMAGEN_XreadsHUMAGEN_X, else the old nameWARP_X, andenv:WARP_X(the old prefix) reads the same variable (upgrading-from-warp.md). - Every replaceable part is a slot:
kindplus a block named after it.kind: postgresreadspostgres: {...}. A program built on thehumagenpackage registers more kinds (humagen.WithKind), and the file selects one by name with no other change. An unknown kind is an error listing the kinds the binary has. A choice is a file or an interface, never a fork. - Unknown fields are errors, with the document and path they are in.
Flags still work and win over the file, so humagen start -addr 127.0.0.1:9090
needs no edit. humagen config check -f humagen.yaml validates without starting and
lists every env: reference the shell it runs in has not set; humagen config
print writes the result with every default filled in.
System¶
api_version: humagen/v1
kind: System
metadata:
name: humagen # the deployment's identifier
display_name: Humagen # what people see: console title, Slack app name
spec:
server:
addr: 127.0.0.1:8080
public_url: http://localhost:8080
webhook_addr: "" # a second listener that serves only signed webhooks
console: {enabled: true, dir: auto} # auto finds a built apps/web
drain_grace: 25s # after SIGTERM, how long runs in flight may finish before they are handed back
shutdown_timeout: 10s # then how long open requests and event streams may take to end
role: all # all | api | worker: which parts this process runs (Process roles)
replicas: 1 # how many server processes the deployment runs; more than 1 is refused on the memory bus (Process roles)
auth: # slot: dev | tailscale | oidc | mock
kind: oidc
oidc:
issuer: https://login.example.com
client_id: humagen
client_secret: {ref: env:HUMAGEN_OIDC_CLIENT_SECRET}
audience: humagen
tenant: {fixed: default} # or {claim: org}
groups: {claim: groups, roles: {admin: [platform-admins], operator: [staff]}} # admin, manager, operator, viewer
policy_file: "" # an authorization policy (docs/architecture/security.md)
stores: # slot: memory | postgres. Every store family
kind: postgres
postgres: {url: {ref: env:HUMAGEN_POSTGRES_URL}}
bus: # slot: memory | postgres. Leave it out and it
kind: postgres # follows the stores: postgres on Postgres stores
blobs: # slot: disk | memory | s3 | gcs. Published files and
# memory's content. With memory, memory's content
# is kept with the stores instead
kind: s3
s3:
bucket: humagen-files
region: us-east-1
endpoint: "" # MinIO: http://127.0.0.1:9000 with path_style; R2: https://ACCOUNT.r2.cloudflarestorage.com, region auto
prefix: ""
path_style: false
access_key: {ref: env:HUMAGEN_S3_ACCESS_KEY_ID} # both left out: the AWS chain
secret_key: {ref: env:HUMAGEN_S3_SECRET_ACCESS_KEY}
# Google Cloud Storage, keyless: Application Default Credentials, which are
# Workload Identity on GKE, GOOGLE_APPLICATION_CREDENTIALS, or gcloud's.
# kind: gcs
# gcs:
# bucket: humagen-files
# prefix: ""
# endpoint: "" # an emulator's URL, such as http://127.0.0.1:4443, reached without credentials
# Google Cloud Storage through its S3-compatible API, with an HMAC key:
# kind: s3
# s3:
# bucket: humagen-files
# endpoint: https://storage.googleapis.com
# region: auto
# path_style: true
# access_key: {ref: env:HUMAGEN_S3_ACCESS_KEY_ID} # the HMAC key's access ID
# secret_key: {ref: env:HUMAGEN_S3_SECRET_ACCESS_KEY} # and its secret
knowledge:
embedder: # slot: none | hashing | openai | vertex. Left out: none, lexical search only
kind: vertex
vertex: {project: my-gcp-project, location: us-central1} # model gemini-embedding-001 and 768 dimensions by default
# kind: openai
# openai: {base_url: "http://127.0.0.1:11434/v1", model: nomic-embed-text, dimensions: 768, key: {ref: env:EMBEDDINGS_KEY}}
# kind: hashing
# hashing: {dimensions: 256} # no model: matches words and word stems, not meaning
speech: # slot: none | groq | openai. Left out: none, a voice note stays an attachment no agent hears
kind: groq # transcribes voice notes before a run starts (Voice notes)
groq:
key: {ref: env:GROQ_API_KEY} # the default; left out, the same
model: whisper-large-v3-turbo # the default
max_bytes: 26214400 # 25 MiB, the default and Groq's own cap; at most 100 MiB
timeout: 60s # one request; the default, at most 10m
execution:
workspace: "" # agents' files. Empty is the user cache directory
concurrency: 4 # a run that calls another agent waits in one place while it runs in another
max_depth: 4 # 1 to 7: a deeper call would pass the bus's hop limit of 8
max_fan_out: 16
# There is no built-in model or offline stand-in. The platform's own agents
# (writer, analyst, builder, reviewers) ship with a chain, anthropic then
# openai then google, and run on the first one a declared or
# administrator-enabled provider answers. execution.builtin is no longer
# read: a file that sets it still starts, with a load note.
sandbox: # slot: docker | local | unisolated. Where a run's tools execute
kind: docker # the default: an instance per run, destroyed when the run ends
docker:
runtime: runsc # gVisor, the default; runc shares the host's kernel and is for trusted tools
insecure_development_runtime: false # true accepts runc; without it runc is refused
image: python:3.13-alpine # the shell and the file tools; needs sh and sleep
connectors_image: node:22-alpine # stdio MCP servers; empty is image
work_root: "" # empty is humagen/sandbox in the user cache directory
host: "" # a sandbox host's daemon: tcp://, ssh:// or unix://. Empty is the local daemon
tls_dir: "" # with a tcp:// host: ca.pem, cert.pem and key.pem
warm: 1 # instances kept started ahead of runs, per shape
max: 64 # every instance at once
egress: # slot: none | gate. How an instance reaches the network
kind: gate # none, the default: no network at all
gate:
listen: 10.0.9.2:3128 # where the gate listens; empty is 127.0.0.1:3128
address: 10.0.9.2:3128 # the gate as an instance reaches it; empty is listen
network: humagen-egress # docker: the --internal network instances join
allow_non_public: false # true lets an allowed host resolve to a private address
rooms: # a conversation with many readers (RFC 0004); each default is far above an ordinary one
coalesce_above: 200 # readers on one server above which each is sent at once only what involves them, the rest as a page
tail_interval: 3s # how often a large conversation's page is sent: 500ms to 1m
max_runs_per_minute: 600 # runs one conversation starts in any minute
max_runs_per_person: 25 # runs one person has in flight at once
secret_env: # variables a workspace's clients may reference, by tenant
default: [HUMAGEN_SLACK_TOKEN]
person_refs: # where each workspace's people may keep their own tool credentials, by tenant
default: ["env:HUMAGEN_PERSON_{subject}_"] # how their references may start, {subject} being the person's; none listed is none
# deploy local (this machine) may also list "op://People/{subject}/" and "keychain:humagen-people-{subject}/"
branding: # the console's look and name; see Branding below
name: Acme # the product's name. Left out: metadata.display_name
entry_agent: humagen # the default: the agent people talk to the deployment through, owning each root session that names nobody. System document only
logo: {path: ./brand/logo.svg, dark: ./brand/logo-dark.svg, alt: Acme}
icons: ./brand/icons # favicon.svg, icon-192.png and the rest, by the console's own names
manifest: {short_name: Acme, theme_color: "#1a1a2e", background_color: "#fafafa"}
palette:
accent: {light: "#c2185b", dark: "#f06292"}
surface: {light: "#fafafa", dark: "#1a1a2e"}
text: {light: "#1a1a2e", dark: "#fafafa"}
fonts:
ui: "Inter, sans-serif"
heading: "Georgia, serif"
files: [{family: Inter, path: ./brand/InterVariable.woff2, weight: "100 900"}] # served for the lists to name
email: {subject: "{name} updates", multiple: "{count} updates wait for you in {name}."}
notifications: # optional outbound delivery; people must also opt in
email:
address: smtp.example.test:587
from: Humagen <notifications@example.test>
username: notifications
password: {ref: env:HUMAGEN_SMTP_PASSWORD}
tls: starttls # default; implicit also requires verified TLS
recipients:
default:
"issuer|person-subject": person@example.test
extensions: [] # process-wide parts a binary registered, each a slot
deploy: # slot: local | compose | kubernetes. Read by humagen deploy
kind: compose
compose:
image: "" # empty builds one from `build`, a humagen checkout
postgres: true # run Postgres beside humagen and point the stores at it
port: 8080
# kind: kubernetes
# kubernetes: {context: prod, namespace: humagen, host: humagen.example.com, image: {repository: ghcr.io/urmzd/humagen, tag: v0.10.0}}
Email recipient mappings use the exact authenticated tenant and subject. Delivery
checks current standing permissions and preferences. It sends a readable update
count and an inbox link, with event kinds and email off by default. The explicit
insecure_loopback TLS mode accepts only literal loopback addresses without
credentials. See Email notifications for quiet hours,
retry behavior and consent records.
Sandbox¶
Every run's tools execute in an instance of the run's own (RFC 0004): the
file tools work in its work directory, the shell tool runs there, and stdio
MCP servers run in its connectors compartment, which holds their credentials
where code in the workload cannot read them. The agent loop and the model
keys stay in the server. An instance is leased on a run's first tool, never
shared with another run (a run another agent calls gets its own), and
destroyed when the run ends, however it ends. Its work directory starts from
the conversation's files and is written back to them at the end, so a
follow-up turn sees what the last one wrote.
sandbox.kind |
Where tools run | Use |
|---|---|---|
docker (default) |
Containers with no network, a read-only root, no capabilities, a non-root user, a seccomp profile stricter than Docker's default and resource limits, on runtime: runsc (gVisor) unless it says runc with insecure_development_runtime: true |
Production |
local |
Host processes, with the server's privileges, in a directory laid out like an instance. The shell works | Development without Docker |
unisolated |
This host, as before the sandbox: files in the conversation's directory, stdio servers as host processes. The shell is refused | Development and tests |
The server says at start which one it runs. local and unisolated are
never chosen for you: name them in the spec or with -sandbox. The Docker
daemon must have runsc registered for the default. runc shares the host's
kernel, so a kernel bug is a way out of every instance: it is refused unless
insecure_development_runtime (or -sandbox-insecure-development-runtime)
is set, and then the server warns at start. humagen start, the make dev
targets and the Tilt stack use docker with runc, the runtime Docker has
on a developer's machine, and set it for you. A docker sandbox whose CLI is
missing, or whose runtime is refused, does not stop the server: it logs why,
and every tool that needs an instance refuses with that reason; nothing falls
back to the host. A server in a
container needs the Docker CLI and a daemon it may use (a mounted socket) to
run tools. Giving Humagen the Docker socket is root on that host:
whoever can start containers through it can mount the host's filesystem. So
the docker driver is for a host that exists to run sandboxes, not a shared
server or a Kubernetes node; the chart and the compose stack set
unisolated explicitly for that reason.
host points the docker sandbox at a daemon on a sandbox host instead,
so Humagen holds no Docker socket on its own machine: whoever takes over
Humagen gets the sandbox host, not the one with the database. A tcp://
host needs tls_dir, the directory with the daemon's certificate authority
(ca.pem) and Humagen's client certificate (cert.pem, key.pem); a
daemon on plain TCP is refused, because it is root for anyone who reaches
the port. With a host, a run's work directory is a volume on the sandbox
host, work_root is unused, and host directories cannot be mounted. The
sandbox host needs Docker with runsc registered and nothing else worth
taking. An instance has no network at all unless the
egress slot is gate (Egress).
Flags override the block: -sandbox, -sandbox-runtime,
-sandbox-insecure-development-runtime, -sandbox-image,
-sandbox-connectors-image, -sandbox-work-root, -sandbox-host and
-sandbox-tls-dir. A binary can register
another kind with humagen.WithKind(humagen.Sandbox, name, factory), whose
factory returns an isolation.Leaser (saige/flow/isolation).
Egress¶
egress decides how a sandbox instance reaches the network. Left out, it is
none: an instance has a loopback interface and nothing else, so a tool that
calls an API cannot reach it.
gate runs playscape's egress gate in the server: an HTTP forward proxy that
is every instance's only way out. Each run's instance is granted the hosts its
ceilings.egress allows (Run settings), default deny, and
every command in it, the shell and stdio MCP servers alike, gets HTTP_PROXY
and HTTPS_PROXY with that grant's token. A request for any other host gets
403 before anything is dialed. HTTPS goes through as a CONNECT tunnel, so
the gate sees the host and port, never the content. The grant ends when the
run's instance is destroyed. Addresses that are loopback, private or
link-local are refused whatever name led to them, unless
allow_non_public is set.
Every decision, allowed or denied, is written to the workspace's audit log as
sandbox.egress on resource egress_host, with the run, its agent and
conversation, the method, host and port, and why a request was refused. A
denied request is a failed record.
| Sandbox | What forces the gate |
|---|---|
docker |
The instance joins network, which must be created with --internal (docker network create --internal humagen-egress), so it has no route out. The gate must be reachable on that network at address: run the server in a container attached to it, and give the server's IP address on it, since gVisor cannot always resolve names there. A network that is not internal is refused |
local |
Nothing: the processes are the server's own, and only the proxy variables send them to the gate. listen and address on loopback are enough |
unisolated |
Nothing runs in an instance, so the gate is not started and the server says so |
Credential injection, where the sandbox holds a placeholder and the gate swaps in the real value for an allowed host, is playscape's and not wired here yet.
Web search and fetch¶
An agent whose tools name web_search or web_fetch reads the public web.
Neither needs an account, a key or a setting. The built-in writer and analyst
have both.
| Tool | What it does | Bounds |
|---|---|---|
web_search |
Searches the web and returns titles, addresses and snippets | 10 results, a query of at most 400 characters |
web_fetch |
Reads one http or https address as text: HTML as a reader sees it, plain text and JSON as they are |
2 MiB read, 40,000 characters returned, 5 redirects, 20 seconds. Content that is not text, such as a PDF or an image, is refused |
Both go out from the server, not from the run's sandbox, which has no
network, so the egress allowlist does not apply to them. They
reach only addresses on the public internet: a loopback, private or
link-local address is refused when the connection is made, after the name is
resolved, so a name or a redirect that points inward is refused too. No proxy
is used. Both are read_context actions, held by the same action policy as
other reads.
The search is DuckDuckGo's page for clients without scripts. It may refuse a server it takes for a program; the tool then says so and returns nothing. A page is evidence, not an instruction: every result says so, and an agent that reads a page can still be misled by it, including into fetching an address that carries what it knows. Give these tools to agents whose other reads you would accept on the public web.
Knowledge search¶
knowledge.embedder turns on hybrid search for knowledge sources
(RFC 0005). Each passage
gets a vector, computed in the background after it is added, so an upload never
waits on a model. Search then ranks passages both by vector similarity and with
BM25, and fuses the two lists by reciprocal rank fusion. It finds passages that
share no word with the query and still puts an exact identifier first.
| Kind | Block | Credentials |
|---|---|---|
none |
none | Lexical only, the default |
hashing |
dimensions (256 when left out) |
None: deterministic, no network. Matches word stems, not meaning |
openai |
base_url, model, dimensions (required), key |
key, a reference, for any OpenAI-compatible /embeddings endpoint |
vertex |
project (required), location, model, dimensions |
Application Default Credentials: the VM's service account on GCE, gcloud credentials locally |
Vectors are stored beside the passages and read back at start. Changing the model or its dimensions computes them again; until then those passages rank lexically. If the embedder fails, writes still succeed and search is lexical. Search sees exactly the documents it would without vectors: the same sources, exclusions, variants and access checks.
Voice notes¶
speech turns a voice note into words before the run it starts, so an
agent reads what was said wherever it was said. A message that carries an
audio attachment (a Slack audio clip, and the WhatsApp and iMessage voice
notes the messaging connectors will carry) is transcribed as it is posted,
and the transcript is put after the message's text, marked
[Voice note, english]. The recording stays attached. In the console, the
microphone records a voice note and its words come back into the draft,
marked the same way, for the person to read and send
(docs/guides/voice.md).
| Kind | Block | Credentials |
|---|---|---|
none |
none | Nothing is transcribed, the default |
groq |
base_url, key, model, speech_model, voice, max_bytes, timeout, every one optional |
key, a reference, env:GROQ_API_KEY when left out |
openai |
The same block as groq |
key, a reference, env:OPENAI_API_KEY when left out |
groq sends each recording to POST /audio/transcriptions on Groq's
OpenAI-compatible API, with whisper-large-v3-turbo unless model says
otherwise. A recording over max_bytes (25 MiB when left out, at most
100 MiB) is not sent, and one request waits at most timeout (60s, at most
10m). A message has at most four voice notes transcribed. A note that is too
long, has no words or reaches a provider that fails is said to be so in the
message, which still posts. speech_model and voice (Groq's
canopylabs/orpheus-v1-english and autumn when left out) are for speaking
replies. openai is the same API on OpenAI's, with whisper-1, tts-1 and
alloy when left out. A binary adds a kind with
humagen.WithKind(humagen.Speech, ...), building a speech.Transcriber.
This slot is the deployment's, and the deployment pays for it. A workspace admin can set up a voice provider of the workspace's own in Workspace settings, which is used before this slot, turns voice mode on, and counts what each call costs in the workspace's usage (docs/guides/voice.md).
A model can be Groq too: kind: groq under models is openai with Groq's
base URL and env:GROQ_API_KEY filled in, and an agent names it as its
provider with a model such as llama-3.3-70b-versatile.
Catalog connectors¶
connectors in a Platform document are the systems the catalog lists
(RFC 0005): tables,
columns and their descriptions, never data. Each is crawled on its refresh
cadence (24h when left out), and a crawl replaces its entries whole, so a
dropped table disappears and a failed crawl keeps the entries before it.
Entries are searched like knowledge, with knowledge.embedder when one is set.
| Field | Meaning |
|---|---|
owner |
The person whose credential the connector uses. Required. They see its entries, may publish them, and may query it |
project |
Whose members see its entries while the owner publishes them (POST /api/catalog/connectors/{name}/publish). Left out, the workspace |
refresh |
How often it is crawled, at least 1h |
| Kind | Block | Credentials |
|---|---|---|
snowflake |
account, database, warehouse, role (all required), max_rows (200, at most 10000), timeout (60s, 1s to 10m) |
credential, a required reference to an OAuth token. The role must have USAGE and SELECT grants only |
gcs |
bucket (required), prefix (empty lists the bucket) |
credential, a required reference to service account JSON |
s3 |
bucket (required), prefix, region (us-east-1) |
credential, a required reference to JSON with access_key_id, secret_access_key, and optional session_token |
bigquery |
project (required), datasets, location, max_bytes_billed (1 GiB), max_rows (200, at most 10000), timeout (60s, at most 10m) |
credential, a reference to a service account key in JSON; left out, Application Default Credentials: the VM's service account on GCE |
Five tools use the catalog and corpora, granted to an agent by name like any tool:
catalog_searchfinds entries: a published connector's when everyone the answer reaches reads its project, and the owner's own only in the owner's private conversation.catalog_queryruns one SQLSELECTwith the connector's credential, so only for its owner, in their own private conversation. BigQuery dry-runs it first and refuses it before it runs when it is not a singleSELECT, reads a dataset outsidedatasets, or would read more thanmax_bytes_billed. The query that runs carries the same cap as BigQuery's maximum bytes billed.corpus_queryruns one SQLSELECTon a Snowflake or BigQuery connector a corpus holds, with the login of the person the run acts for, never the connector's credential, so the warehouse's own grants, row access and masking apply. It runs only in a direct conversation (the person's own private one, or their DM with the app), for a reader of the corpus, and only for an agent the corpus is granted to (sources.md). Snowflake leaves the connector's role out, so each reader's default role applies.corpus_searchsearches the corpora granted to the agent: files by words and meaning, references live, warehouse tables by what they hold. It uses only what everyone the answer reaches may read, checked when it runs, and says what it held back (sources.md).corpus_graphreads the workspace graph of the corpora granted to the agent: documents, tables and systems, who owns each and how stale each is, by the same rules ascorpus_search.
The credential needs roles/bigquery.metadataViewer (or dataViewer) on the
datasets to crawl them, roles/bigquery.dataViewer to read them, and
roles/bigquery.jobUser on project to run queries. Give it no write role:
the dry run's statement check is the first guard, the credential the last.
Rooms¶
rooms protects the server from a conversation with a great many readers
(RFC 0004, "A million people in one room"). A conversation's stream
(GET /api/events?thread=<id>) is sent every event as it happens while the
conversation has at most coalesce_above readers on the server. Past that,
each reader is sent at once only the messages they posted or are named in,
the runs they asked for and the questions put to them, and the rest as one
page every tail_interval, which says how much happened; the console then
reads the conversation's newest turns. What one server delivers each second
is then bounded by the events that involve someone plus the readers divided
by the interval, whatever the conversation's message rate.
max_runs_per_minute and max_runs_per_person are admission limits beside
a workspace's policies: a run past either is refused with 429 and a
Refusal whose limit is room_rate or person_runs, and a tag in a
message past them is refused in the message's refused. Only a run a person
or a surface started counts: a call between agents is its root's work, and a
schedule's or an eval's run is asked by nobody. With stores.kind: postgres
the counts are shared by every replica.
Stopping and readiness¶
GET /healthz says the process is alive. GET /readyz says it should be
sent traffic: 200 once it has finished starting, while its database (with
stores.kind: postgres) answers, and until it starts to stop; 503 with the
reason (starting, draining or unavailable, and which check failed)
otherwise. Point a load balancer's or Kubernetes' readiness probe at
/readyz and its liveness probe at /healthz.
On SIGTERM (or the first Ctrl-C) the server drains:
/readyzanswers 503draining, so traffic moves to another replica.- A new turn is refused with 503 and
Retry-After. The worker claims no new run, except one that a run it holds called, so a turn waiting on its subagent can still finish. - Runs in flight go on for up to
server.drain_grace. - Open requests and event streams get
server.shutdown_timeoutto end. - Whatever is still running is handed back to the queue without being charged a failure. With Postgres stores, another replica resumes it where it stopped; with memory stores it is lost with the process.
A second signal skips the wait. Give a container longer than
drain_grace plus shutdown_timeout to stop (Kubernetes'
terminationGracePeriodSeconds), or it is killed mid-drain. Flags
-drain-grace and -shutdown-timeout win over the file.
Process roles¶
server.role (or -role) says which parts of the platform a process runs,
so the API and the execution of turns scale on their own (RFC 0004, "A
million people in one room").
| Role | Runs | Listens |
|---|---|---|
all (the default) |
the API and the turns, in one process | server.addr, and webhook_addr when set |
api |
the API, sign-in, the event stream and webhooks; it admits runs onto the queue and executes none | as all |
worker |
the turns on the run queue (anchor's worker) and what they need: models, tools, the sandbox | nothing |
humagen worker is humagen serve with the worker role, whatever the
file's server.role says; a different -role on its command line is
refused. api and worker hand runs to each other through the run ledger
and queue, so both need stores.kind: postgres, and a split role on memory
stores is refused at start.
server.replicas (or -replicas) declares how many server processes the
deployment runs, 1 when left out. Humagen does not count its replicas; the
number is what the operator says. More than one on the in-memory bus is
refused, by humagen config check and at start, because each process has
its own in-memory bus and would miss the other's events: set
stores.kind: postgres and leave bus out (or bus.kind: postgres), or
set server.replicas: 1. The Helm chart refuses the same combination from
replicaCount and autoscaling.maxReplicas.
humagen serve -f humagen.yaml -role api # behind the load balancer
humagen worker -f humagen.yaml # as many as the queue needs
Whatever its role, every process on one database campaigns for leadership,
and only the leader runs the work done once per deployment: the reconciler,
schedules, inbox retention, email notices, knowledge source refresh and
catalog crawls. The leader holds a session advisory lock on a connection of
its own; when that connection ends, the lock goes with it and another process
takes over within about ten seconds: it waits out the old leader's last check, so two terms never overlap while the old leader can still reach the database. On memory stores the one process
always leads. Each process logs its role at start (msg=process role=...)
and logs platform: leading when it becomes the leader.
Today every store but feedback is still loaded into memory at start and the
stores' lock admits one process per database
(limits at scale), so a
deployment runs one process, with role: all, until the stores read the
database per request. The roles and the election are in place for that step.
Platform¶
One document per workspace. metadata.name is its tenant.
api_version: humagen/v1
kind: Platform
metadata:
name: default
display_name: Acme
spec:
workspace: # a field left out is left to the console
history: {mode: recent, limit: 8000}
agents: {default: "*"} # the workspace's own: each agent decides on untagged messages, anywhere
instructions: Acme sells warehouse robots. Answer plainly. # the workspace's own, sent first
channels: [{name: announcements, purpose: Company news}] # the workspace's own; every project has general
experts: [{who: "role:security", topics: [security]}] # answer anywhere a nearer project names nobody
knowledge: [handbook] # every run in the workspace is grounded in these sources, besides its agent's own
skills: # a message anywhere names one with $summarize, and the agents it starts use it
- {name: summarize, description: Summarize a thread in five bullets., instructions: "Summarize the conversation so far in five bullets, newest last."}
mention_kinds: # @oncall:sre notifies everyone holding sre, besides the built-in @sme: and @skill:
- {kind: oncall, title: On call, resolves: role}
members: [{who: "*", role: member}, {who: "role:comms", role: owner}] # the workspace's own
project_kinds: [{name: partner, title: Partner, like: account}] # the workspace's own kinds
agent_posts: review # what agents scheduled in the workspace itself post waits for its owners
run: # every run's settings: ceilings bound it, preferences choose within them
ceilings: {models: ["anthropic/*", "gemini/*"], call_depth: 2, tool_servers: [mcp.acme.example], egress: [api.github.com, "*.pypi.org"]}
preferences: {model: anthropic/claude-sonnet-4-5}
projects: # merged into the tree at every start, parents first
- {name: Launch, description: Everything for the Q4 launch}
- name: Field
title: Field engineering
kind: team # company | team | account | a project_kinds name. Left out: team
instructions: Customer accounts. Never promise dates.
knowledge: [field-playbook] # runs filed here and below are grounded in it too, nearest first
skills: # $review here and below; a nearer project's of the same name wins
- {name: review, description: Review a renewal., argument_hint: "[account]", instructions: Check the renewal terms against the contract and list what changed.}
members: [{who: "*", role: viewer}, {who: "role:field-eng", role: member}, {who: "role:field-leads", role: owner}]
agent_posts: publish # what its scheduled agents post goes out at once
run: # tightens the workspace's for runs filed here and below
ceilings: {tools: [file_read, file_list, "mcp:github"], call_depth: 1}
preferences: {compaction_tokens: 120000}
schedules: # the file's: filed here, paused and run in the console, changed only here
- {name: field-recap, cron: "41 8 * * 1", agent: humagen-analyst, text: "What changed in Field this week?", deliver: project}
- name: Globex
parent: Field # a project in this file. Left out: the top level
kind: account
account: {customer: Globex Inc, external_id: "sf:0015g00000ABC", url: "https://crm.example.com/globex"}
channels:
- {name: renewals, purpose: Renewal work}
- {name: general, slack: {client: slack-acme, channel: C0123GLOBEX}} # a Slack thread there is a shared thread here
experts: [{who: "okta|00u1ana", topics: [billing, renewals]}]
agents: {allow: [globex-helper, lead]} # narrows: only these run here and below
members: [{who: "okta|00u1ana", role: owner}] # no "*": members only, read by its members alone
person_credentials: {values: false} # true lets people store a tool credential's value with humagen
release_notes: true # each release's breaking changes and features, posted once in the workspace's inbox from humagen
inbox_retention: 180d # how long the inbox keeps what was settled for everyone. Left out: 90d. At least 7d
models: # each a slot: anthropic | openai | google | groq
- name: anthropic # what an agent names as its provider
kind: anthropic
anthropic: {key: {ref: env:ANTHROPIC_API_KEY}}
- name: gemini
kind: google # Gemini; vertex: {project: P, location: us-central1} for Vertex AI
google: {key: {ref: env:GOOGLE_API_KEY}}
- name: local
kind: openai # any OpenAI-compatible server, such as Ollama (http://127.0.0.1:11434/v1) or vLLM
openai: {base_url: "http://127.0.0.1:8000/v1"}
- name: groq
kind: groq # openai on Groq: base_url https://api.groq.com/openai/v1 and key {ref: env:GROQ_API_KEY} by default
model_policies:
- name: default
models: [{provider: anthropic, model: YOUR_MODEL}, {provider: local, model: YOUR_LOCAL_MODEL}]
fallback_on: [unavailable, rate_limit]
tools: # each a slot: mcp
- name: docs # granted to an agent as mcp:docs or mcp:docs:write
kind: mcp
mcp:
transport: http
endpoint: https://mcp.example.com
credential: {ref: env:DOCS_MCP_TOKEN}
accept: # pinned by schema hash; new or changed tools stay pending
- {name: search, schema_hash: 9f2c4e, class: read}
- name: issues # granted as mcp:issues; each person reaches it as themselves
kind: mcp
mcp:
transport: http
endpoint: https://issues.example.com/mcp
credential_scope: person # shared (the default) or person. A person-scoped tool names no credential
accept: # not reached at start, so each tool carries the form its server offers
- name: search
description: Search issues
input_schema: {type: object, properties: {q: {type: string}}}
schema_hash: 21877437383c4aa0e8fc28bbe3abc1d801bac704010bcdd62a93e30dafd20ab6
class: read
connectors: # each a slot: bigquery. What the catalog lists, and agents query in place
- name: warehouse
kind: bigquery
owner: ana@acme.example # whose credential it is: they see its entries and may query it
project: Field # whose members see its entries once the owner publishes them
refresh: 24h # how often it is crawled, at least 1h
bigquery:
project: acme-analytics
datasets: [billing, web] # the catalog and every query keep to these
max_bytes_billed: 1073741824 # one query reads at most this; refused before it runs otherwise
max_rows: 200
# credential: {ref: env:BQ_KEY} # a service account key; left out, the VM's service account
agents:
- spec:
name: lead
provider: anthropic # a model, never a nickname: the chain is the agent's own
model: claude-sonnet-5-5
fallbacks: [{provider: openai, model: gpt-5.1}]
system_prompt: You coordinate work.
access: {spawn: [helper]}
- spec: {name: helper, provider: local, model: YOUR_LOCAL_MODEL, system_prompt: Do one task well.}
- project: Globex # its home: only Globex's readers see it, and it answers only where they alone read
spec: {name: globex-helper, provider: local, model: YOUR_LOCAL_MODEL, system_prompt: You know the Globex account.}
- file: agents/reviewer.agent.md # saige's own format; a .json or .yaml file holds a spec instead
policy: {answerers: ["role:field-leads"], tagged_only: true} # what the .agent.md does not say
surfaces:
slack: # humagen runs the Slack app as its client, over Socket Mode
enabled: true
team: T0123456
bot_token: {ref: env:SLACK_BOT_TOKEN}
app_token: {ref: env:SLACK_APP_TOKEN}
operators: [U0123456]
command: /agent # `humagen slack manifest -f humagen.yaml` writes the app's manifest
description: Acme's agents in Slack # the manifest's; each left out is Humagen's
background_color: "#1a1a2e"
command_description: Ask Acme's agents
command_usage_hint: "[question]"
humagen_client: # how the app signs in to humagen's API. Dev sign-in needs none
token_url: https://login.example.com/oauth2/v1/token
client_id: humagen-slack
client_secret: {ref: env:HUMAGEN_SLACK_CLIENT_SECRET}
scopes: [humagen:agents:read, humagen:runs:read, humagen:runs:write, humagen:billing:read, humagen:projects:read]
audience: "" # set when the provider needs one named
# humagen_token: {ref: env:HUMAGEN_SLACK_API_TOKEN} # instead: a bearer token that does not expire
github:
enabled: false
owners: [acme]
token: {ref: env:HUMAGEN_GITHUB_TOKEN}
webhook_secret: {ref: env:HUMAGEN_GITHUB_WEBHOOK_SECRET}
login: humagen[bot] # the app's own login; see github.md, "Who a comment asks"
branding: # this workspace's, over the System document's, once its people sign in
wordmark: Acme Field
palette: {accent: "#2e9e8f"} # one color is both themes'
welcome: {title: "Welcome to {name}", text: Ask the field team anything. Your drafts stay private until you share them.}
starters: # replace the suggestions on an empty conversation; [] shows none
- {agent: lead, label: Plan the week, text: "Plan this week's customer visits for "}
copy: # the console's own text, by key: humagen config copy-keys lists them
navigation.projects: Accounts
Branding¶
branding is how the console looks and what it calls itself. Everything left
out is Humagen's own. The System document's is the deployment's, and it alone
covers what is served before anyone signs in; a Platform document's is that
workspace's, field by field over the deployment's, applied once a person of
the workspace signs in.
| Field | What it changes | Where |
|---|---|---|
name |
The product's name: the tab title, the sidebar's wordmark and the installed app's name, unless each is set itself. Left out, metadata.display_name |
both |
title |
What follows the page's own name in the browser tab, after · |
both |
wordmark |
The text beside the logo in the sidebar. "" shows the logo alone |
both |
logo |
{path, dark, alt}: an .svg, .png, .webp or .jpg of at most 512 KiB in place of Humagen's mark. dark is the same kind of file drawn in the dark theme; left out, path is drawn in both |
both |
icons |
A directory of files that replace the console's icons by name: favicon.svg, favicon-32.png, apple-touch-icon.png, icon.svg, icon-192.png, icon-512.png. favicon-dark.svg and favicon-dark-32.png are added for the tab while the device is in its dark theme; an SVG favicon may instead carry its own prefers-color-scheme style. One it lacks stays Humagen's; any other name is an error |
System |
manifest |
The installable app's name, short_name, description, theme_color and background_color |
System |
palette |
accent, surface (the page), plane (the sidebar and panels), text and rule (lines), each {light, dark} or one color for both themes |
both |
fonts |
CSS font-family lists for ui, heading and mono text, and files: up to 12 {family, path, weight, style} faces (.woff2, .woff, .ttf or .otf, at most 2 MiB each) the server serves for those lists to name. A face named without a file must be installed on the device. A workspace's files replace the deployment's |
both |
entry_agent |
The agent people talk to the deployment through, humagen when left out: lowercase kebab case. It owns each root session that names nobody, answers simple asks and calls specialists as child sessions (docs/architecture/projects.md#the-entry-agent). The GitHub check run is named for it by name |
System |
welcome |
{title, text} of the announcement a workspace's people find first in its inbox. Left out, Humagen's, with the product's name in place of Humagen. It is posted once, so a change reaches only a workspace not yet welcomed |
both |
starters |
Up to 6 {agent, label, text} suggestions on an empty conversation, each shown only where its agent can answer. [] shows none |
both |
copy |
The console's own text by key, such as navigation.agents: Assistants. humagen config copy-keys lists the keys; an unknown one is an error. A workspace's keys are merged over the deployment's |
both |
email |
What notification emails say: subject, single (one update), multiple (with {count}) and footer. {name} is the product's name in each. Left out, Humagen's under the product's name |
both |
Colors are hex, #rgb or #rrggbb. Text must reach 4.5:1 on its surface and
the accent 3:1 in each theme (WCAG AA), against Humagen's own for a side left
out; a workspace's palette is checked over the deployment's. The product's own messages in the inbox are shown from its name. The accent is
the console's default: a person still picks their own under Settings, where
Workspace returns to it. Paths are read at start, from the working directory,
like agents[].file, so a missing file, an SVG carrying a script, or an icon
under a name the console does not have fails the start rather than a page.
The server writes the deployment's name, theme color and stylesheet into the
console's page and manifest as it serves them, so nothing is rebuilt and the
checkout stays clean. A workspace's reaches the console through
GET /api/branding.
Some of a workspace's identity lives outside Humagen. A Slack app's icon and
its bot's picture are set on the app's page at api.slack.com: Slack's
manifest has no field for them. A GitHub App's name and avatar are its
registration's on GitHub, and every review comment and check run carries
them; surfaces.github.login only tells Humagen what that login is.
What the file owns¶
A Platform document is applied at every start, and is the floor the console builds on:
- Agents in the file are created, or revised to the file's spec. An
unchanged spec makes no new revision. An edit made in the console to an agent
the file declares lasts until the next start.
autoandsmeare reserved, so never an agent's name (humagen config checkrefuses one written inline, the start one read from a file), and a new agent named like a handle a person in the workspace goes by fails the start with "a person goes by @dana", as the API answers 409. - Workspace fields that are set are applied; fields left out stay as the console left them.
- Projects in the file are created, or taken over when the console made
one by that name, parents first, and are managed by the file. A field the
file sets is the file's, and the console cannot change it (409); a field
it leaves out stays the console's.
workspace.instructionsare the workspace's own in the same way. An unchanged entry makes no new version. A project made in the console survives every start, and one that leaves the file stays, no longer managed, so it can be changed or deleted in the console again. A project's channels and experts are the file's in the same way: a channel the file declares is created or taken over, and one that leaves it stays, unmanaged; experts the file sets, even as[], are the file's, and experts it leaves out stay the console's. The knowledge sources a project or the workspace names, and the skills it declares, are the same: the file's when it sets them, even as[], and the console's when it leaves them out. A project's schedules are the file's whole: created, or taken over when the console made one by that name, filed in the project; the console can pause, resume and run one, not change or delete it (409), and one that leaves the file stays, the console's again. Schedules are applied last, once the agents and their homes are in. - Agents are independent of projects. Any agent answers in any
project, unless an
allowlist leaves it out:allow, set on the workspace or a project, is the only agents that may run there and below, and a project below can only narrow it.workspace.agents.defaultanswers a message that tags no agent anywhere (an agent, or*for everyone decides: each agent that is nottagged_onlyis asked whether to join, see the dynamic router).autostill works and reads as*, with a load note asking to write"*". Each list names agents in the file or the platform's own. Set, they are the file's as a whole, and the console cannot change them. An agent'sprojectis its home, which says only who sees it: an agent homed in a project everyone reads answers anywhere, and one homed in a project kept to its members answers only where its readers alone read. The workspace default must be allowed at the workspace.enable, a project'sdefaultand a channel'sdefaultare no longer read; a file that sets them still starts, with a load note for each. They are applied in this order: the workspace, the projects, the agents, then each agent's home. A home that leaves the file stays.workspace.baselineis gone: a file that still sets it fails with "baseline is now workspace.agents.default". - Models and tools exist only while the file declares them. A tool's
pinned schemas are its acceptance; anything else stays pending. A tool's
credential_scopesays whose credential reaches it: see Tools that act as you. - GitHub is a client managed by the file,
file-github, read-only in the API. The one an earlier start kept is changed to what the file says, so a field added later, such aslogin, takes effect at the next start.enabled: falseturns it off: it stays the file's and answers no webhook until the file turns it on again. A section that leaves the file leaves the client as it is, still answering. An unchanged section makes no new version. A client of that id made in the console is left as it is. - Nothing is deleted because it left the file.
Agent files¶
An agent is a spec inline, or a file. A file ending in .agent.md is a
saige definition: YAML frontmatter (apiVersion: saige/v1, name,
version, model.use: provider/model, tools, subagents,
approval.ask), then the system prompt. Any other file holds a spec as JSON
or YAML.
---
apiVersion: saige/v1
name: reviewer
version: 1.0.0
description: Reviews changes.
model:
use: anthropic/YOUR_MODEL
---
Review the change and list what is risky.
policy goes beside an .agent.md file, and only there. It holds what
saige's format does not: approvers, self_approval, answerers,
tagged_only, workspace_areas, mcp_write (the MCP servers whose write
tools it may call), knowledge and fallback_on. Left out, it grants
nothing beyond the file.
People pick agents, not models: an agent's model chain and reasoning effort
are its definition's, and nothing overrides them per message. saige's format
has no effort field, so an .agent.md file sets it in its metadata,
metadata: {humagen_effort: high}, and the API as the agent's effort. It
is sent only to the chain's first model, and only when that model takes it;
a run moved to a fallback answers at the model's default.
An agent's answer can have a shape: output: {schema: <JSON Schema>}, for an
object. Its model is asked for structured output under the schema, and a model
that cannot give it fails the run instead of answering in free text. The
answer, checked against the whole schema, is kept on the run as output. An
.agent.md file sets it in metadata, humagen_output_schema, as the schema in
a JSON string.
The approval agent ships with a schema of decision (allow, ask or deny),
reason and references. A workspace may give it its own, which must keep
decision, a required string whose enum is drawn from allow, ask and deny, and
reason, a required string. Any other field, such as risk, conditions or
notify, is recorded with each judgement in the audit as field.<name> and
shown on the approval card. humagen config check refuses a schema without
that core. An answer that is missing or does not hold to the schema leaves the
call for a person.
A choices block
from an older policy or agent spec is not read: a file that has one still
starts, with a load note. subscriptions is refused: the platform decides
what wakes an agent. saige checks the file at start, then the platform's
own rules apply as to any spec. The file's version is not kept: the store
numbers each change, and a run pins the version, digest and policy it
started with.
The Slack app¶
surfaces.slack runs the Slack app (apps/slack) beside the server as a
client of its API, restarting it when it exits. It needs Node.js on PATH and
apps/slack with its dependencies installed (pnpm install), found under the
working directory, beside the binary, or at HUMAGEN_SLACK_APP_DIR. The Humagen image
carries neither, so there the surface is logged as off and the server runs
without it.
The app is given its tokens, its workspace and Humagen's address, plus PATH,
HOME, TMPDIR, TZ, XDG_STATE_HOME, the NODE_OPTIONS,
NODE_EXTRA_CA_CERTS, NODE_USE_ENV_PROXY and proxy variables, and
SLACK_BRANDING and SLACK_SOCKET_*, when they are set. Nothing else of
Humagen's environment reaches it.
humagen slack manifest -f humagen.yaml writes the app's manifest from the
surface: its name (app_name, else the workspace's or deployment's
display_name), command, description, background_color,
command_description and command_usage_hint, each Humagen's when left out.
What the app says in Slack itself (its tagline, disclaimer and suggested
prompts) is the SLACK_BRANDING file's. The app's icon and its bot's
picture are set on the app's page at api.slack.com.
It calls Humagen's API with a credential for the server's sign-in. Under dev it
needs none. Under oidc or mock it needs humagen_client: a machine client of
the identity provider, whose access tokens the app gets with client credentials
and renews as they expire, with the scopes the API
lists for a Slack surface. humagen_token is a bearer token given as it is, for a
token that does not expire; set one or the other. A process cannot sign in
through Tailscale Serve, so tailscale sign-in refuses a Slack surface. A spec
that needs a credential and has none is refused when it is checked, and so is a
start whose -auth flag needs one the file does not give.
Model names are shared across the workspaces in one process: two workspaces may declare the same model, but not two different ones under one name.
Projects¶
The workspace is the root of a tree of projects, written ~ in the
console's addresses. Each entry of workspace.projects is one project:
| Field | Left out | Rule |
|---|---|---|
name |
required | the identity, never changed: letters, digits, spaces, dashes and underscores, starting with a letter or digit, at most 63, unique ignoring case |
title |
the name | what people see: one line, at most 80 characters |
description |
none | at most 500 characters |
kind |
team |
company, team, account or a name in workspace.project_kinds, which behaves as the kind it is like. A company project sits under the workspace or another company project, and there are at most 10. An account never sits under another account |
parent |
the workspace | another project in this file (~ is the workspace), at most 4 levels below the workspace |
account |
none | {customer, external_id, url}, on an account project only. url is https |
instructions |
none | at most 4,000 characters, sent to every agent answering here and below |
agent_posts |
the console's | what an agent scheduled here posts: publish posts it at once, review holds it as a draft until an owner publishes or discards it. A project that leaves both out reviews at the workspace and in company projects, which everyone reads, and publishes in team and account projects. workspace.agent_posts is the workspace's own |
knowledge |
the console's | at most 8 knowledge sources, each named once: lower case letters, digits and dashes, starting with a letter or digit, at most 63. Runs filed here and below are grounded in them, see below |
skills |
the console's | at most 32 skills, each {name, description, argument_hint, instructions}: a name of lower case letters and digits in words joined by single dashes, starting with a letter, at most 64, once; a description on one line of at most 1,024 characters; an optional argument hint of at most 100; instructions of at most 8,000. A message posted here and below names one with $<name>, see below |
schedules |
none | agents scheduled here, see below |
members |
the console's | at most 100 {who, role}: who is * (everyone who can see the parent), role:<name> (the holders of a policy role) or a subject; role is viewer, member or owner. An owner owns everything below. Until reads are confined to members, the list has an entry for * of at least viewer, a company project's of at least member, and a project is never more open than its parent. A new project the file leaves them out of has everyone as a member (a viewer of an account) and projects:govern as its owner |
workspace.members are the workspace's own in the same way: everyone (*)
is at least a member of it, and projects:govern owns it whatever they say.
workspace.project_kinds are at most 16 kinds of the workspace's own, each
{name, title, like}: a name of lower case letters, digits and dashes that is
not a built-in kind, a title of at most 40 characters, and like either
team or account. Behaviors stay Humagen's; names are the workspace's. A kind
a project still has cannot be removed: a start that would fails, naming the
projects.
workspace.instructions, at most 4,000 characters, are sent first, then each
project's down to the one a conversation is filed in. A later one wins, and a
turn is sent at most 8,000 characters of them: the farthest are left out
first, and the turn says which.
knowledge names knowledge sources every run filed in the project and below
it is grounded in, besides its agent's own sources. A run is given its
project's, then each project's above it, workspace.knowledge last, nearest
first, each once, at most 16; never a sibling's or a sub-project's. They are
fixed when the run is accepted, so a change made while it works, or a restart,
does not change what it is grounded in. Sources are filled in the console,
so the file cannot check that the workspace has them: one it does not have
grounds nothing until it does. Through the API, naming one takes an owner of
the project who holds knowledge:read.
skills are named instructions a person can tell an agent to use: writing
the slash command /<name> in a console message (or the aliases $<name>
and @skill:<name>, which Slack and GitHub text and agents' instructions
may use, and which the console shows as /<name>) has every run the message starts
given the skill's instructions ahead of the turn, below the project's and the
agent's own. A message posted in a project can name its project's skills, then
each project's above it, workspace.skills last, nearest first, each name
once; never a sibling's or a sub-project's. A skill nobody on the way declares
refuses the message. A message a person posts in the console, as themselves
and not posted only, that names a skill and tags no agent asks the agents
whether to join, and each that joins is told to use it; one
a client posts is answered by the client's default with the skill. The skills
are fixed when a run is accepted, so a change made while it works, or a
restart, does not change what it was told. A skill's name and description are
ones a SKILL.md takes. A Slack client's command whose name is a skill's uses
that skill. Through the API, declaring one takes an owner of the project.
workspace.mention_kinds are at most 16 kinds of @<kind>:<name> besides the
built-in sme (experts) and skill (skills), each {kind, title, resolves}:
a kind of lower case letters, digits and dashes, starting with a letter, at
most 32, that is not sme, skill or auto, once; a title of at most 40
characters, as the console shows it; and resolves, what its items are:
experts (@<kind>:<topic> is @sme:<topic>), skills (@<kind>:<name> is
$<name>, which the console offers and shows as /<name>), role (everyone holding the policy role <name> is notified,
except in a private thread, where the tag is refused) or people (the person
whose handle is <name>). Left out, a workspace has the built-in kinds only.
Only the file declares them; the console completes each kind's items as a
person types.
humagen config check refuses a mistake with its path, such as
workspace.projects[2].parent: "Feild" is not a project in this file. A
parent must be in the same file, because one made only in the console cannot
be checked before start. A workspace has at most 500 projects, and the start
checks the file again against the projects the console made. A file that
names another kind or parent for a project that already exists changes it as
the console's move would, under the same rules: a move into its own subtree,
past four levels, or that breaks a kind or openness rule fails the start.
Run settings¶
run on workspace or on a project sets what every run filed there and
below may do, and what it prefers. A person adds their own level through
PUT /api/me/context. Each setting is one of two kinds:
| Setting | Kind | Left out everywhere | Rule |
|---|---|---|---|
ceilings.tools |
ceiling | narrows nothing | at most 64 tool names, as an agent's tools writes them (mcp:<name> for a provider's tools). A tool the agent grants that is not listed is taken away for the run. [] allows none |
ceilings.models |
ceiling | narrows nothing | at most 64 provider/model, or provider/* for all of a provider's. The run's model and fallbacks outside it are dropped, and a run with none left is refused |
ceilings.call_depth |
ceiling | the deployment's depth | 0 to 16: how deep a run's calls to other agents may go. 0 calls none. It never deepens the deployment's own limit |
ceilings.tool_servers |
ceiling | none | at most 64 hosts, in lower case, a person's own tool servers may be on. Default deny: only workspace.run opens it, and a project or a person only narrows it |
ceilings.egress |
ceiling | none | at most 64 hosts, in lower case, a run's sandbox may reach through the egress gate, on ports 80 and 443: an exact name, or *.domain for its subdomains (not the domain itself). Default deny: only workspace.run opens it, and a project or a person only narrows it. It takes effect only with the egress slot set to gate (Egress) |
preferences.model |
preference | the agent's model | provider/model, or policy/<name> for one of the workspace's model policies, used in place of the agent's own. One the ceilings do not allow is passed over |
preferences.compaction_tokens |
preference | never compacts | 1,024 to 2,000,000: the input size, in tokens, past which a run's history is summarized before its next model call |
A ceiling is held by the strictest level: the workspace, each project from the root down to the run's, then the person. A level below can only tighten it. A preference is taken from the nearest level that sets one the ceilings allow: the person, the run's project, each project above it, the workspace, then the default.
The settings are resolved once, when a run is admitted, together with who it acts for (whoever posted the message that started it, in a shared thread too), that person's tool servers on the allowed hosts and their memory volume. The result is pinned to the run with a digest, as its agent's definition is: a retry or a replay sees exactly what the first attempt saw, and a change made while the run works reaches only the runs after it. A run another agent calls inherits its caller's context and can only narrow it. A run acting for a person may call only agents that person may read.
A person's own tool servers are kept as an https address and a credential
reference, never a secret, and the reference must be under the person's own
start (System person_refs). They are pinned to the run but not yet
connected: they wait for the sandbox's connector compartment
(RFC 0004).
Channels and experts¶
Every project, the workspace included, has a general channel, and at most
20 channels in all. channels on workspace or on a project declares more,
or declares general to set its purpose:
| Field | Left out | Rule |
|---|---|---|
name |
required | lower case letters, digits and dashes, starting with a letter or digit, at most 40, once per project, never changed |
title |
the name | one line, at most 80 characters |
purpose |
none | one line, at most 200 characters, sent to every agent answering in the channel |
default |
none | no longer read: the workspace default answers a message that tags no agent. A file that sets it still starts, with a load note |
slack |
unbound | {client, channel}: a Slack client's id and a Slack channel's (C... or G..., never a direct message) whose threads are shared threads here. One Slack channel is bound once in the file. The client need not exist yet: until it does the binding binds nothing. The app's bot must already be in the channel |
experts names who answers for some topics, here and below: at most 50, each
{who, topics}, where who is a person's subject or role:<name> and
topics are 1 to 8 of lower case letters, digits and dashes. For a topic, the
nearest project that names someone answers, then the projects above it.
Tagging @sme:<topic> in a thread notifies them, and an agent's question
asked of sme:<topic> is addressed to them.
Tools that act as you¶
An MCP tool is reached with one of two credentials, as its
credential_scope says:
credential_scope |
Reached with | When there is none |
|---|---|---|
shared (the default) |
its credential, the same for every run |
nobody's run gets its tools |
person |
the credential of the person the run acts for, which each person connects for themselves in the console (Your connections) or with PUT /api/me/credentials/{tool} |
that person's run gets no tools from it, and the agent is told they have not connected one |
A person-scoped tool names no credential, and one that does is refused: a
person with no credential of their own is never given a shared one. Its
server is not reached at start, since there is no credential to reach it
with, so each tool in accept carries its description and input_schema
as the server offers them, and is accepted in that form when its
schema_hash is the hash of that schema (humagen config check prints the
hash it computed when they differ). A stdio one needs credential_as.
A run that acts for someone, of an agent granted a person-scoped tool, asks
that person alone what it, or a run it calls, asks with ask_person, even
of the project's experts (asked_of: sme:<topic>), and takes an edit or a
note on an approval only from them, so nobody else's answer reaches their
tools. An agent's answerers still apply, and a called agent's own decide
who answers what it asks: when they leave that person out, nobody may
answer, and the run waits until the question expires or is stopped. Leave
answerers unset on an agent granted such a tool and on every agent it may
call, directly or through another, or name everyone who uses it.
That covers what a run is answered. A later turn is sent the conversation so far, whoever asked or answered its earlier turns, and the transcript does not say who: an earlier turn's answer drawn from someone else's reply reads as the agent's own. Read a conversation before continuing it with an agent granted such a tool, or start a new one (security).
Who a run acts for is decided when it is accepted, never by anything said in it:
| The run | Acts for |
|---|---|
| asked in the console, or through the API with a person's sign-in | that person |
asked by the Slack app built on the API for a Slack person its client maps (act_as) |
the mapped person, never the app. A message the app posts for them into the Humagen thread their Slack thread is (with its surface) is theirs, and so is every run it starts |
| asked about with that app's message shortcut, on someone else's message | nobody: the app asks as itself, since those words are the whole request. Under a dev sign-in, where the app's own credential is the person dev, asking as itself acts for dev. In a channel bound to a project the app refuses it, since only a person's own words are posted there |
| raised by a Slack client's own connector | the one person the team's Slack clients map that Slack user to; none, or two different people, is nobody. It is started only if that person may start it where it is filed: the policy grants their subject runs:write and they are a member of the project. In a channel bound to a project it is not started for nobody |
| started by a message in a shared thread (a tagged agent, an agent that joined, or the thread's default) | the person who posted it, never another participant, though it is sent what the others said in the room ahead of the poster's words; its retry is the poster's alone, from their inbox |
| Run Now on a schedule | whoever pressed it, when they wrote what it runs (whoever last changed its text, or its creator while nobody has, unless someone else has since chosen its agent or its project, whose instructions and notes go ahead of the text); anyone else's press acts for nobody. When the answer may hold what their own credentials reached, deliver does not post it in the project, hold it for the owners or send it to someone else who created the schedule: it goes to them alone, saying why |
| Retry on a failed turn in the inbox, and Retry or Resume in the Slack app | whoever the turn acted for. A turn that acted for a person is retried only by that person, as themselves, and anyone else, an operator included, is refused, except a turn the Slack app asked as itself, which it asks again the same way, by the person who asked or an operator: under a dev sign-in, one that acted for dev. A turn that acted for nobody is retried for nobody: in the inbox by anyone who may start runs, in the Slack app by the person who asked or an operator |
| Retry or Regenerate in a console conversation | the person pressing it, as anything they send there, so each is offered only on a turn that acted for them |
| asked by a machine as itself, a schedule on its own clock, an eval, housekeeping, or another agent's call | nobody |
| raised by GitHub | nobody: no client maps GitHub logins to people yet |
A person connects a credential in one of two ways:
- A reference (
env:,keychain:,op://), which must be the person's own under one of the starts the operator lists for the workspace inperson_refs. Only the reference is stored. The server reads it when a run uses it, with its own access: its environment, its keychain, the 1Password account it signed in to. So every start names the person whose references it holds with{subject}, their sign-in subject, and a person may give only a reference under a start with their own subject in it: underop://People/{subject}/, Ana (subjectana) may giveop://People/ana/issuesand nobody else may.{subject}comes once, after a place of the operator's own, and is followed by/(by_in anenv:start,env:HUMAGEN_PERSON_{subject}_, and in akeychain:start it is in the service,keychain:humagen-people-{subject}/). No two starts may share a place, within a workspace or across two, so give each workspace its own. A subject is written as it is, except in anenv:start, which writes it in capitals (anagivesenv:HUMAGEN_PERSON_ANA_ISSUES). A subject with a character a reference cannot hold there (anenv:start takes lowercase letters and digits; the others take letters, digits,.,_,@and-) can give no reference under it, only a value. Keep each person's items under their exact subject, in a place that holds nothing else, and in a store that tells names apart by case. Anenv:start names aHUMAGEN_variable, never a sign-in secret. A workspace with no entry may reference nothing. - A value, only when the Platform document sets
workspace.person_credentials.values: true. The value is stored, in the same secrets store client secrets are kept in: never returned and never logged, and withstores: {kind: postgres}kept in the database as written. Guard the database as you would the credentials, or keep values off and use references.
Both are checked again on every run, so a value is not used once values are turned off, and a reference is not used once it is no longer the person's own under a listed start.
Memory is files (RFC 0004):
an agent's notes, a project's and a person's own are each a versioned tree,
whose files an agent with the memory_search tool can search. Nothing in the
spec configures it beyond blobs.
What a person's tools found is not remembered. Memory is shared: an agent's notes are sent to every run of that agent, and a project's to every run in it and below it, whoever the run acts for. So the memory agent is not asked about a turn whose conversation, up to and including it, has a turn that acted for a person and was answered by an agent granted a person-scoped tool, whichever agent answers the turn and whether or not approval is on.
Schedules¶
A project's schedules run an agent on a cron, filed in the project, so
each run is counted under every limit on its chain and is sent the
project's instructions and notes:
| Field | Left out | Rule |
|---|---|---|
name |
required | letters, digits, dashes and underscores, at most 63, unique across the deployment: every run it raises carries it |
cron |
required | a 5-field cron expression, in UTC |
agent |
required | an agent in the file or one of the platform's own, available in the project |
text |
required | what the agent is asked, at most 8,000 characters. Each firing is a cron.tick.v1 event carrying it, on the channel cron://<workspace>/<name> |
description |
none | what it is for, at most 500 characters; the agent is not shown it |
deliver |
the run | project posts each answer in the project as an announcement from the agent, its first line the subject, or as a draft for the project's owners under agent_posts: review. An answer of NONE posts nothing. A file has nobody to send an answer to, so inbox is refused |
A recap is such a schedule: humagen-analyst, a Monday morning, "What changed in
Field this week?", deliver: project. A file may name the store's agents
without declaring them; a schedule of one the workspace has not installed is
refused when it fires, with an alert saying which package to install (Core for
humagen-analyst). Its project_changes tool reads only
the project and the projects below it.
Release notes¶
workspace.release_notes: true (off by default) posts what the release of
Humagen this process runs brings in the workspace's own inbox, as an
announcement from humagen: "What's new in Humagen 0.16.0", then the release's
breaking changes and its features, its Breaking and Features groups in the
changelog the binary carries (CHANGELOG.md), and the link to the full
changelog. The release tool files every breaking change under Breaking, a
breaking feature included, so a breaking change of any type is posted.
Fixes are not posted. It reaches everyone who reads the workspace, shows in
What's new and in the workspace's inbox like any announcement there, and
each reader hides it for themselves.
Each release is posted once, at the start that first runs it: a restart, a
later process on the same database, a withdrawal, or retention dropping it
never posts it again.
With memory stores every start is a new inbox, so it is posted at each
start. A release of fixes alone posts nothing, and so does a build that is
not a release: dev, a local build or a pseudo-version. The release is the
version a release build stamps (-ldflags "-X main.version=v0.16.0", as the
Dockerfile does), else the version Go records for Humagen's module
(go install github.com/urmzd/humagen/cmd/humagen@latest, or a program that
imports Humagen at that version). It counts against the workspace's 20
announcements a day; a start past them posts it at the next start. The
Slack app connects after the start and catches up when it does, so it posts
them in a channel bound to the workspace's general, once it was bound
before that start, where a reply under
them starts a thread seeded with them, from Humagen (Slack).
Inbox retention¶
workspace.inbox_retention is how long the workspace's inbox keeps what was
settled for everyone: a message resolved, dismissed or withdrawn. It is whole
days, such as 90d, or a duration, such as 2160h; left out, it is 90
days, and it is at least 7d and at most 100 years (humagen config check
refuses less or more). At start and every hour after, Humagen drops each
message settled longer ago than that, with everything recorded about it:
its outcomes, who read or hid it, and where a client posted it. What is open or snoozed is never dropped, nor a
question a run still waits on, and an announcement stays while it is open
for anyone, however many readers hid their own copy. Message ids are never
issued again, and release notes dropped this way are not posted again.
The badge and Count.updates use counters maintained as inbox changes
apply and rebuilt on replay. Open messages share buckets by kind,
addressing and source. Each reader's read and hidden marks reduce those
counts. The same read rule checks each bucket, so counts reveal only what
the reader may see. Snoozes whose time has passed are added separately;
messages snoozed for everyone are grouped as buckets are, and the read rule
checks each group once.
Settled messages are never scanned to answer a count.
Once a withdrawn announcement is dropped, a reply under its Slack post
starts a thread as any other in the channel, and a thread started from it
no longer shows it. The log lines each inbox decision writes
(platform: inbox) are the operator's, and retention does not touch them.
Which level a knob lives at¶
| Concern | Level | Why |
|---|---|---|
| Listen address, public URL | System | belongs to the host |
| Sign-in and the identity provider | System | one per process |
| Stores, bus, files | System | where state lives is the operator's choice |
| Concurrency, depth and fan-out | System | protects the process |
Where a run's tools execute (sandbox) |
System | the isolation boundary is the host's |
A conversation's readers, run rate and runs per person (rooms) |
System | protects the process |
| Variables a workspace may reference | System | the environment is the process's |
Where people may keep their own tool credentials (person_refs) |
System | a reference is read with the process's own access |
Whether people may store a tool credential's value (workspace.person_credentials) |
Platform | it is the workspace's people's data |
Release notes in the workspace's inbox (workspace.release_notes) |
Platform | it is the workspace's people's news |
How long the inbox keeps what was settled (workspace.inbox_retention) |
Platform | it is the workspace's people's record |
| Names people see | both | the deployment's, then each workspace's |
| Branding: name, logo, palette and fonts | both | the deployment's, then each workspace's |
| Branding: icons and the installable app | System | served before anyone signs in |
| Models and model policies | Platform | what the workspace's agents run on |
| MCP tools and pinned schemas | Platform | what its agents may touch |
| Agents | Platform | the workspace's own |
| Slack and GitHub | Platform | its identity on a surface |
| History | Platform | how it behaves |
| Project tree, kinds, instructions, channels, experts, knowledge sources, skills, mention kinds and which agents are available where | Platform | the workspace's own |
| Spend and run limits | Platform, in the console | versioned, scoped policies (pkg/policy) |
Ceilings and preferences of every run (workspace.run, a project's run) |
Platform, then each person | the strictest ceiling and the nearest preference win |
Deploying it¶
humagen deploy takes the same documents anywhere, so nobody writes compose files
or Helm values by hand:
deploy.kind |
What humagen deploy does |
|---|---|
local (the default) |
humagen start on this machine |
compose |
writes a Docker Compose project (Humagen, and Postgres when asked) and brings it up. Sign-in that only answers on loopback runs on the host's network, so it stays on this machine |
kubernetes |
installs the Helm chart Humagen carries, with the spec as its values, into the cluster the block names |
humagen deploy -o DIR writes the project or the chart and values and stops, for
review or for GitOps (the Flux example in deploy/flux applies the same
chart). A secret never lands in a written file: an env: reference is passed
from the deploying shell's environment, and a keychain: or op:// one is
read on this machine and handed to the target as a variable the written spec
references. The kubernetes block's values are merged over the chart
values Humagen derives, but may not set system or platforms: those are the
spec's documents, whose references humagen deploy carries and checks, so set
them there.
That is for the spec's own references. A person's reference (Tools that act as you) is read where Humagen runs, when a run uses it, so there is nothing to read or pass when deploying:
- A
keychain:orop://start inperson_refsnames this machine's keychain or the 1Password account it signed in to, which a container cannot reach.humagen deployrefuses one forcomposeandkubernetes, naming the entry. For those targets list anenv:start instead, let people store their credential with Humagen (workspace.person_credentials.values: true), or deploylocal. - An
env:start names one variable per person and tool (env:HUMAGEN_PERSON_{subject}_holds Ana'sHUMAGEN_PERSON_ANA_ISSUES), which nobody knows when deploying, sohumagen deploydoes not pass them, and says so in what it prints and in the file it writes. Set each in the target: forcomposein the Humagen service's environment, for example in acompose.override.yamlbeside thecompose.yamlit writes, and forkubernetesin the pod's, for example asextraEnvin the block'svalues, from a Secret of your own.
Extending it¶
| Slot | Built in | A registered kind returns |
|---|---|---|
system.blobs |
disk, memory, s3, gcs | a blob.Store |
system.bus |
memory, postgres | a bus.Bus |
system.extensions[] |
none | something with Run(ctx) error, run beside the server |
platform.models[] |
anthropic, openai, google | a native.ProviderFunc |
platform.tools[] |
mcp | a runtime.Catalog |
humagen.WithKind(slot, name, factory) registers one. The factory is given its
block as JSON and decodes it strictly itself, so its fields get the same
unknown-field errors as the built-ins'. Sign-in and stores are built in only,
for now.
humagen.WithRuntime(rt) runs every turn on your own turn.Runtime
(github.com/urmzd/saige/flow/turn) in place of the native saige
turn. It is handed the pinned definition and the triggering event and streams
back catalog event bodies. It runs inside the same sandbox and on
the same durable runs; it brings its own models and tools, so the spec's
models and WithModelProvider do not reach it.
Since fiber moved into orchagent¶
fiber, anchor and playscape now live in one module,
github.com/urmzd/orchagent, as flow, durable and sandbox. A program
built on the humagen package imports fiber from
github.com/urmzd/orchagent/flow/... (fiber/pkg/durable is now
flow/runschema), anchor from github.com/urmzd/orchagent/durable/... and
playscape from github.com/urmzd/orchagent/sandbox/.... It drops
github.com/urmzd/fiber, github.com/urmzd/anchor and
github.com/urmzd/playscape from its go.mod. Their error messages now start
flow:, durable: and sandbox:; stored names (fiber_* tables, fiber://
URIs, fiber.* event kinds) are unchanged. This is a breaking change for
such a program, not for a file:
| Before | Now |
|---|---|
github.com/urmzd/fiber/pkg/agentrt |
github.com/urmzd/orchagent/flow/turn/native (native.ProviderFunc, native.Option) |
envelope.Tag, envelope.Event |
one event.Envelope, with a typed body per event type |
a kind (delta.text) and a payload |
a type (run.delta.text.v1) and its body |
router, registry, agentspec, topics |
egress, definition over pkg/agents, channels per tenant |
a cron schedule's Meta and Routes |
its Context; where a run answers is its channel |
Nothing a file says changes, and stored data is read as it was written: a run
recorded before keeps its trigger, and a schedule keeps its context
(upgrading-from-warp.md). The API sends a run's
events as the union too: each has a type and its data inline
(API contract).
Since orchagent moved into saige¶
orchagent has since been folded into saige. Humagen requires only
github.com/urmzd/saige v0.45.0 and Go 1.26.11 or later, and a program built
on the humagen package drops github.com/urmzd/orchagent from its go.mod.
flow, durable and sandbox keep their package paths under saige; a few
packages moved into Humagen instead, and a few were not carried over. Stored
and wire names are unchanged: the fiber_* tables, the event type names and
the envelope fields. This is a breaking change for such a program, not for a
file:
| Before | Now |
|---|---|
github.com/urmzd/orchagent/flow/... |
github.com/urmzd/saige/flow/... (flow/event, flow/bus, flow/turn/native, flow/isolation and the rest) |
github.com/urmzd/orchagent/durable/... |
github.com/urmzd/saige/durable/... |
github.com/urmzd/orchagent/sandbox/... |
github.com/urmzd/saige/sandbox/... |
flow/turn/native/saigetypes, ragtypes, agenttest |
github.com/urmzd/saige/agent/types, rag/types, agent/agenttest |
flow/runschema |
Humagen's internal/runschema |
flow/toolprovider, flow/mcptools |
Humagen's internal/toolprovider, internal/mcptools |
the embedders of flow/knowledge |
github.com/urmzd/humagen/pkg/dense |
orchagent's flow root package (flow.New, flow.App) |
gone: compose runtime.New(durable.New(ledger, queue), resolver, bus, ...) from saige/flow/runtime, as internal/platform/platform.go does |
flow/dispatch, the Jira, webhook and author connectors, the knowledge store |
not carried into saige, and not used by Humagen |
github.PrepareReview(r, files, false) |
github.PrepareReview(r, files): an APPROVE review is refused with github.ErrNoApproval |
| one question per park | event.Parked.Questions and event.Resumed.Answers for a batch of waiting tool calls |
scripts/rewrite-orchagent-imports.sh rewrites the imports that map one to
one and lists what it left. See
upgrading-to-saige.md for what changes at
runtime.
Managed source records¶
Managed source configuration is durable API state, documented in sources
and KnowledgeSourceConfig in the OpenAPI contract. mode selects indexed, live
or hybrid behavior. provider selects a registered knowledge.Provider, with
Drive and Notion built in. origin is the selected resource ID. project is
explicit for external sources, with ~ selecting the workspace. The connecting
owner is the authenticated person. stop_after_seconds defaults to 86400 and
accepts 60 through 2592000. No source record contains a credential. Personal
references follow the existing deployment credentials.refs allowlist.
Storage collection credentials¶
GCS and S3 sources use the existing indexed source lifecycle. Set provider
to gcs with an origin such as gs://reports/monthly/, or to s3 with
s3://reports/monthly/. Connect a credential reference as the current reader.
Collection never uses a machine credential, and catalog publication never
grants access to object text. The reader's S3 credential may also include region for buckets outside
us-east-1. The reader's credential uses the same JSON
format documented above. Only UTF-8 .txt, .md, .csv, and .json objects
are collected. A prefix exceeding 200 objects or 8 MiB, an unsupported file,
or any failed read refuses the whole snapshot. Narrow the prefix to collect
only the intended text files. Catalog crawls list at most 5000 objects and
never download their text.
Snowflake uses the SQL API and one explicitly named role with USAGE and SELECT grants only. Queries require a single SELECT, are wrapped with a row limit, and carry a server-side timeout. Result text is capped at 256 KiB. A catalog crawl that exceeds its row, column, or response limits publishes nothing. Configure a restricted read warehouse and resource monitor to bound warehouse credits; Snowflake does not offer BigQuery's bytes-billed cap.
Personal tool server grants¶
An agent opts into the requesting person's own servers with
tools.registry: [person_tools]. This grants no hosts: the resolved
run.ceilings.tool_servers must allow each server's host. The person adds
servers and reviews their tool lists in Customize. Changes to schemas,
metadata or read-only hints require another review; every write tool asks
that person for approval. MCP clients and credential resolution run in the
trusted worker, outside the agent sandbox.
Prompt and evaluation policy¶
Platform.spec.workspace.prompts configures the stable platform and workspace
instruction prefix and the Slack word budget. workspace.eval_limits bounds
online execution cost, duration, and evidence checks. Zero cost or duration limits
leave those optional checks disabled; changing shared instructions requires the sampled eval gate. Existing
runs retain their admitted prompt versions. See Prompt and evaluation policy
for fields, deterministic checks, and approved regression overrides.
Service connection authorization¶
System.spec.connections defaults to disabled. It accepts an encryption_key
secret reference, a redirect_url, optional registered clients, and optional
GitHub App installation configuration under github. The key resolves to a
base64-encoded 32-byte value. Registered clients bind an issuer, client ID,
optional secret reference and scopes; native providers use their fixed profiles.
Configuration does not grant host access, tools or agent routing. See
connection authorization.