Secure, Fast, and Extensible Sandbox runtime for AI agents.
// Copyright 2026 The OpenSandbox Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
import { createExecdClient, type ExecdClient } from "../openapi/execdClient.js";
import { throwOnOpenApiFetchError } from "./openapiError.js";
import type { SandboxFiles } from "../services/filesystem.js";
import type { paths as ExecdPaths } from "../api/execd.js";
import type {
ContentReplaceEntry,
ContentReplaceResult,
DirectoryListEntry,
FileInfo,
FileMetadata,
FilesInfoResponse,
MoveEntry,
Permission,
RenameFileItem,
ReplaceFileContentItem,
ReadBytesResponse,
ReadBytesStream,
SearchEntry,
SearchFilesResponse,
SetPermissionEntry,
WriteEntry,
} from "../models/filesystem.js";
import { SandboxApiException, SandboxError } from "../core/exceptions.js";
import { throwOnUploadFailure } from "./uploadFailure.js";
import { createReadBytesResponse, readResponseBody } from "./downloadResponse.js";
function joinUrl(baseUrl: string, pathname: string): string {
const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
const path = pathname.startsWith("/") ? pathname : `/${pathname}`;
return `${base}${path}`;
}
function toUploadBlob(data: Blob | Uint8Array | ArrayBuffer | string): Blob {
if (typeof data === "string") return new Blob([data]);
if (data instanceof Blob) return data;
if (data instanceof ArrayBuffer) return new Blob([data]);
// Copy into a new Uint8Array backed by ArrayBuffer (not SharedArrayBuffer)
const copied = Uint8Array.from(data);
return new Blob([copied.buffer]);
}
function isReadableStream(v: unknown): v is ReadableStream<Uint8Array> {
return !!v && typeof (v as any).getReader === "function";
}
function isAsyncIterable(v: unknown): v is AsyncIterable<Uint8Array> {
return !!v && typeof (v as any)[Symbol.asyncIterator] === "function";
}
function isNodeRuntime(): boolean {
const p = (globalThis as any)?.process;
return !!(p?.versions?.node);
}
async function collectBytes(
source: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>
): Promise<Uint8Array> {
const chunks: Uint8Array[] = [];
let total = 0;
if (isReadableStream(source)) {
const reader = source.getReader();
try {
while (true) {
const { done, value } = await reader.read();
if (done) break;
if (value) {
chunks.push(Uint8Array.from(value));
total += value.length;
}
}
} finally {
reader.releaseLock();
}
} else {
for await (const chunk of source) {
chunks.push(Uint8Array.from(chunk));
total += chunk.length;
}
}
const out = new Uint8Array(total);
let offset = 0;
for (const chunk of chunks) {
out.set(chunk, offset);
offset += chunk.length;
}
return out;
}
function toReadableStream(
it: AsyncIterable<Uint8Array>
): ReadableStream<Uint8Array> {
const RS: any = ReadableStream as any;
if (typeof RS?.from === "function") return RS.from(it);
const iterator = it[Symbol.asyncIterator]();
return new ReadableStream<Uint8Array>({
async pull(controller) {
const r = await iterator.next();
if (r.done) {
controller.close();
return;
}
controller.enqueue(r.value);
},
async cancel() {
await iterator.return?.();
},
});
}
function basename(p: string): string {
const parts = p.split("/").filter(Boolean);
return parts.length ? parts[parts.length - 1] : "file";
}
function encodeUtf8(s: string): Uint8Array {
return new TextEncoder().encode(s);
}
// `filename` is a quoted-string header parameter, so a backslash, a quote or a
// line break in the basename would truncate the part header and make the whole
// body unparseable.
//
// The backslash opens a quoted-pair, so it has to be doubled the way
// `multipart.CreateFormFile` does on the Go side and `_multipart_header_filename`
// does on the Python side; it is escaped first so it does not double the
// backslashes we introduce. The remaining three are escaped the way the platform
// `FormData` used on the in-memory path below does, so the two upload paths emit
// the same header for the characters `FormData` handles.
function multipartHeaderFilename(filename: string): string {
return filename
.replace(/\\/g, "\\\\")
.replace(/\r/g, "%0D")
.replace(/\n/g, "%0A")
.replace(/"/g, "%22");
}
async function* multipartUploadBody(opts: {
boundary: string;
metadataJson: string;
fileName: string;
fileContentType: string;
file: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
}): AsyncIterable<Uint8Array> {
const b = opts.boundary;
// Part 1: metadata (application/json)
yield encodeUtf8(`--${b}\r\n`);
yield encodeUtf8(
`Content-Disposition: form-data; name="metadata"; filename="metadata"\r\n`
);
yield encodeUtf8(`Content-Type: application/json\r\n\r\n`);
yield encodeUtf8(opts.metadataJson);
yield encodeUtf8(`\r\n`);
// Part 2: file
yield encodeUtf8(`--${b}\r\n`);
yield encodeUtf8(
`Content-Disposition: form-data; name="file"; filename="${multipartHeaderFilename(opts.fileName)}"\r\n`
);
yield encodeUtf8(`Content-Type: ${opts.fileContentType}\r\n\r\n`);
if (isReadableStream(opts.file)) {
const reader = opts.file.getReader();
try {
while (true) {
const { done, value } = await reader.read();
if (done) break;
if (value) yield Uint8Array.from(value);
}
} finally {
reader.releaseLock();
}
} else {
for await (const chunk of opts.file) {
yield Uint8Array.from(chunk);
}
}
yield encodeUtf8(`\r\n--${b}--\r\n`);
}
export interface FilesystemAdapterOptions {
/**
* Must match the baseUrl used by the ExecdClient, used for binary endpoints
* like download/upload where we bypass JSON parsing.
*/
baseUrl: string;
fetch?: typeof fetch;
/**
* No-overall-timeout fetch used for uploads, whose request body is produced
* by the caller and may take longer than the connection's request timeout.
* See `ConnectionConfig.uploadFetch`. Falls back to `fetch`.
*/
uploadFetch?: typeof fetch;
headers?: Record<string, string>;
}
function toPermission(e: {
mode?: number;
owner?: string;
group?: string;
}): Permission {
return {
mode: e.mode ?? 755,
owner: e.owner,
group: e.group,
} as Permission;
}
/**
* Filesystem adapter that exposes user-facing file APIs (`sandbox.files`).
*
* This adapter owns all request/response conversions:
* - Maps friendly method shapes to API payloads
* - Parses timestamps into `Date`
* - Implements streaming upload/download helpers
*/
export class FilesystemAdapter implements SandboxFiles {
private static readonly MAX_IDENTITY_ID = 4294967294;
// Assert that every generated identity route starts with this prefix.
private static readonly identityBasePath:
Extract<keyof ExecdPaths, `/v1/filesystem/${string}`> extends never
? never
: Exclude<
Extract<keyof ExecdPaths, `/v1/filesystem/${string}`>,
`/v1/filesystem/{uid}/{gid}/${string}`
> extends never ? "/v1/filesystem/{uid}/{gid}" : never =
"/v1/filesystem/{uid}/{gid}";
private static identityPath(uid: number, gid: number): string {
return FilesystemAdapter.identityBasePath
.replace("{uid}", String(uid))
.replace("{gid}", String(gid));
}
private readonly fetch: typeof fetch;
private readonly uploadFetch: typeof fetch;
private static readonly Api = {
// This is intentionally derived from OpenAPI schema types so API changes surface quickly.
SearchFilesOk:
null as unknown as ExecdPaths["/files/search"]["get"]["responses"][200]["content"]["application/json"],
FilesInfoOk:
null as unknown as ExecdPaths["/files/info"]["get"]["responses"][200]["content"]["application/json"],
ListDirectoryOk:
null as unknown as ExecdPaths["/directories/list"]["get"]["responses"][200]["content"]["application/json"],
MakeDirsRequest:
null as unknown as ExecdPaths["/directories"]["post"]["requestBody"]["content"]["application/json"],
SetPermissionsRequest:
null as unknown as ExecdPaths["/files/permissions"]["post"]["requestBody"]["content"]["application/json"],
MoveFilesRequest:
null as unknown as ExecdPaths["/files/mv"]["post"]["requestBody"]["content"]["application/json"],
ReplaceContentsRequest:
null as unknown as ExecdPaths["/files/replace"]["post"]["requestBody"]["content"]["application/json"],
ReplaceContentsOk:
null as unknown as ExecdPaths["/files/replace"]["post"]["responses"][200]["content"]["application/json"],
};
constructor(
private readonly client: ExecdClient,
private readonly opts: FilesystemAdapterOptions,
private readonly identityBaseUrl: string = opts.baseUrl
) {
this.fetch = opts.fetch ?? fetch;
this.uploadFetch = opts.uploadFetch ?? this.fetch;
}
withIdentity(uid: number, gid: number): SandboxFiles {
for (const [name, value] of [["uid", uid], ["gid", gid]] as const) {
if (!Number.isInteger(value) || value < 0 || value > FilesystemAdapter.MAX_IDENTITY_ID) {
throw new RangeError(name + " must be an integer between 0 and " + FilesystemAdapter.MAX_IDENTITY_ID);
}
}
const opts = {
...this.opts,
baseUrl: this.identityBaseUrl.replace(/\/+$/, "") +
FilesystemAdapter.identityPath(uid, gid),
};
return new FilesystemAdapter(createExecdClient(opts), opts, this.identityBaseUrl);
}
private parseIsoDate(field: string, v: unknown): Date {
if (typeof v !== "string" || !v) {
throw new Error(`Invalid ${field}: expected ISO string, got ${typeof v}`);
}
const d = new Date(v);
if (Number.isNaN(d.getTime())) {
throw new Error(`Invalid ${field}: ${v}`);
}
return d;
}
private static readonly _ApiFileInfo =
null as unknown as (typeof FilesystemAdapter.Api.SearchFilesOk)[number];
private mapApiFileInfo(raw: typeof FilesystemAdapter._ApiFileInfo): FileInfo {
const { path, type, size, created_at, modified_at, mode, owner, group, ...rest } =
raw;
return {
...rest,
path,
type,
size,
mode,
owner,
group,
createdAt: created_at
? this.parseIsoDate("createdAt", created_at)
: undefined,
modifiedAt: modified_at
? this.parseIsoDate("modifiedAt", modified_at)
: undefined,
};
}
async getFileInfo(paths: string[]): Promise<Record<string, FileInfo>> {
const { data, error, response } = await this.client.GET("/files/info", {
params: { query: { path: paths } },
});
throwOnOpenApiFetchError({ error, response }, "Get file info failed");
const raw = data as typeof FilesystemAdapter.Api.FilesInfoOk | undefined;
if (!raw) return {} as FilesInfoResponse;
if (typeof raw !== "object") {
throw new Error(
`Get file info failed: unexpected response shape (got ${typeof raw})`
);
}
const out: Record<string, FileInfo> = {};
for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
if (!v || typeof v !== "object") {
throw new Error(
`Get file info failed: invalid file info for path=${k}`
);
}
out[k] = this.mapApiFileInfo(v as typeof FilesystemAdapter._ApiFileInfo);
}
return out as FilesInfoResponse;
}
async deleteFiles(paths: string[]): Promise<void> {
const { error, response } = await this.client.DELETE("/files", {
params: { query: { path: paths } },
});
throwOnOpenApiFetchError({ error, response }, "Delete files failed");
}
async createDirectories(
entries: Pick<WriteEntry, "path" | "mode" | "owner" | "group">[]
): Promise<void> {
const map: Record<string, Permission> = {};
for (const e of entries) {
map[e.path] = toPermission(e);
}
const body = map as unknown as typeof FilesystemAdapter.Api.MakeDirsRequest;
const { error, response } = await this.client.POST("/directories", {
body,
});
throwOnOpenApiFetchError({ error, response }, "Create directories failed");
}
async deleteDirectories(paths: string[]): Promise<void> {
const { error, response } = await this.client.DELETE("/directories", {
params: { query: { path: paths } },
});
throwOnOpenApiFetchError({ error, response }, "Delete directories failed");
}
async listDirectory(entry: DirectoryListEntry): Promise<FileInfo[]> {
const { data, error, response } = await this.client.GET("/directories/list", {
params: { query: { path: entry.path, depth: entry.depth } },
});
throwOnOpenApiFetchError({ error, response }, "List directory failed");
const ok = data as typeof FilesystemAdapter.Api.ListDirectoryOk | undefined;
if (!ok) return [];
if (!Array.isArray(ok)) {
throw new Error(
`List directory failed: unexpected response shape (expected array, got ${typeof ok})`
);
}
return ok.map((x) => this.mapApiFileInfo(x));
}
async setPermissions(entries: SetPermissionEntry[]): Promise<void> {
const req: Record<string, Permission> = {};
for (const e of entries) {
req[e.path] = toPermission(e);
}
const body =
req as unknown as typeof FilesystemAdapter.Api.SetPermissionsRequest;
const { error, response } = await this.client.POST("/files/permissions", {
body,
});
throwOnOpenApiFetchError({ error, response }, "Set permissions failed");
}
async moveFiles(entries: MoveEntry[]): Promise<void> {
const req: RenameFileItem[] = entries.map((e) => ({
src: e.src,
dest: e.dest,
}));
const body =
req as unknown as typeof FilesystemAdapter.Api.MoveFilesRequest;
const { error, response } = await this.client.POST("/files/mv", {
body,
});
throwOnOpenApiFetchError({ error, response }, "Move files failed");
}
async replaceContents(entries: ContentReplaceEntry[]): Promise<void> {
const req: Record<string, ReplaceFileContentItem> = {};
for (const e of entries) {
req[e.path] = { old: e.oldContent, new: e.newContent };
}
const body =
req as unknown as typeof FilesystemAdapter.Api.ReplaceContentsRequest;
const { error, response } = await this.client.POST("/files/replace", {
body,
parseAs: "text",
});
throwOnOpenApiFetchError({ error, response }, "Replace contents failed");
}
async replaceContentsDetailed(entries: ContentReplaceEntry[]): Promise<ContentReplaceResult[]> {
const req: Record<string, ReplaceFileContentItem> = {};
for (const e of entries) {
req[e.path] = { old: e.oldContent, new: e.newContent };
}
const body =
req as unknown as typeof FilesystemAdapter.Api.ReplaceContentsRequest;
const { data, error, response } = await this.client.POST("/files/replace", {
params: { query: { verbose: true } },
body,
parseAs: "text",
});
throwOnOpenApiFetchError({ error, response }, "Replace contents failed");
const text = data?.trim() ?? "";
if (!text) return [];
let ok: typeof FilesystemAdapter.Api.ReplaceContentsOk | undefined;
try {
ok = JSON.parse(text) as typeof FilesystemAdapter.Api.ReplaceContentsOk;
} catch (e) {
throw new Error(
`Replace contents failed: unexpected response shape (${e instanceof Error ? e.message : String(e)})`
);
}
if (typeof ok !== "object" || ok === null || Array.isArray(ok)) {
throw new Error("Replace contents failed: unexpected response shape (expected object)");
}
return Object.entries(ok).map(([path, result]) => {
const replacedCount = (result as { replacedCount?: unknown } | null)?.replacedCount;
if (typeof replacedCount !== "number") {
throw new Error(
`Replace contents failed: unexpected response shape (invalid entry for ${path})`
);
}
return { path, replacedCount };
});
}
async search(entry: SearchEntry): Promise<SearchFilesResponse> {
const { data, error, response } = await this.client.GET("/files/search", {
params: { query: { path: entry.path, pattern: entry.pattern } },
});
throwOnOpenApiFetchError({ error, response }, "Search files failed");
// Make the OpenAPI contract explicit (and fail loudly on unexpected shapes).
const ok = data as typeof FilesystemAdapter.Api.SearchFilesOk | undefined;
if (!ok) return [];
if (!Array.isArray(ok)) {
throw new Error(
`Search files failed: unexpected response shape (expected array, got ${typeof ok})`
);
}
return ok.map((x) => this.mapApiFileInfo(x));
}
private async uploadFile(
meta: FileMetadata,
data:
| Blob
| Uint8Array
| ArrayBuffer
| string
| AsyncIterable<Uint8Array>
| ReadableStream<Uint8Array>
): Promise<void> {
const url = joinUrl(this.opts.baseUrl, "/files/upload");
const fileName = basename(meta.path);
const metadataJson = JSON.stringify(meta);
// Streaming path (large files): build multipart body manually to avoid buffering.
if (isReadableStream(data) || isAsyncIterable(data)) {
// Browsers do not allow streaming multipart requests with custom boundaries.
// Fall back to in-memory uploads when streaming is unavailable.
if (!isNodeRuntime()) {
const bytes = await collectBytes(data);
return await this.uploadFile(meta, bytes);
}
const boundary = `opensandbox_${Math.random()
.toString(16)
.slice(2)}_${Date.now()}`;
const bodyIt = multipartUploadBody({
boundary,
metadataJson,
fileName,
fileContentType: "application/octet-stream",
file: data,
});
const stream = toReadableStream(bodyIt);
const res = await this.uploadFetch(url, {
method: "POST",
headers: {
"content-type": `multipart/form-data; boundary=${boundary}`,
...(this.opts.headers ?? {}),
},
body: stream as any,
// Node fetch (undici) requires duplex for streaming request bodies.
duplex: "half" as any,
// Uploads never follow redirects: the multipart body cannot always be
// replayed, and a redirect could otherwise replay credentials. A 3xx is
// surfaced below as a SandboxApiException with the original status.
redirect: "manual" as RequestRedirect,
} as any);
await throwOnUploadFailure(res);
return;
}
// In-memory path (small files): use FormData.
const form = new FormData();
form.append(
"metadata",
new Blob([metadataJson], { type: "application/json" }),
"metadata"
);
if (typeof data === "string") {
const textBlob = new Blob([data], { type: "text/plain; charset=utf-8" });
form.append("file", textBlob, fileName);
} else {
const blob = toUploadBlob(data);
const fileBlob = blob.type
? blob
: new Blob([blob], { type: "application/octet-stream" });
form.append("file", fileBlob, fileName);
}
const res = await this.uploadFetch(url, {
method: "POST",
headers: {
...(this.opts.headers ?? {}),
},
body: form,
// Uploads never follow redirects (see the streaming path above).
redirect: "manual",
});
await throwOnUploadFailure(res);
}
async readBytes(
path: string,
opts?: { range?: string; offset?: number; limit?: number }
): Promise<Uint8Array> {
return (await this.readBytesDetailed(path, opts)).body;
}
async readBytesDetailed(
path: string,
opts?: { range?: string; offset?: number; limit?: number }
): Promise<ReadBytesResponse<Uint8Array>> {
const res = await this.fetchDownload(path, opts, "Download failed");
const ab = await res.arrayBuffer();
return createReadBytesResponse(
res,
new Uint8Array(ab),
opts?.offset != null || opts?.limit != null,
);
}
readBytesStream(
path: string,
opts?: { range?: string; offset?: number; limit?: number }
): AsyncIterable<Uint8Array> {
return this.downloadStream(path, opts);
}
async readBytesStreamDetailed(
path: string,
opts?: { range?: string; offset?: number; limit?: number }
): Promise<ReadBytesResponse<ReadBytesStream>> {
const res = await this.fetchDownload(path, opts, "Download stream failed");
return createReadBytesResponse(
res,
readResponseBody(res),
opts?.offset != null || opts?.limit != null,
);
}
private async fetchDownload(
path: string,
opts: { range?: string; offset?: number; limit?: number } | undefined,
errorMessage: string,
): Promise<Response> {
let url =
joinUrl(this.opts.baseUrl, "/files/download") +
`?path=${encodeURIComponent(path)}`;
if (opts?.offset != null) url += `&offset=${opts.offset}`;
if (opts?.limit != null) url += `&limit=${opts.limit}`;
const res = await this.fetch(url, {
method: "GET",
headers: {
...(this.opts.headers ?? {}),
...(opts?.range ? { Range: opts.range } : {}),
},
});
if (!res.ok) {
const requestId = res.headers.get("x-request-id") ?? undefined;
const rawBody = await res.text().catch(() => undefined);
throw new SandboxApiException({
message: errorMessage,
statusCode: res.status,
requestId,
error: new SandboxError(
SandboxError.UNEXPECTED_RESPONSE,
errorMessage
),
rawBody,
});
}
return res;
}
private async *downloadStream(
path: string,
opts?: { range?: string; offset?: number; limit?: number }
): AsyncIterable<Uint8Array> {
const response = await this.readBytesStreamDetailed(path, opts);
yield* response.body;
}
async readFile(
path: string,
opts?: { encoding?: string; range?: string; offset?: number; limit?: number }
): Promise<string> {
const bytes = await this.readBytes(path, { range: opts?.range, offset: opts?.offset, limit: opts?.limit });
const encoding = opts?.encoding ?? "utf-8";
return new TextDecoder(encoding).decode(bytes);
}
async writeFiles(entries: WriteEntry[]): Promise<void> {
for (const e of entries) {
const meta: FileMetadata = {
path: e.path,
owner: e.owner,
group: e.group,
mode: e.mode,
};
await this.uploadFile(meta, e.data ?? "");
}
}
}