BYOB CLI

BYOB CLI is the Codex connector for BYOB. It installs a local byob command, configures Codex MCP, and installs the byob_cli skill so Codex can safely edit approved BYOB projects.

Under the hood, byob mcp starts a stdio MCP server that forwards JSON-RPC to BYOB's hosted Agent MCP endpoint in AIR using a user-approved agent token. The package does not contain BYOB platform credentials.

Install

Use the package directly from npm. Codex is the primary supported client, and other MCP clients can use the same standard command + args + env model:

npx -y byob-cli --help

Install and authorize BYOB for Codex in one command:

npx -y byob-cli codex install --client-name "Codex"

The command starts the BYOB OAuth device flow, waits for browser approval, then runs codex mcp add with the approved project scope. It also installs the byob_cli skill into ~/.agents/skills/byob_cli so Codex can discover it in /skills or $ skill invocation. byob_cli is the Codex platform contract: it tells Codex how to establish active project context, route tools, handle preview/editor/deployment URLs, protect BYOB-managed files, test changes, and use deployment/billing/domain tools. After authentication, the installer also downloads BYOB AIR coding skills into local Codex skill folders with byob_ prefixes. Those synced skills hold reusable implementation knowledge for SvelteKit, Supabase, BYOB DB, UI quality, SEO, PWA, payments, animations, image generation, and integrations. The wizard prints a BYOB banner, auto-opens the approval URL when possible, shows progress steps, and prints the final Codex server/skill install locations. Pass --no-open to suppress browser opening, --no-skill to skip local skill installation, or --no-air-skills to skip downloading AIR coding skills.

Refresh synced coding skills later without rerunning OAuth or changing MCP config:

npx -y byob-cli codex sync-skills --project-id <project_id> --token <agent_access_token>

For Local Codex billed project editing, the BYOB Agent MCP returns a workspace handle that the Codex host opens as the active Codex workspace. The native handoff uses SSH into the BYOB project container:

npx -y byob-cli@latest codex ssh-proxy '{"ssh_endpoint":"wss://..."}'

Use byob-cli@latest for Local Codex billed.

Or install it globally:

npm install -g byob-cli
byob --help

Requirements:

• Node.js 18 or newer.
• A BYOB agent access token from the OAuth device flow.
• One or more project ids approved during the OAuth flow.

URLs And Environments

There are two classes of URLs:

• Control-plane URLs are configured by the user or deployment:
  • BYOB_AIR_URL: Agent MCP broker. Production is always https://air.api.byob.studio.
  • --prim-url / BYOB_PRIM_URL: OAuth/token API. Production is always https://prim.api.byob.studio.
• Project URLs are returned by BYOB at runtime:
  • preview_url
  • editor_url
  • deployment_url

Do not hardcode preview or editor hostnames when making tool decisions. Local development often returns VM/host URLs such as http://10.0.3.1:<port>. Production project runtime URLs normally use these host patterns:

• Editor: https://editor.<project_id>.api.byob.studio
• Preview: https://preview.<project_id>.api.byob.studio

Always prefer the exact URLs returned by byob_current_project_context, byob context, or _meta.byob_project, because custom domains, gateways, or future deployment routing can change the canonical URL.

Standard MCP Client Config

Most MCP clients accept a mcpServers entry with command, args, and env. Add:

{
  "mcpServers": {
    "byob": {
      "command": "npx",
      "args": ["-y", "byob-cli", "mcp"],
      "env": {
        "BYOB_PROJECT_ID": "<project_id>",
        "BYOB_AGENT_TOKEN": "<agent_access_token>"
      }
    }
  }
}

Generate the same shape locally:

byob config --project-id <project_id>

https://air.api.byob.studio and https://prim.api.byob.studio are the package defaults. Set BYOB_AIR_URL, BYOB_PRIM_URL, --air-url, or --prim-url only for local development or staging.

Use npx.cmd as the command on Windows if your MCP client does not resolve npx.

Codex Setup

For Codex users, prefer installing the BYOB Codex plugin. The plugin bundles:

• skills/byob_cli/SKILL.md
• .mcp.json, which starts the byob MCP server with npx -y byob-cli mcp

Plugin install makes the BYOB skills and MCP server available from one package. The user still needs to provide their project id and agent token, because those are user/project-specific secrets.

For the common MCP setup path, use the installer:

npx -y byob-cli codex install --client-name "Codex"

This follows the same wizard pattern used by many MCP providers: the npm package performs auth, writes the Codex MCP config, and installs the BYOB Codex skill into ~/.agents/skills/byob_cli. It makes BYOB tools available immediately through MCP server instructions and tool discovery, and makes $byob_cli available after Codex reloads skills or starts a new session.

Publishing byob-cli to npm makes the byob binary available to npx; it does not automatically create a Codex plugin marketplace. codex plugin add byob-cli@npm will fail unless a marketplace named npm has been configured and contains a plugin entry.

For local repo testing, add this repository marketplace from the repo root:

codex plugin marketplace add /path/to/byob
codex plugin add byob --marketplace byob-local

