Core concepts

An org is your company. Inside it you create projects, and each project is one agent: its own key, its own model keys, its own tools, its own knowledge, its own settings. One install runs many agents with strict per-org isolation, so a project in one org can never see another org's data.

People join an org with roles. An owner or admin can change settings and connect tools, a viewer can look but not touch. Invite teammates from the console and they land in the same org.

Your product tells EERRAA who the current user is through a user context object. There are two modes:

• Open trusts the identity as-is. Good for personalization: the agent knows the user's name, role, and any data you pass. Nothing stops a determined user from editing it in the browser, so open mode never gates anything private.
• Signed makes the identity tamper-proof. Your server signs the context with HMAC-SHA256 over canonical JSON plus a fresh timestamp, valid for 300 seconds. Signed mode is what gates private uploads, the vault, per-user MCP OAuth, and the My-tasks panel.

The signing secret lives in Settings under Identity and is server-side only. Never put it in a client bundle or a VITE_ / NEXT_PUBLIC_ variable. The Identify your users guide has the full signing recipe.

Tools are how the agent acts. There are two ways to give it some:

• Custom tools are your own webhooks. You describe the inputs, EERRAA calls your endpoint when the agent decides to, and every request is SSRF-guarded so a tool can't be tricked into hitting your internal network.
• MCP servers are remote toolsets. Connect any Streamable-HTTP MCP server and its whole toolset auto-imports. There is a one-click catalog (Tavily, Exa, Firecrawl, Context7, DeepWiki, Hugging Face) and support for none, bearer, header, or OAuth auth.

Discovered tools import disabled. You enable the ones you want, and re-running Discover preserves your choices. Write actions pause for an Approve or Cancel confirmation in the widget before they run.

Some tools need a secret that belongs to the end user, not to you: their API key for another service, for example. The per-user vault holds those secrets Fernet-encrypted at rest. You reference one in a tool's auth as {{user.creds.<name>}} and EERRAA injects it at call time. The raw secret never reaches the model. You can also forward a live JWT with {{user.auth_token}}.

Caps are 50 credentials per user and 8 KB per value. Secrets are provisioned server-to-server with a signed identity via PUT /v1/credentials, so raw values never travel through the browser. The vault requires signed identity.

Upload PDF, TXT, or MD files and the agent answers from them. Retrieval is hybrid: pgvector cosine top-K plus Postgres full-text search, fused, reranked, and the top-4 chunks are injected into the prompt. Embeddings use BAAI/bge-m3, so it works across Arabic, English, and mixed content.

Every document has an audience. The shared project pool is visible to everyone using that agent. A private user pool is scoped to one person, keyed by their id, and requires signed identity to write to. The agent retrieves from the shared pool plus the current user's private pool, never someone else's.

The agent can offer clickable buttons instead of making the user type. It ends a reply with a fenced code block tagged choices holding a JSON array of 2 to 6 short strings, and the widget renders them as buttons. Tap one and it goes back as the next message. It is a plain convention, no special API, and you can turn it off per widget with data-options="off".

Two kinds of guardrails keep an agent from running away with your model bill:

• Rate limits cap requests per minute and per day for the project, plus a per-user chat throttle. Over the line returns RATE_LIMIT_EXCEEDED.
• Budget is a monthly token ceiling. Cross it and chat hard-stops with 402 BUDGET_EXCEEDED until the next cycle or you raise it.

On top of that, every write action pauses for confirmation, so the expensive and the irreversible both stay under a human's thumb.