Filesystem

Filesystem endpoints let you list, read, write, move, copy, delete, and search files inside a running sandbox. File content is transferred as raw binary bytes.

List files

List directory entries.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
result = sandbox.filesystem.ls(
  path="/workspace",
  recursive=False,
  exclude=["node_modules", ".git"],
)

print(len(result.items))

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/ls`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({ path: "/workspace", recursive: false, exclude: ["node_modules", ".git"] }),
})

const data = await res.json()
console.log(data.items?.length ?? 0)

Stat path

Get metadata for a single path.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
info = sandbox.filesystem.stat(path="/workspace/main.py")
print(info.size)

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/stat`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({ path: "/workspace/main.py" }),
})

const data = await res.json()
console.log(data.size)

Make directory

Create a directory. Set recursive to create parent directories.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
sandbox.filesystem.mkdir(
  path="/workspace/src",
  recursive=True,
  permissions="755",
)

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/mkdir`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({ path: "/workspace/src", recursive: true, permissions: "755" }),
})

console.log(res.status)

Write file

Write raw binary content to a single path. The file path is passed as a query parameter and the request body is the raw file bytes.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
sandbox.filesystem.write_bytes(
  path="/workspace/hello.txt",
  content=b"Hello, world!",
  permissions="644",
)

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/write-file?path=/workspace/hello.txt&permissions=644`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/octet-stream",
},
body: new TextEncoder().encode("Hello, world!"),
})

console.log(res.status)

Write multiple files

Write multiple files in a single request using multipart/form-data. Each part’s name is the file path and the body is the raw file bytes.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
sandbox.filesystem.write_files_bytes(
  files={
      "/workspace/a.txt": b"a",
      "/workspace/b.txt": b"b",
  }
)

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const form = new FormData()
form.append("/workspace/a.txt", new Blob(["a"]))
form.append("/workspace/b.txt", new Blob(["b"]))

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/write-files`, {
method: "POST",
headers: { authorization: apiKey },
body: form,
})

console.log(res.status)

Read file

Read a single file. The response body contains the raw file bytes with content type application/octet-stream.

Use head to read only the first N lines or tail to read only the last N lines. These options are mutually exclusive.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()

print(sandbox.filesystem.read_bytes(path="/workspace/main.py"))
print(sandbox.filesystem.read_bytes(path="/workspace/main.py", head=20))
print(sandbox.filesystem.read_bytes(path="/workspace/main.py", tail=10))

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

// Full file
const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/read-file`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({ path: "/workspace/main.py" }),
})

const content = new Uint8Array(await res.arrayBuffer())
console.log(new TextDecoder().decode(content))

// First 20 lines
const headRes = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/read-file`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({ path: "/workspace/main.py", head: 20 }),
})

console.log(await headRes.text())

// Last 10 lines
const tailRes = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/read-file`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({ path: "/workspace/main.py", tail: 10 }),
})

console.log(await tailRes.text())

Read multiple files

Read multiple files. The response is multipart/form-data where each part’s name is the file path and the body is the raw file bytes.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
files = sandbox.filesystem.read_files_bytes(
  paths=["/workspace/a.txt", "/workspace/b.txt"],
)

for path, content in files.items():
  print(path, content)

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/read-files`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({ paths: ["/workspace/a.txt", "/workspace/b.txt"] }),
})

const formData = await res.formData()
for (const [name, value] of formData.entries()) {
console.log(name, await value.text())
}

Delete path

Delete a file or directory. Set recursive for directories with contents.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
sandbox.filesystem.delete(path="/workspace/old", recursive=True)

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/delete`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({ path: "/workspace/old", recursive: true }),
})

console.log(res.status)

Set permissions

