> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2-codex-homepage-20260719-015142.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Context

> Self-hosted multiplayer context agent with a private CRM, knowledge base, teammate inbox, and read-only MCP surface.

**@context gives one owner a private work context that teammates can contribute to and AI apps can read through a constrained surface.**

It is for founders, managers, and operators whose contacts, decisions, reminders, messages, and project knowledge are spread across systems. Teammates can submit updates and check their own receipts. Only verified owner identities receive the private CRM, knowledge, retrieval, and action surfaces.

Agno selects tools from the caller's identity before the model runs, loads owner-only playbooks at runtime, and exposes one read-only MCP tool to Claude, ChatGPT, Claude Code, Codex, Cursor, and other clients. Run it locally, connect the AgentOS UI, then capture a contact or ask for your daily rundown. The [source](https://github.com/agno-agi/context) is public.

## Run locally

**Prerequisites:** [Docker](https://www.docker.com/get-started/) and an [OpenAI API key](https://platform.openai.com).

```bash theme={null}
git clone https://github.com/agno-agi/context.git && cd context

cp example.env .env
# Set OPENAI_API_KEY, OWNER_ID, OWNER_NAME, and OWNER_TIMEZONE in .env

docker compose up -d --build
curl http://localhost:8000/health
```

Open the API at [localhost:8000/docs](http://localhost:8000/docs). `OWNER_ID` decides who receives the private owner surface. In AgentOS and private Slack DMs, every other verified caller receives the private guest surface.

### Connect the AgentOS UI

1. Open [os.agno.com](https://os.agno.com) and sign in with an identity listed in `OWNER_ID`.
2. Choose **Connect OS** → **Local**.
3. Enter `http://localhost:8000`, name it **Local Context**, and connect.
4. Open **Context** under Agents and try a prompt from the examples below.

### Connect MCP clients

The MCP endpoint exposes one tool, `use_context`, for retrieving and preparing the owner's private context. Filing, learning, acknowledgement, drafts, Slack sends, and other mutations are absent from this surface.

```bash theme={null}
uvx agno connect
```

The command detects supported local clients, preserves their other MCP entries, registers `http://localhost:8000/mcp`, and verifies the connection. Undo the registrations with `uvx agno disconnect`.

Local MCP is keyless in development. Anything that can reach the port can read the owner's context through `use_context`. Keep it on a trusted machine and network. See [docs/MCP.md](https://github.com/agno-agi/context/blob/main/docs/MCP.md) for production OAuth and per-client setup.

## How it works

@context is one Agno agent that captures, files, retrieves, and prepares working context. In production, AgentOS verifies HTTP identities from JWTs. Slack verifies signed events and maps their authors to user IDs. Explicit local development trusts the caller-supplied `user_id`.

| Caller                                 | Effective surface                                                       |
| -------------------------------------- | ----------------------------------------------------------------------- |
| Owner in AgentOS or a private Slack DM | Full configured Context surface                                         |
| Guest in a private run or DM           | `submit_update`, caller-scoped `my_updates`, and caller-scoped learning |
| Anyone in a shared Slack room          | `submit_update` only                                                    |
| Owner-approved MCP client              | Fresh, private, read-only `use_context` calls                           |

The built-in playbooks help the owner retrieve and prepare context:

| Playbook      | Ask                         | What you get                                                                                                                     |
| ------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Rundown**   | "What's on today?"          | Queued teammate updates, due reminders, stored meetings, and relevant Gmail or Slack context when configured                     |
| **Week plan** | "What's my week?"           | Priorities for the week. When Slack is configured, runs Sunday evening and lands in your Slack DMs                               |
| **Prep**      | "Prep for my 2pm with Kyle" | A pre-meeting brief: who they are, notes, past threads, what's still open, and public background for contacts you don't know yet |

Playbooks live in `skills/`, one `SKILL.md` per folder. The shipped set also includes `process-today`, `research`, and `knowledge-review`. When Slack is configured, scheduled daily and weekly playbooks DM their results to the owner.

### Context sources

Most sources use Agno context providers that expose `query_<id>` for reads and a source-scoped update tool where writes are enabled. The workspace source exposes `list_files`, `search_content`, and `read_file` directly.

| Source      | Access                             | Enabled by                                 |
| ----------- | ---------------------------------- | ------------------------------------------ |
| `crm`       | Read and write                     | Always on                                  |
| `knowledge` | Read and write                     | Always on                                  |
| `workspace` | Read                               | Always on                                  |
| `web`       | Read                               | Always on                                  |
| `slack`     | Read; owner-confirmed sends        | `SLACK_BOT_TOKEN`                          |
| `gmail`     | Read; draft create and update only | Google OAuth credentials and a Gmail token |

The `crm` source stores contacts, projects, meetings, reminders, notes, and queued updates in Postgres. The `knowledge` source stores specs and research notes on the filesystem by default and can use a private Git repository in production.

### Security

The toolset is chosen in code from the request identity before the model runs. A private guest can append to the owner's queue with `submit_update` and read only their own receipts with `my_updates`. Shared Slack rooms expose only `submit_update`. Guests cannot access the owner's CRM, knowledge base, inbox, queue, or action tools. Each caller's memory is scoped to their verified identity.

Owner actions are narrow. `update_slack` sends exact text only after explicit approval. `update_gmail` can create or update a draft and has no send capability. After a provider, workspace, or rundown read, the current run becomes read-only. Make any follow-up mutation as a fresh private request.

@context runs locally or in your own cloud. Its CRM and inbound queue live in Postgres, and its knowledge base lives on the filesystem or in a private Git repository. Prompts and retrieved material are processed by the model and provider services you configure. See [docs/SECURITY.md](https://github.com/agno-agi/context/blob/main/docs/SECURITY.md).

## Deploy to Railway

@context runs anywhere that runs a Docker container. For a quick deployment, `scripts/railway/up.sh` runs @context and Postgres on the same private network. It reads credentials from `.env.production` and creates the public domain you connect to in the AgentOS UI.

**Prerequisites:** [Railway CLI](https://docs.railway.com/cli#installing-the-cli) installed and `railway login` completed.

<Steps>
  <Step title="Create a production env">
    ```bash theme={null}
    cp .env .env.production
    ```

    The deploy scripts read `.env.production` first and fall back to `.env`.
  </Step>

  <Step title="Deploy">
    ```bash theme={null}
    ./scripts/railway/up.sh
    ```

    The script creates your public domain, then pauses and waits while you mint the JWT verification key.
  </Step>

  <Step title="Mint your JWT key">
    Token-Based Authorization is on by default. Without a `JWT_VERIFICATION_KEY` in `.env.production`, the AgentOS will not serve traffic. That is the safe default for an agent that holds your work context. You can also [issue and verify your own JWT](/agent-os/security/authorization/self-hosted).

    1. Open [os.agno.com](https://os.agno.com), click **Connect OS** → **Live**, and paste the domain the script printed.
    2. Turn on **Token-Based Authorization** and click **Connect**.
    3. Copy the public key into `.env.production` as `JWT_VERIFICATION_KEY`.
    4. Back in the terminal, press Enter. The script reads the key and deploys the service.
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    railway logs --service agent-os
    ```

    Open `https://<your-domain>/docs` to confirm the API is serving.
  </Step>
</Steps>

If you add or update values in `.env.production`, sync them with `./scripts/railway/env-sync.sh`. After code changes, redeploy with `./scripts/railway/redeploy.sh`, or connect the repo in the Railway dashboard to auto-deploy on push.

### Point MCP clients at production

Production connections use MCP OAuth. `scripts/railway/up.sh` generates `MCP_CONNECT_SECRET` when it is missing. A client connects by URL, and you approve it once on a consent page by entering that secret.

```bash theme={null}
uvx agno connect --url https://<your-domain>
```

The command wires Claude Code, Codex, Cursor, and Claude Desktop and prints each client's sign-in step. In claude.ai or ChatGPT, add `https://<your-domain>/mcp` through the app's custom connector flow, leave optional OAuth client credentials empty, and approve the consent page with `MCP_CONNECT_SECRET`. The AgentOS UI uses its separate control-plane JWT. Rotating `AGENTOS_MCP_SIGNING_KEY` revokes every issued token; rotating `MCP_CONNECT_SECRET` gates future consents.

See [docs/MCP.md](https://github.com/agno-agi/context/blob/main/docs/MCP.md#production-mcp-oauth) for the consent flow, per-client specifics, and ChatGPT and Claude on the web.

### Back the knowledge base with Git

Local runs store the knowledge base in a gitignored `knowledge/` folder. In production, back it with a private Git repo: create one, mint a fine-grained token with read and write access to its contents, and add both to `.env.production`:

```bash theme={null}
KNOWLEDGE_REPO_URL=https://github.com/you/your-context.git
KNOWLEDGE_GITHUB_TOKEN=ghp_...
```

Then sync with `./scripts/railway/env-sync.sh`. Every update commits and pushes, so the git history is your audit trail. See [docs/KNOWLEDGE.md](https://github.com/agno-agi/context/blob/main/docs/KNOWLEDGE.md).

## Connect to Slack

With Slack configured, teammates can @-mention @context to leave you updates, you can DM it for private conversations, and the scheduled daily rundown and weekly plan land in your DMs.

1. Create a Slack app from the manifest in [docs/SLACK.md](https://github.com/agno-agi/context/blob/main/docs/SLACK.md).
2. Copy the Bot User OAuth Token and Signing Secret.
3. Set `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET` in `.env` or `.env.production`.
4. Restart the application.

Local runs need a public URL for Slack's callbacks, so use an ngrok tunnel. Once you deploy, repoint the app's `/slack/events` and `/slack/interactions` request URLs at your Railway domain.

## Connect Gmail

Connect Gmail to ground rundowns and preparation in your inbox. Set `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, and `GOOGLE_PROJECT_ID`, then mint the consent token once with `python scripts/google_mint_tokens.py`. See [docs/GOOGLE.md](https://github.com/agno-agi/context/blob/main/docs/GOOGLE.md).

## Example prompts

Use the AgentOS UI or a private Slack DM for prompts that write context:

* Add Dana Reyes, Head of Platform at Acme, [dana@acme.com](mailto:dana@acme.com). Remind me to send her the integration spec next Tuesday.
* Write up a decision: we're standardizing on Agno.

Use any connected interface for retrieval and preparation:

* Who do I know at Acme?
* What's on today?
* Prep for my 2pm with Kyle.
* What in my knowledge base needs attention?

## Run evals

@context comes with model-backed behavioral evals in [`evals/`](https://github.com/agno-agi/context/tree/main/evals). They exercise guest boundaries and adversarial attempts to reach owner data. Deterministic policy and authorization checks live in `tests/`.

```bash theme={null}
./scripts/venv_setup.sh

.venv/bin/python -m evals --tag smoke
.venv/bin/python -m evals --tag release
.venv/bin/python -m evals --name guest_cannot_read_the_crm
```

## Source

The [GitHub repo](https://github.com/agno-agi/context) has the full detail:

| Guide                                                                                  | Covers                                                          |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| [`AGENTS.md`](https://github.com/agno-agi/context/blob/main/AGENTS.md)                 | Architecture, key files, and conventions for coding agents      |
| [`docs/SECURITY.md`](https://github.com/agno-agi/context/blob/main/docs/SECURITY.md)   | The owner/guest model, read boundary, and action controls       |
| [`docs/MCP.md`](https://github.com/agno-agi/context/blob/main/docs/MCP.md)             | Per-client MCP setup and production MCP OAuth                   |
| [`docs/SLACK.md`](https://github.com/agno-agi/context/blob/main/docs/SLACK.md)         | The app manifest, identity resolution, and moving to production |
| [`docs/KNOWLEDGE.md`](https://github.com/agno-agi/context/blob/main/docs/KNOWLEDGE.md) | The knowledge base and Git backing                              |
| [`docs/CRM.md`](https://github.com/agno-agi/context/blob/main/docs/CRM.md)             | The `crm` schema, filing rules, and the write boundary          |
| [`docs/GOOGLE.md`](https://github.com/agno-agi/context/blob/main/docs/GOOGLE.md)       | Gmail setup                                                     |
| [`docs/NETWORK.md`](https://github.com/agno-agi/context/blob/main/docs/NETWORK.md)     | How a team's contexts talk to each other                        |