Skip to content

Files

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

The Files API moves files between your machine and a session, whose browser runs on another machine and cannot open your files.

  • Session files are in one session's /files folder. You upload a file there so that a page can use it, and the files that the browser downloads are saved there. Steel keeps them after the session ends, so that you can download them.
  • Global files belong to your organization and do not depend on a session. Upload a file once, and copy it into any session.

Before you begin

Put your Steel API key in the STEEL_API_KEY environment variable. Then install the Steel SDK and Playwright.

npm install steel-sdk playwright

In Go and Rust, install only the SDK, as the Go and Rust SDK pages show. The code that drives the browser uses Playwright, so it is in TypeScript and Python only.

Upload a file to a session

Call client.sessions.files.upload with a running session's ID and the file. The response has the file's path in the session, its size in bytes and its lastModified time.

This program creates a session, uploads data.csv from the current folder, prints where the file is in the session, and releases the session.

upload.mts
import { createReadStream } from "node:fs";
import Steel from "steel-sdk";

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

try {
  const uploaded = await client.sessions.files.upload(session.id, {
    file: createReadStream("data.csv"),
    path: "data.csv",
  });
  console.log(uploaded.path, uploaded.size);
} finally {
  await client.sessions.release(session.id);
}

Run the program:

npx tsx upload.mts

The program prints the file's path in the session and its size.

/files/data.csv 2048

The program passes path to name the file. Steel does not use the name of the file that you upload. Without path, it gives the file a random ID as its name. To put the file in a folder, pass a path such as "reports/data.csv". To let Steel fetch the file, pass a public http:// or https:// URL in file instead of the content. The SDKs take only file content in file, so send that request without the SDK, as the example in Keep global files does.

You can upload only while the session runs.

Use the file on a page

Uploading puts the file in the session. A page still needs the file in its file input. Pass the path from the upload to the input with the CDP (Chrome DevTools Protocol) command DOM.setFileInputFiles. Put the import at the top of the program above, and the rest in its try block, after the upload. The code connects Playwright to the session and fills the file input with the ID load-file:

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP(session.websocketUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://www.csvplot.com/");

const cdp = await context.newCDPSession(page);
const document = await cdp.send("DOM.getDocument");
const input = await cdp.send("DOM.querySelector", {
  nodeId: document.root.nodeId,
  selector: "#load-file",
});
await cdp.send("DOM.setFileInputFiles", {
  files: [uploaded.path],
  nodeId: input.nodeId,
});

The page then reads the file as if a person had picked it. With Commands, the upload command does the same in one step. Pass it the session file's name.

Download files from a session

Files that the browser downloads are saved in /files, next to the files that you uploaded. client.sessions.files.list returns all of them. It works during the session and after you release it. List session files says in what order.

const files = await client.sessions.files.list(session.id);
for (const file of files.data) {
  console.log(file.path, file.size);
}
/files/report.pdf 589
/files/data.csv 3207

Playwright changes these names. When it connects over CDP, it tells the browser to save each download under a random ID, such as /files/ef4853ce-7350-4119-888e-861987165947, instead of the file's own name. To keep the names, reset the download behavior right after you connect:

const cdp = await browser.newBrowserCDPSession();
await cdp.send("Browser.setDownloadBehavior", { behavior: "default" });

To download one file, pass its path without the /files/ prefix, such as report.pdf. A path that starts with / fails.

import { writeFile } from "node:fs/promises";

const response = await client.sessions.files.download(session.id, "report.pdf");
await writeFile("report.pdf", Buffer.from(await response.arrayBuffer()));

To download all of the session's files as one zip file, call downloadArchive:

const archive = await client.sessions.files.downloadArchive(session.id);
await writeFile("session-files.zip", Buffer.from(await archive.arrayBuffer()));

Check the size or content of what you download. A click on a download button does not prove that the file arrived.

Keep global files

Upload a global file with client.files.upload. Pass path to name the file. Without it, Steel names the file with a random ID and the .bin extension. The response has the file's path.

import { createReadStream } from "node:fs";

const globalFile = await client.files.upload({
  file: createReadStream("data.csv"),
  path: "data.csv",
});
console.log(globalFile.path);
data.csv

To copy a global file into a session, upload to the session and pass the global file's path in file, instead of its content. The SDKs take only file content in file, and their types refuse a string there, so this code sends the request without the SDK. Without path, the session file gets the global file's name. In Python, the code uses httpx, which comes with steel-sdk.

const form = new FormData();
form.append("file", "data.csv");
const response = await fetch(
  `https://api.steel.dev/v1/sessions/${session.id}/files`,
  {
    method: "POST",
    headers: { "steel-api-key": process.env.STEEL_API_KEY! },
    body: form,
  },
);
const uploaded = await response.json();
console.log(uploaded.path);
/files/data.csv

client.files.list lists the global files, and client.files.download downloads one by its path, in the same way as for session files.

Delete files

Delete a session file by its path, without the /files/ prefix, or delete all of the session's files. You can delete session files only while the session runs.

await client.sessions.files.delete(session.id, "report.pdf");
await client.sessions.files.deleteAll(session.id);

Delete a global file by its path:

await client.files.delete("data.csv");

Check that it worked

List the session's files with client.sessions.files.list. The uploaded file is there, with the path /files/data.csv and the size that the upload printed. For a file that you download, compare the size of the file on your machine with its size in the list. When the two match, the whole file arrived.

Troubleshooting

A file path is required

{
  "error": "Bad Request",
  "message": "A file path is required. Provide a relative path with no leading '/' or '..' segments, e.g. 'downloads/report.pdf'.",
  "retryable": false,
  "linkToDocs": "https://docs.steel.dev/overview/files-api/overview"
}

Cause: The path starts with /, holds a .. segment, or is empty. This happens when you pass the path from an upload or a list, such as /files/report.pdf, to a download or a delete.

Fix: Remove the /files/ prefix, and pass report.pdf.

Verify: The download returns the file.

The session is not running

Cause: You uploaded or deleted a file after the session ended. The response has the status 409, and its message starts with Session 'SESSION_ID' is and the session's status.

Fix: Upload and delete files before you release the session. To list and download a released session's files, use the calls in Download files from a session.

Verify: The upload returns the file's path.

Next steps

  • Files API: List and download global files, and see what each call takes and returns.