byoa: bring your own agent

Status: spec only. No code yet.

byoa is an open-source library that helps you build AI-native apps fast. Your app runs the user's own Claude Code or Codex in a sandbox. The user signs in with their own ChatGPT or Claude plan, so they pay for the AI work with a plan they already have. The user connects each MCP tool (Notion, Gmail, and others) one time, and every agent run has it.

You can use any sandbox provider. To change the provider, you change one adapter.

The problem

To make an app AI-native, you run a big lab's harness (Claude Code or Codex) in a sandbox, with the user's own AI plan. For each app, you must build the same connection layer again:

We built this layer for Bookish. Margins and an AI-native mail app need the same layer. byoa is that layer, as a library.

What byoa is, and what it is not

 ┌────────────────────────────────────────────────────────────────────────┐
 │ END USER                                                               │
 │ has: ChatGPT or Claude plan · Notion, Gmail, Heptabase accounts        │
 └───────────────────────────────┬────────────────────────────────────────┘
                                 │ uses the app
 ┌───────────────────────────────▼────────────────────────────────────────┐
 │ YOUR APP   (its own backend)        calls: agents.run(userId, task)    │
 │ ╔════════════════════════════════════════════════════════════════════╗ │
 │ ║ byoa  (open source, runs inside your backend)                      ║ │
 │ ║  login flow (real claude/codex CLI) · sandbox adapters             ║ │
 │ ║  MCP OAuth + one refresh owner      · harness installer (pinned)   ║ │
 │ ║  skills / AGENTS.md / mcp.json      · MCP proxy                    ║ │
 │ ║  token store: your own database                                    ║ │
 │ ╚════════════════════════════════════════════════════════════════════╝ │
 └──────┬──────────────────────────────┬───────────────────────┬──────────┘
        │ create / resume / destroy    │ MCP calls via proxy   │ mount
 ┌──────▼─────────────────────┐ ┌──────▼──────────────┐ ┌──────▼─────────┐
 │ ANY SANDBOX PROVIDER       │ │ MCP SERVER OWNERS   │ │ USER-OWNED     │
 │ E2B · Daytona · Modal ·    │ │ Notion · Gmail ·    │ │ LOGIN VOLUME   │
 │ Vercel · Cloudflare · ...  │ │ Heptabase · Margins │ │ ~/.claude      │
 │ ┌────────────────────────┐ │ └─────────────────────┘ │ ~/.codex       │
 │ │ HARNESS in the sandbox │ │                         └────────────────┘
 │ │ Claude Code / Codex    │─┼──── model calls on the user's plan ───┐
 │ └────────────────────────┘ │                                       │
 └────────────────────────────┘                                       │
                                               ┌──────────────────────▼──┐
                                               │ AI LABS                 │
                                               │ Anthropic · OpenAI      │
                                               └─────────────────────────┘

How it will look

This is a sketch. The API can change.

import { createAgents } from 'byoa'
import { e2b } from 'byoa/sandbox/e2b'
import { convexStore } from 'byoa/store/convex'

const agents = createAgents({ sandbox: e2b({ apiKey }), store: convexStore(ctx) })

await agents.connectLogin(userId, 'claude')                     // real claude CLI sign-in
await agents.connectLogin(userId, 'codex')                      // real codex CLI, device auth
await agents.connectMcp(userId, 'https://mcp.notion.com/mcp')   // OAuth, one refresh owner
const run = await agents.run(userId, { harness: 'claude', task, skills: ['./skills'] })

To change the provider, change e2b(...) to daytona(...).

How we will verify it

We call version 1 done only when all of these checks pass. The full list is in SPEC.md.

  1. Two apps use it. Bookish moves its login, connector and sandbox code to byoa. A second app (Margins or the mail app) uses byoa with no copied code.
  2. Two harnesses work. One user runs the same task with Claude Code and with Codex, each on that user's own plan.
  3. Two providers work. The same user, with the same MCP grants and skills, runs a job on E2B and then on Daytona. Only the adapter changes.
  4. Tokens stay out of the sandbox. A test searches the sandbox's environment, files and process list for each real MCP token after a job. It must find none.
  5. One refresh owner. Two jobs run at the same time and both need a token refresh. The provider sees one refresh request, and no grant is revoked.
  6. Sandboxes are disposable. The library destroys the sandbox after a job. The next job starts in a new sandbox, and the user does not sign in to an MCP server again.

Rules we follow

License

MIT