Set file mode and optionally change owner and group.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
sandbox.filesystem.set_permissions(
  path="/workspace/script.sh",
  mode="755",
  owner="root",
  group="root",
)

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/set-permissions`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({
  path: "/workspace/script.sh",
  mode: "755",
  owner: "root",
  group: "root",
}),
})

console.log(res.status)

Glob

Find file paths matching a glob pattern.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
matches = sandbox.filesystem.glob(
  path="/workspace",
  pattern="*.ts",
  exclude=["node_modules"],
)

print(len(matches))

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/glob`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({ path: "/workspace", pattern: "*.ts", exclude: ["node_modules"] }),
})

const data = await res.json()
console.log(data.items?.length ?? 0)

Grep

Search for a text pattern across files in a directory.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
matches = sandbox.filesystem.grep(
  path="/workspace",
  pattern="TODO",
  include="*.py",
  exclude=["node_modules", ".git"],
)

print(len(matches))

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/grep`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({ path: "/workspace", pattern: "TODO", include: "*.py", exclude: ["node_modules", ".git"] }),
})

const data = await res.json()
console.log(data.items?.length ?? 0)

Edit file

Apply one or more find-and-replace edits to a single file. The response includes a unified diff and the total number of replacements made.

Python
JavaScript & TypeScript

from leap0 import FileEdit, Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
result = sandbox.filesystem.edit_file(
  path="/workspace/main.py",
  edits=[
      FileEdit(find="hello", replace="hi"),
      FileEdit(find="world", replace="earth"),
  ],
)

print(result.diff)
print(result.replacements)

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/edit-file`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({
  path: "/workspace/main.py",
  edits: [
    { find: "hello", replace: "hi" },
    { find: "world", replace: "earth" },
  ],
}),
})

const data = await res.json()
console.log(data.diff)
console.log(data.replacements)

Edit files

Replace text across multiple files at once.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
results = sandbox.filesystem.edit_files(
  paths=["/workspace/a.py", "/workspace/b.py"],
  find="old_name",
  replace="new_name",
)

print(len(results))

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/edit-files`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({
  files: ["/workspace/a.py", "/workspace/b.py"],
  find: "old_name",
  replace: "new_name",
}),
})

const data = await res.json()
console.log(data.items?.length ?? 0)

Move path

Move or rename a file or directory.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
sandbox.filesystem.move(
  src_path="/workspace/old.txt",
  dst_path="/workspace/new.txt",
  overwrite=False,
)

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/move`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({ src_path: "/workspace/old.txt", dst_path: "/workspace/new.txt", overwrite: false }),
})

console.log(res.status)

Copy

Copy a file or directory. Set recursive to copy directories with contents.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
sandbox.filesystem.copy(
  src_path="/home/user/file.txt",
  dst_path="/home/user/file-copy.txt",
  recursive=False,
  overwrite=False,
)

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/copy`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({
  src_path: "/home/user/file.txt",
  dst_path: "/home/user/file-copy.txt",
  recursive: false,
  overwrite: false,
}),
})

console.log(res.status)

Exists

Check whether a path exists in the sandbox.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
print(sandbox.filesystem.exists(path="/workspace/main.py"))

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/exists`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({ path: "/workspace/main.py" }),
})

const data = await res.json()
console.log(data.exists)

Tree

Get a recursive directory tree. Use exclude to skip directories and max_depth to limit traversal depth. The response is JSON: {"items": [{"name": "src", "type": "directory", "children": [...]}, ...]}.

Python
JavaScript & TypeScript

from leap0 import Leap0Client

client = Leap0Client()
sandbox = client.sandboxes.create()
tree = sandbox.filesystem.tree(
  path="/workspace",
  exclude=["node_modules", ".git"],
  max_depth=3,
)

print(tree.items)

const apiUrl = "https://api.leap0.dev"
const apiKey = "<your-api-key>"
const sandboxId = "<sandbox_id>"

const res = await fetch(`${apiUrl}/v1/sandbox/${sandboxId}/filesystem/tree`, {
method: "POST",
headers: {
  authorization: apiKey,
  "Content-Type": "application/json",
},
body: JSON.stringify({ path: "/workspace", exclude: ["node_modules", ".git"], max_depth: 3 }),
})

const data = await res.json()
console.log(data.items)