agent-foyer

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-dark.png"> <img alt="Agent Foyer: a place where agents work" src="docs/assets/banner-light.png" width="100%"> </picture> </p> <p align="center"> <a href="https://github.com/AIsa-team/agent-foyer/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/AIsa-team/agent-foyer/actions/workflows/ci.yml/badge.svg"></a> <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-2d2d2b"></a> <img alt="Node 22.18+" src="https://img.shields.io/badge/node-%E2%89%A522.18-2d2d2b"> <img alt="MCP with OAuth 2.1" src="https://img.shields.io/badge/MCP-OAuth%202.1-F76918"> </p> <p align="center"> <a href="#quick-start">Quick start</a> · <a href="#the-five-things">The five things</a> · <a href="docs/DEPLOY.md">Deploy</a> · <a href="CONTRIBUTING.md">Contribute</a> · <a href="README.zh-CN.md">中文</a> </p>

Any agent that speaks MCP (Claude Code, Codex, Cursor, one running in the cloud, …) can connect and get the five things it needs to do real work for the people it works with: identity, context, a place to ship, resources and guardrails. People decide; agents do the rest.

It is for anyone who works together and has agents: a company, a team, a community, an open-source project.

<p align="center"> <img alt="A home page in Agent Foyer: numbers, calendar and charts, built by an agent" src="docs/assets/home-en.png" width="100%"> </p>

What that looks like

"Make a page that shows how our posts are doing. Keep a list of everything we post, pull in the latest views and likes from each platform, and suggest three topics for next week."

A few minutes later the agent has published it at content.<your apps domain>, behind sign-in and open only to the people you chose. Views and likes come from data APIs and the topic ideas from a model, both through the hub, so the agent writes no scraper and the app holds no API key. Whoever you make content with has their agent log each new post as it goes out (call_app). Your home page shows how the week is going, and whoever posted something without a link is asked to add it.

Nobody filled in a form or clicked through an admin page. Each step was a sentence to an agent, and the web pages are where people look and decide.

The five things

| | What agents get | | |---|---|---| | Identity | Every agent acts as its person, with that person's own accounts and access | ↓ | | Context | Data, documents, goals, calendar, projects, know-how as Skills, people | ↓ | | A place to ship | Apps on their own subdomain, pages and boards, checks and alerts | ↓ | | Resources | Models and data APIs that apps call instead of rebuilding, other tools' MCP servers, data connections | ↓ | | Guardrails | Checked as the person every time, consent, limits, keys agents never see | ↓ |

Identity: every agent acts as its person

• People sign in with Feishu/Lark or any OpenID Connect provider (Google Workspace, Microsoft Entra ID, Okta…). Agents connect with standard MCP OAuth 2.1, or a personal token when they cannot do OAuth.
• Whatever an agent reads or changes in other tools (Feishu/Lark, Linear, GitHub, …), it does with that person's own account and access; apps save mail drafts in the person's own mailbox. An agent never sees more than its person could.
• People see each of their agents with the device it was added from and a name they give it, and disconnect any of them.

Context: what the agent needs to know

• Data from wherever it lives, such as Feishu/Lark Base tables or Metabase questions and read-only SQL; anything else comes in through a small app an agent builds to serve its rows. When admins turn it on, two sources can be combined into one. Agents count, chart and read rows (query_data, read_data_rows).
• Documents: search, read, edit and create documents and wiki pages, in Feishu/Lark today.
• Goals and time: OKRs, the person's calendar, Linear projects and issues, GitHub activity.
• Know-how as Skills: a Skill market with versions and update notices; agents that cannot install Skills read and follow them (read_skill), so a scheduled task always uses the latest version.
• People: the directory, departments and their pages, app requests from the people you work with.

A place to ship: what agents build, people and agents use

• Apps: "publish this" deploys a static site or a container to its own subdomain, behind sign-in, visible to only you, chosen people, everyone signed in, or the public (an admin approves). With Feishu/Lark, apps keep their records in Feishu/Lark tables the people using them can see and edit.
• Apps for agents too: an app says in hub-agent.json what other agents may do in it (find, add and change records, call its own actions); they find it with list_apps and act as their person with call_app.
• Pages: agents build home pages (personal, per department, for everyone) and data boards (your own, shared, per department) from charts, numbers, tables, OKRs, the calendar and more.
• Watching data: metric alerts and data checks that hand each problem row to the person who owns it.
• Working together: collaborators on apps and Skills, feedback to their authors, and a pool of app requests.

<table> <tr> <td width="50%"><img alt="Apps built by people's agents, each on its own subdomain" src="docs/assets/apps-en.png"></td> <td width="50%"><img alt="The Skill market, with versions and update notices" src="docs/assets/skills-en.png"></td> </tr> <tr> <td align="center">_{Apps agents published, each on its own subdomain}</td> <td align="center">_{Skills, versioned, with update notices}</td> </tr> </table>

Resources: call it, don't rebuild it

Much of the data a team needs already exists as an API: posts and trends on X, website traffic, search results, market data, papers. When an agent builds an app that needs it, the app calls that API through the hub: nobody writes a scraper or rebuilds the data, and nobody signs up with each provider one by one. So the hub gives what agents build a resource layer:

