Space Storage | BCTRL Docs

Space storage is the durable file layer for a space. Use it for inputs, exports, CSVs, PDFs, screenshots, logs, and files that should be reused across runtimes, invocations, and runs.

The preferred SDK entrypoint is space.storage.files.

1 const space = await bctrl.spaces.get("spc_123");
2 
3 const uploaded = await space.storage.files.upload(csvBuffer, {
4   path: "inputs/report.csv",
5   contentType: "text/csv",
6 });

Upload a file

1 const file = await space.storage.files.upload(pdfBytes, {
2   path: "inputs/invoice.pdf",
3   contentType: "application/pdf",
4 });
5 
6 console.log(file.id, file.path);

Parameter	Type	Required	Description
`data`	`Buffer \| Uint8Array \| Blob`	Yes	File content.
`options.path`	`string`	No	Durable path inside the space.
`options.name`	`string`	No	Display filename. Defaults from `path` when omitted.
`options.contentType`	`string`	No	MIME type for the uploaded file.

List files

1 const { files, nextCursor } = await space.storage.files.list({
2   prefix: "inputs/",
3   limit: 20,
4 });
5 
6 for (const file of files) {
7   console.log(file.id, file.path, file.sizeBytes);
8 }

Parameter	Type	Required	Description
`prefix`	`string`	No	Restrict results to a path prefix.
`limit`	`number`	No	Max results.
`cursor`	`string`	No	Cursor from a previous page.

Get metadata

1 const file = await space.storage.files.get(uploaded.id);
2 console.log(file.path, file.contentType);

Download a file

1 const bytes = await space.storage.files.download(uploaded.id);

Delete a file

1 await space.storage.files.delete(uploaded.id);

Mount a storage namespace

Spaces can mount a shared storage namespace when several spaces should see the same durable files.

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

Space storage vs runtime files

Space storage is durable cloud storage.

Runtime files are files inside a live runtime. Use runtime file staging to move a storage file into a runtime, and collection to copy a runtime-local file back into storage.

1 const staged = await runtime.files.stage({
2   fileId: uploaded.id,
3 });
4 
5 const collected = await runtime.files.collect({
6   path: "/tmp/output.csv",
7   storagePath: "outputs/output.csv",
8 });