Spaces

A space controls which resources the runtimes inside it can reach: a storage namespace, vault secrets, and AI provider credentials. Mount what a space needs once, and every runtime you launch inside it inherits that environment.

Create a space

1
const space = await bctrl.spaces.create({ name: "invoice-agent" });

Pass environment to mount resources at creation time:

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

• storage.namespace - the storage namespace runtimes read and write.
• vault.allow - key prefixes runtimes may decrypt from the vault.
• ai - the AI providers runtimes may use; shaped as { aiProviderIds, defaults: { stagehand, browserUse } }.

List and read

1
const { data } = await bctrl.spaces.list();
2
3
for await (const space of bctrl.spaces.iter()) {
4
  console.log(space.id, space.name);
5
}
6
7
const one = await bctrl.spaces.get(space.id);

list returns one page with a cursor; iter walks every page for you. See Pagination.

Update and delete

1
await bctrl.spaces.update(space.id, { name: "invoice-agent-prod" });
2
await bctrl.spaces.delete(space.id);

Manage the environment

Read or change a space’s mounts after creation:

1
const env = await bctrl.spaces.environment.get(space.id);
2
3
await bctrl.spaces.environment.update(space.id, {
4
  vault: { allow: ["clients/acme/", "shared/"] },
5
});

Launch runtimes in a space

Pass spaceId when creating a runtime so it inherits the space environment:

1
const runtime = await bctrl.runtimes.create({
2
  spaceId: space.id,
3
  type: "browser",
4
  name: "main",
5
});

Next

• Runtimes - launch and configure cloud browsers
• Vault - secrets a space can mount
• Subaccounts - isolate spaces per customer