For distribution, publish a Codex marketplace JSON from a Git repo or share the plugin through the Codex app. Then users install from that marketplace, while the bundled .mcp.json uses npm only to launch the MCP binary.

Example plugin-scoped MCP config:

[plugins."<installed_byob_plugin_id>".mcp_servers.byob.env]
BYOB_PROJECT_ID = "<project_id>"
BYOB_AGENT_TOKEN = "<agent_access_token>"

For multiple projects:

[plugins."<installed_byob_plugin_id>".mcp_servers.byob.env]
BYOB_PROJECT_IDS = "<project_id_1>,<project_id_2>"
BYOB_CLI_MULTI_PROJECT = "1"
BYOB_AGENT_TOKEN = "<agent_access_token>"

Use the plugin id Codex shows after installation, for example byob or a marketplace-qualified id.

The bundled MCP server forwards BYOB_AIR_URL and BYOB_PRIM_URL when set, but production defaults are already https://air.api.byob.studio and https://prim.api.byob.studio.

Manual MCP Setup

If the user does not install the plugin, they can still add the stdio MCP server directly:

codex mcp add byob \
  --env BYOB_PROJECT_ID=<project_id> \
  --env BYOB_AGENT_TOKEN=<agent_access_token> \
  -- npx -y byob-cli mcp

Equivalent config.toml:

[mcp_servers.byob]
command = "npx"
args = ["-y", "byob-cli", "mcp"]

[mcp_servers.byob.env]
BYOB_PROJECT_ID = "<project_id>"
BYOB_AGENT_TOKEN = "<agent_access_token>"

Codex reads MCP server instructions returned during initialization. BYOB uses those instructions to tell Codex to establish project context on first BYOB use and after project switches. Context can come from _meta.byob_project, resource byob://project/<project_id>/context, byob_current_project_context, or byob context. Codex should show the user the active project name/id and preview URL when the active project was not already clear.

Important: npx -y byob-cli mcp starts the MCP server; it does not install Codex skills by itself. With only the MCP server configured, Codex learns about BYOB at runtime from:

• MCP initialize.instructions
• MCP tools/list
• MCP resources and _meta.byob_project where the host supports them

To make the SKILL.md workflow available to Codex as a skill, run byob codex install, install the BYOB Codex plugin, or place the skill folder in a Codex-scanned skills location. The installer copies the skill to ~/.agents/skills/byob_cli; the MCP server alone does not register that skill name. The main skill installs CODEX_CORE.md as a sidecar file and uses synced byob_* skills for reusable styling, framework, backend, and integration guidance.

This package includes Codex plugin scaffolding for that:

• .codex-plugin/plugin.json
• .mcp.json
• skills/byob_cli/SKILL.md

The local developer skill lives under local-skills/byob_cli_local/ and is not included in the production plugin manifest.

During local development, the repo marketplace is at .agents/plugins/marketplace.json.

Refreshing Codex Skills

Use this after BYOB updates AIR coding skills or when a Codex machine already has MCP configured:

npx -y byob-cli codex sync-skills --project-id <project_id> --token <agent_access_token>

codex sync-skills downloads AIR coding-skill resources and rewrites their local skill names with byob_ prefixes. It does not run OAuth, does not call codex mcp add, and does not change the active MCP server config.

Local Codex Billed

When a user chooses Local Codex billed, open the BYOB project as the active Codex workspace from the start of the edit session:

1. Call byob_codex_status for the selected project.
2. If Local Codex billed is available, call byob_codex_connection_create with mode: "local_codex_billed".
3. Hand the returned workspace_handle to the Codex host so /home/workspace/app_data becomes the active SSH workspace.
4. Keep tokens, private keys, and complete proxy commands out of chat.
5. Use Codex's normal file, shell, and git workflow inside that active workspace.

The underlying proxy command bridges OpenSSH stdio to AIR's authenticated WebSocket endpoint:

BYOB_CODEX_SSH_TOKEN=<connection_token> \
ssh -i <temporary_key_file> \
  -o ProxyCommand="npx -y byob-cli@latest codex ssh-proxy '{\"ssh_endpoint\":\"<ssh_endpoint>\"}'" \
  byob@byob-project

Agents and hosts should keep this user-facing: say "Local Codex billed", not internal labels such as ssh_gateway, unless debugging the connector itself.

Multiple Projects

BYOB grants can cover more than one approved project. There are two supported install shapes.

Recommended: One Server Per Project

Use one MCP entry per project when the client supports multiple servers. This is the clearest mode because every server has a stable project target and no tool-call routing ambiguity.

{
  "mcpServers": {
    "byob-web": {
      "command": "npx",
      "args": ["-y", "byob-cli", "mcp"],
      "env": {
        "BYOB_PROJECT_ID": "<web_project_id>",
        "BYOB_AGENT_TOKEN": "<agent_access_token>"
      }
    },
    "byob-admin": {
      "command": "npx",
      "args": ["-y", "byob-cli", "mcp"],
      "env": {
        "BYOB_PROJECT_ID": "<admin_project_id>",
        "BYOB_AGENT_TOKEN": "<agent_access_token>"
      }
    }
  }
}

