Core Concepts

Mounts & Inheritance

View as Markdown

Spaces define the resource boundary. Runtimes inherit that boundary from their space.

Space
  storage namespace
  vault prefixes
  AI connection allowlist
  browser resources
Runtime
  inherits the space boundary

Use space mounts to make durable resources available to runtimes and hosted invocations.

Storage

Use space storage for durable files: inputs, downloads, reports, screenshots, and artifacts.

1const space = await bctrl.spaces.create({
2  name: "invoice-agent",
3  mounts: {
4    storage: {
5      space: "shared-invoices",
6    },
7  },
8});
1const uploaded = await space.storage.files.upload(invoicePdf, {
2  path: "inputs/invoice.pdf",
3});

Storage paths are durable cloud paths. They are not runtime-local file paths. Use runtime file staging when a browser or agent needs a real file path inside the runtime.

1const staged = await runtime.files.stage({
2  fileId: uploaded.id,
3});
4
5console.log(staged.path);

Vault

Use the vault for credentials, API keys, and TOTP seeds.

1await bctrl.vault.set("clients/acme/quickbooks", {
2  username: "[email protected]",
3  password: process.env.QUICKBOOKS_PASSWORD!,
4  totp: process.env.QUICKBOOKS_TOTP_SEED!,
5});

Mount only the prefixes the space should access.

1const space = await bctrl.spaces.create({
2  name: "acme-invoice-ops",
3  mounts: {
4    vault: {
5      allow: ["clients/acme/"],
6    },
7  },
8});

AI connections

AI connections are provider credentials for hosted agent flows.

1const ai = await bctrl.aiConnections.create({
2  provider: "anthropic",
3  label: "Anthropic production",
4  apiKey: process.env.ANTHROPIC_API_KEY!,
5  defaultModel: "claude-sonnet-4-5",
6});
7
8const space = await bctrl.spaces.create({
9  name: "research-agent",
10  mounts: {
11    ai: {
12      allowConnections: [ai.id],
13      defaults: {
14        stagehand: {
15          connection: ai.id,
16          model: "claude-sonnet-4-5",
17        },
18      },
19    },
20  },
21});

Runtime configuration

Runtime configuration chooses the browser resources for a specific launch, such as profile, extensions, proxy, stealth, humanization, and CAPTCHA behavior.

1const runtime = await space.runtimes.browser.launch({
2  name: "quickbooks",
3  profile: "prof_sales_bot",
4  extensionIds: ["ext_internal_tools"],
5  config: {
6    stealth: "high",
7    humanize: true,
8    proxy: {
9      mode: "saved",
10      id: "proxy_us_residential",
11    },
12  },
13});