Any AI-native software, on your users' own subscriptions.
Apps that use sandboxes and agents need the same connection layer. byoa gives you that layer, so you build the product, not the plumbing.
The user's plan pays
Each user signs in with their own Claude or ChatGPT plan. The agent work runs on that plan, not on your API bill.
The real agents
Your app runs the real, unmodified Claude Code and Codex. Users get the full harness, with their tools and skills.
Any sandbox
Each sandbox provider is one adapter. E2B and Daytona come first. To change the provider, you change one line.
Connect once
The user connects each MCP tool one time. Every agent run has it. The real tokens never go into the sandbox.
Every AI-native app builds the same layer again.
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:
- the user's AI login, through the real CLI;
- the user's MCP connections and their OAuth tokens, with one refresh owner;
- the user's skills and AGENTS.md;
- the harness install and its updates;
- the code that connects all of this to one sandbox provider.
byoa is that layer, as a library, so you do not build it again for each app.
The same work, three times. Weeks before the first useful feature.
Each app imports the layer. The goal: the first agent run in one day.
byoa sits in your backend, between your users and their agents.
Your app calls agents.run(userId, task). byoa starts a sandbox, loads the user's setup, and runs the user's own harness on the user's own plan.
Scroll sideways to see the whole diagram →
Real tokens never go into the sandbox.
The agent in the sandbox gets a short-lived job token. The proxy in your backend adds the real MCP token to each request.
Scroll sideways to see the whole diagram →
One refresh owner
Your backend owns each grant's refresh. Two jobs that need a refresh at the same time cause one refresh request.
Your database
byoa stores grants through a store adapter, encrypted with a key that your app gives.
Your user's login
By default, the AI login stays in a volume that belongs to that one user. byoa does not copy the Claude login into your database.
Every job gets a fresh sandbox.
The sandbox is disposable. The user's setup stays, so the next job needs no new sign-in.
- 01Createbyoa starts a sandbox at your provider.
- 02Load the setupPinned harness, skills, AGENTS.md and MCP config.
- 03Run the jobText, tool calls and permission requests stream back as events.
- 04Destroybyoa destroys the sandbox at the provider.
A few calls to the first agent run.
The goal for v1: a new app reaches its first agent run in under 50 lines of its own code.
- 1Sign-in is databyoa gives you the sign-in URL and code, so you can show them on any device, also a phone.
- 2One event streamClaude Code and Codex stream events in one schema. Your UI handles one format.
- 3Test without a planA fake harness lets you test with no AI plan and no sandbox.
This is the API in this repository today. It can change before version 1.
import { createAgents } from 'byoa'
import { e2b } from 'byoa/sandbox/e2b'
import { postgresStore } from 'byoa/store/postgres'
const agents = createAgents({
app: 'myapp', // each app has its own login volumes
sandbox: e2b({ apiKey }),
store: postgresStore({ query: (sql, args) => pool.query(sql, args) }),
encryptionKey, // openssl rand -base64 32; grants are encrypted with it
proxyUrl: 'https://myapp.example.com/byoa/mcp', // serve agents.proxy here
oauth: { redirectUrl: 'https://myapp.example.com/byoa/callback' },
})
const claude = await agents.connectLogin(userId, 'claude') // { url }: Anthropic's own sign-in page
await agents.finishLogin(userId, 'claude', { code }) // the code that page shows
const codex = await agents.connectLogin(userId, 'codex') // { url, code }: OpenAI's page and the code to enter
await agents.finishLogin(userId, 'codex', { waitMs: 60_000 })
const mcp = await agents.connectMcp(userId, 'https://mcp.notion.com/mcp', { name: 'notion' })
// mcp.signInUrl: the server's sign-in page; your redirectUrl route then calls agents.finishMcp({ state, code })
for await (const event of agents.run(userId, { harness: 'claude', task, mcp: ['notion'], setup: { agentsMd, skills } })) {
// start, text, tool_call, tool_result, permission, error, end: the same events for Claude Code and Codex
}Each job runs in a new sandbox, and byoa destroys the sandbox after the job. The user's AI login stays in a volume of that user and app. The MCP config in the sandbox points to agents.proxy, with a token for that one job. The real MCP tokens stay in your database.
To change the provider, change e2b(...) to another adapter. An adapter implements one interface (src/sandbox/types.ts): create (with volumes), resume, run a command, write a file, destroy. The Convex store adapter is not written yet.
For Daytona, use daytona({ apiKey }) from byoa/sandbox/daytona (it needs @daytona/sdk). Daytona allows 100 volumes per organization, so the adapter keeps every user's AI login in its own subpath of one shared volume (byoa by default). A sandbox mounts only that user's subpath. On Daytona Tier 1 and Tier 2, a sandbox can reach only allowed domains, so serve agents.proxy on one of them (for example *.convex.site or *.workers.dev), or use Tier 3 or higher.
What version 1 covers.
These are the targets in SPEC.md. Claude Code and Codex are both in the first version. Other agents can come later.
BYOA IS
- A library that runs inside your app's own backend
- Open source, under the Apache 2.0 license
- A way to store tokens in your own database
- A runner for the real, unmodified claude and codex binaries
BYOA IS NOT
- A hosted service. We run no server and never see your users' tokens
- A way to share one user's AI login between apps
- A modified client, or a client that pretends to be another
- A UI kit. byoa gives data and events; your app draws its own UI
v1 is done only when these checks pass.
We call version 1 done only when all of these checks pass. The full list is in SPEC.md.
- Two apps use it. An existing app moves its own login, connector and sandbox code to byoa. A second app uses byoa with no copied code.
- Two harnesses work. One user runs the same task with Claude Code and with Codex, each on that user's own plan.
- 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.
- 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.
- 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.
- 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.
We follow the labs' rules.
byoa uses each user's plan the way Anthropic and OpenAI allow: the real binaries, the labs' own sign-in pages, and one app per login.
- We run the real, unmodified
claudeandcodexbinaries. We never pretend to be another client. - The user signs in through Anthropic's or OpenAI's own sign-in page.
- One app's AI login is used only by that app.
- Each app signs its own agreements with the labs when it needs them. See SPEC.md.