Upload & Download Files in Browser Agent Sessions

2 min read

How to move files in and out of cloud browser sessions — session files for a single run, global files for assets reused across every session.

Steel has two file scopes. Session files belong to an active browser environment; global files persist at the organization level and can be mounted into later sessions.

Use session files for uploads, downloads, and artifacts tied to one run. Use global files for inputs that several runs need.

Upload a file to a session

import fs from "node:fs";

const session = await client.sessions.create();

try {
  const uploaded = await client.sessions.files.upload(session.id, {
    file: fs.createReadStream("./input.csv"),
  });

  console.log(uploaded.path);
  // Use uploaded.path when setting the browser's file input.
} finally {
  await client.sessions.release(session.id);
}

Files uploaded to the session are available inside that browser environment. Browser downloads also appear through the session files interface.

Download the run's output

const files = await client.sessions.files.list(session.id);

for (const file of files.data) {
  console.log(file.path, file.size);
}

const archive = await client.sessions.files.downloadArchive(session.id);
const zip = await archive.blob();

Download the artifacts your application must retain before their storage policy expires. Keep the session ID, job ID, source URL, and artifact checksum beside the stored file.

Reuse a global file

const globalFile = await client.files.upload({
  file: fs.createReadStream("./reference.csv"),
});

const sessionFile = await client.sessions.files.upload(session.id, {
  file: globalFile.path,
});

Global storage avoids uploading the same input for every run. Keep tenant boundaries in your application: organization-wide availability does not mean every workflow should receive every file.

Security and retention

Files can contain personal data, exports from authenticated portals, or instructions that influence an agent. Apply the same controls used for other untrusted input:

  • validate file type and size;
  • scan or sandbox content before parsing;
  • keep authorization tied to the owning task or tenant;
  • avoid exposing raw storage paths in model prompts;
  • define retention and deletion outside the browser lifecycle.

Releasing a session ends browser execution, but it is not a data-retention policy.

Follow the Files API overview to upload one test file, list the session files, and download the resulting archive.