Spaces

A Space is the boundary around your automation resources. It groups Runtimes and defines the environment they can use: durable storage, Vault secrets, and AI credentials.

A Runtime inherits the environment of the Space it belongs to. Configure a capability once at the Space boundary when several Runtimes should share it.

Create a Space

The smallest valid request is an empty object:

const space = await bctrl.spaces.create({});
console.log(space.id);

Give the Space a name when you want a stable label in your application:

const space = await bctrl.spaces.create({
  name: "checkout-automation",
});

You can configure its environment at creation time:

const models = await bctrl.ai.models.list({
  status: "recommended",
});
const modelId = models.data[0]?.id;
if (!modelId) {
  throw new Error("No recommended Browser Use model is available");
}
const space = await bctrl.spaces.create({
  name: "checkout-automation",
  environment: {
    storage: { namespace: "checkout" },
    vault: { allow: ["checkout/"] },
    ai: {
      credentialIds: ["openai-production"],
      default: modelId,
    },
  },
});

Create fields

Space identity

The Space object includes its environment, so one response gives you both the Space identity and the capabilities available to its Runtimes.

Use the Space ID for resource operations. The literal "default" can be used where the API accepts a Space selector to address the caller’s default Space.

Space environment

An environment is a set of optional mounts. If a mount is omitted, that capability is not mounted into the Space.

Storage

Vault

Keep the allowlist narrow. Leave allowRawReads unset unless the workflow needs the secret value itself; many workflows only need Vault to provide a credential to a Tool.

AI

A string is the shorthand model form:

default: modelId

Use the object form when the selection needs explicit authentication or model controls:

default: {
  model: modelId,
  auth: { credential: "openai-production" },
  reasoningEffort: "medium",
}

AiStoredModelSelection has a required model and optional auth, provider, and model controls. auth can be "managed" or { credential: string }. When a saved credential is selected, its provider is used; do not send a separate provider with auth: { credential: ... }. The AI models page explains model selections and credentials in detail.

Read and update the environment

Read the environment from the Space object:

const current = await bctrl.spaces.get(space.id);
const environment = current.environment;
console.log(environment.storage?.namespace);
console.log(environment.vault?.allow);
console.log(environment.ai?.credentialIds);

Include environment in spaces.update() to patch the Space environment:

• Omit a mount to leave it unchanged.
• Send an object to add or replace a mount.
• Send null to remove a mount.

await bctrl.spaces.update(space.id, {
  name: "checkout-production",
  environment: {
    storage: { namespace: "checkout" },
    vault: {
      allow: ["checkout/"],
      deny: ["checkout/admin/"],
    },
    ai: {
      credentialIds: ["openai-production"],
      default: modelId,
    },
  },
});

For nested AI fields, the same patch rules apply. Omit a field to keep it, provide a value to set it, and use null to clear it:

await bctrl.spaces.update(space.id, {
  environment: {
    ai: {
      default: null,
    },
  },
});

To remove the complete mount:

await bctrl.spaces.update(space.id, {
  environment: {
    vault: null,
  },
});

Manage Spaces

const page = await bctrl.spaces.list({ limit: 50 });
const current = await bctrl.spaces.get(space.id);
await bctrl.spaces.update(space.id, {
  name: "checkout-production",
});
for await (const item of bctrl.spaces.iter()) {
  console.log(item.id, item.name);
}

Delete a Space only after its active Runtimes have stopped:

await bctrl.spaces.delete(space.id);

Use a Space with a Runtime

Pass spaceId when creating a Runtime. If you omit it, the Runtime uses the caller’s default Space.

const runtime = await bctrl.runtimes.create({
  spaceId: space.id,
});

Runtime-specific settings such as browser identity, proxy, and extensions belong in Runtimes.