• Models and data APIs on one key. Pick a provider on the admin page: an AI resource platform such as AIsa, where one key covers 100+ models and thousands of data APIs (search, X, Similarweb, finance, papers, scraping…), or, for models only, any OpenAI-compatible service (OpenAI, OpenRouter, your own gateway…). Each provider is a small preset in server/ai.ts, so others like it are easy to add.
• Ready for what agents build. Apps call models at /__hub/ai/v1/… (OpenAI-compatible, streaming included) and data APIs at /__hub/ai/apis/v1/…, as the person using them, without holding a key. Agents see what is there with ai_resources.
• Other tools' MCP servers (Linear, Metabase, …): each person connects their own account, or a shared key is used for everyone, and agents reach them through the hub (list_connected_tools, call_connected_tool).
• Data connections (Metabase today): read with one key, shared only as admins decide.

Guardrails: why it is safe to let agents act

• Access is checked as the person on every read, and every app request is re-checked, so revoking access takes effect at once.
• An app asks each person once before it acts as them in Feishu/Lark or saves mail drafts; agents are told to confirm before tools that change things.
• Keys are entered on the admin page only, kept encrypted and never shown again, never handed to agents or apps.
• AI calls have daily limits per app and per person, are recorded with their tokens, and need a signed-in person: a public app cannot spend your credit for strangers. SQL from agents can only read.
• Container apps run in their own containers with memory, CPU and process limits and no capabilities. Admins can switch tools, apps' AI use and whole services off.

Works with what you already use

Platforms come in as channels (server/channels.ts). Feishu/Lark is the first: sign-in, directory, Base tables, OKRs, documents, calendar and bot messages. Without it, sign in with OpenID Connect and you keep the core: apps, Skills, agents, pages, data apps and connections, checks, alerts and AI resources (docs/OIDC_SETUP.md). A new platform is a new channel: its directory and its kinds of data source behind two small interfaces (see CONTRIBUTING.md).

Everything people see exists in every language the hub ships (English and Chinese today; a new one is a catalogue file).

How it works

flowchart LR
  agents["Agents<br/>Claude Code · Codex · Cursor …"] -- "MCP + OAuth" --> hub
  people["People<br/>in the browser"] --> hub
  people --> gateway
  subgraph foyer["Agent Foyer · one Node process"]
    hub["Web UI · API · MCP"]
    gateway["App gateway<br/>sign-in · access · /__hub"]
  end
  gateway --> apps["Apps<br/>static files or containers<br/>&lt;slug&gt;.your-apps-domain"]
  hub --> tools["Feishu/Lark · Linear · GitHub<br/>Metabase · Gmail …"]
  gateway --> ai["AI provider<br/>models · data APIs"]

• One process, routed by Host. The hub's own domain goes to the Hono app; app subdomains go to the gateway. The reverse proxy only terminates TLS, so adding an app never touches its config.
• Storage: SQLite (data/hub.db) plus app files, Skill packages and icons under data/.
• App sign-in: the gateway sends visitors to the hub, which checks who they are and hands a one-time code back to the app's subdomain, exchanged for a cookie scoped to that subdomain only. Apps read the person from the X-Hub-User-* headers, or fetch('/__hub/me') in the browser; an app's server calls the hub with the X-Hub-Ticket of the person's request.
• Two kinds of app: static (built files, SPA routing supported) and container (its own Dockerfile, or one generated for Node and Python projects). Each container app is on a private Docker network only the hub can reach, with a persistent /data and encrypted environment variables.
• Agents get the hub's tools and instructions over MCP and are told when the hub changed since they connected.

Quick start

Let your agent set it up

Paste this into your agent (Claude Code, Codex, Cursor, …):

Set up Agent Foyer for me on this machine: https://github.com/AIsa-team/agent-foyer

1. Clone it. It needs Node >= 22.18 and pnpm; tell me if either is missing.
2. Run `pnpm install` and `pnpm build`, then start it with `pnpm dev` in the background and wait until
   http://localhost:8080 answers. With no sign-in settings it uses a dev login with three test users.
3. Connect yourself to it as a remote MCP server named agent-foyer at http://localhost:8080/mcp (HTTP, with OAuth):
   - Claude Code: `claude mcp add --transport http --scope user agent-foyer http://localhost:8080/mcp`,
     then remind me to type /mcp, pick agent-foyer and sign in.
   - Codex: `codex mcp add agent-foyer --url http://localhost:8080/mcp`, then `codex mcp login agent-foyer`.
   - Other agents: add the URL as an HTTP / Streamable HTTP server and follow the sign-in.
   If you need a restart to see its tools, tell me.
4. Call its whoami tool, then tell me in a few lines what I can ask you to do with it.

To run it for your team on a server, ask your agent to follow docs/DEPLOY.md with you.

Or by hand

Needs Node ≥ 22.18 (TypeScript runs directly, no compile step) and pnpm.

pnpm install
pnpm build          # build the web UI
pnpm dev