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 Agentifys 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, Agentifys 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 Agentifys 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. They are on from the moment you create a project, at 20 per minute and 500 per day. Over the line returns RATE_LIMIT_EXCEEDED with a 429 and a Retry-After header.
• Budget is a monthly token ceiling. It is off by default. Turn it on, cross it, and chat hard-stops with 402 BUDGET_EXCEEDED until the next cycle or you raise it.

Chat is also throttled per user, but that throttle reuses the project's own numbers rather than a share of them. With the defaults, each distinct user id gets its own 20 per minute and 500 per day bucket — and the project bucket is 500 a day too, so one busy user can spend the project's entire day. If you want real fairness between users, raise the project rpm and rpd well above what any one person should get.

The per-user bucket is keyed on the user id you send. In open mode that id is forgeable, so the per-user throttle is a fairness convenience there, not a guarantee; the project-wide ceiling is the only real cap. Counters live in memory in the server process, so a restart begins a fresh window, and a self-hosted deployment running several workers counts separately in each.

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

The console shows token usage per project and per org, budget status, conversation analytics and trends, session transcripts, and a live log stream of tool calls and agent turns.

All of it is console-only. Those routes live under /admin and authenticate with a signed-in console session tied to an org membership — your era_ project key does not open them, and there is no /v1 equivalent. If you need usage or logs in your own dashboard or warehouse today, read them from the console by hand.