Single Entry: Multi-Project Routing

Use one MCP entry only when the client cannot manage multiple BYOB servers cleanly. The bridge routes tools/call by arguments.project_id. Non-tool methods such as initialize, tools/list, and ping use the first configured project.

{
  "mcpServers": {
    "byob": {
      "command": "npx",
      "args": ["-y", "byob-cli", "mcp", "--multi-project"],
      "env": {
        "BYOB_PROJECT_IDS": "<project_id_1>,<project_id_2>",
        "BYOB_CLI_MULTI_PROJECT": "1",
        "BYOB_AGENT_TOKEN": "<agent_access_token>"
      }
    }
  }
}

For project-specific tools, pass project_id in the tool arguments:

byob call byob_project_status '{"project_id":"<project_id_2>"}'

Without project_id, the first configured project is the default. Use:

byob projects

to list projects approved for the grant.

Project switching is intentionally explicit. The bridge does not persist a mutable "current project" on disk; pass --project-id, set BYOB_PROJECT_ID, or include project_id in tool arguments.

OAuth

Request a device code:

byob device-code --client-name "My coding agent"

Open the returned verification_uri_complete, approve the project, then exchange:

byob token <device_code>

Refresh:

byob refresh <refresh_token>

Do not paste access or refresh tokens into chat, logs, or issue reports.

If the needed project is missing from byob projects, reconnect with the device flow and approve that project in BYOB.

CLI Smoke Checks

BYOB_PROJECT_ID=<project_id> \
BYOB_AGENT_TOKEN=<agent_access_token> \
byob tools

Common aliases:

byob status
byob context
byob start
byob deploy
byob billing
byob payment-url '{"topup":500}'
byob env-status
byob grants
byob dns

billing returns the current credit balance and plan. payment-url returns a BYOB pricing/top-up URL that can be shown directly to the user.

Call any tool directly:

byob call byob_project_status '{}'

Target another approved project for one command:

byob --project-id <other_project_id> status
byob call byob_project_status '{"project_id":"<other_project_id>"}'

Project Context Metadata

The MCP server exposes project metadata as both a real tool and a resource.

For Codex reliability, prefer the tool:

byob context

The underlying MCP tool is:

byob_current_project_context

Codex sees MCP tools reliably and receives BYOB server instructions telling it to call this tool when project context is needed.

Read another approved project:

byob context '{"project_id":"<other_project_id>"}'

For host UIs that support MCP resources, read the resource:

byob context-resource
byob context-resource '{"project_id":"<other_project_id>"}'

List resources:

byob resources

Resource URI shape:

byob://project/<project_id>/context

The context payload includes:

• project name
• project id
• status
• preview URL
• editor URL
• deployment URL
• publish slug
• updated/started timestamps

MCP responses also include _meta.byob_project where useful. Hosts can use that _meta for display without injecting it into model-visible text. Do not put the editor URL into prompts unless the user explicitly needs it.

Tool Notes

BYOB platform tools are exposed by Agent MCP:

• byob_current_project_context
• byob_list_projects
• byob_project_status
• byob_start_project
• byob_billing_status
• byob_payment_url
• byob_project_env_status
• byob_list_agent_grants
• byob_revoke_agent_grant
• byob_deploy_project
• byob_deployment_status
• byob_deployment_analytics
• byob_get_custom_domain
• byob_custom_domain_dns_instructions
• byob_set_custom_domain
• byob_delete_custom_domain
• byob_testing_browsers
• byob_browser_session_start
• byob_browser_action
• byob_browser_session_close

Project coding tools are discovered with tools/list and proxied into the selected project's private container MCP. After successful mutating coding tools such as edit_file, write_file, apply_patch, package changes, file moves, copies, or deletes, BYOB appends the current preview URL to the tool response when available. Agents should surface that preview URL after code changes.

Codex-driven browser testing is exposed as BYOB platform tools, not as raw container tools. byob_browser_action routes browser commands through the connected BYOB browser extension and supports navigation, screenshots, clicks, typing, DOM evaluation, selector waits, viewport resizing, console logs, and network capture. BYOB's internal delegate_testing chat/modal flow remains separate and is not advertised through Agent MCP.

Codex does not need BYOB browser tools for every test. For basic smoke checks, it can directly fetch or inspect the preview_url and combine that with BYOB preview/browser log tools. Use the BYOB Testing extension only when real browser interaction is needed: screenshots, clicks, typing, viewport checks, DOM evaluation, fresh console logs, or network capture.

If browser-extension testing is needed and no BYOB testing browser is connected, ask the user to install or open the BYOB Testing extension:

https://chromewebstore.google.com/detail/byob-testing/ncnaebcfklfpcapminohoiekcemmaalj

When a long-running build, image generation, package install, or deploy is already in progress, tell the user they can install the extension during that wait so Codex can test the preview afterward.

Included Skills

The production plugin includes one Codex skill:

• skills/byob_cli/SKILL.md

The local-only developer skill is kept at local-skills/byob_cli_local/SKILL.md for BYOB contributors testing a local stack. Do not include it in the production plugin build.