Filesystem Operations

The Filesystem API provides comprehensive file and directory management capabilities within the sandbox, including CRUD operations, permission management, search, and batch operations.

Get File Metadata

curl -X GET "http://localhost:44772/files/info?path=/workspace/file.txt" \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

Retrieves detailed metadata for one or multiple files including permissions, owner, group, size, and modification time.

path

array

required

File path(s) to get info for (can be specified multiple times)

[path]

object

Map of file paths to FileInfo objects

Show FileInfo properties

path

string

Absolute file path

size

integer

File size in bytes

modified_at

string

Last modification time (RFC3339 format)

created_at

string

File creation time (RFC3339 format)

owner

string

File owner username

group

string

File group name

mode

integer

File permissions in octal format (e.g., 755)

{
  "/workspace/file.txt": {
    "path": "/workspace/file.txt",
    "size": 2048,
    "modified_at": "2025-11-16T14:30:45Z",
    "created_at": "2025-11-16T14:30:45Z",
    "owner": "admin",
    "group": "admin",
    "mode": 644
  },
  "/workspace/data.csv": {
    "path": "/workspace/data.csv",
    "size": 10240,
    "modified_at": "2025-11-16T15:20:10Z",
    "created_at": "2025-11-16T15:20:10Z",
    "owner": "admin",
    "group": "admin",
    "mode": 644
  }
}

Delete Files

curl -X DELETE "http://localhost:44772/files?path=/workspace/temp.txt" \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

Deletes one or multiple files from the sandbox. Only removes files, not directories. Use DELETE /directories for directory removal.

path

array

required

File path(s) to delete (can be specified multiple times)

{}

Change File Permissions

curl -X POST http://localhost:44772/files/permissions \
  -H "X-EXECD-ACCESS-TOKEN: your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "/workspace/script.sh": {
      "owner": "admin",
      "group": "admin",
      "mode": 755
    },
    "/workspace/config.json": {
      "owner": "admin",
      "group": "admin",
      "mode": 644
    }
  }'

Changes permissions (mode), owner, and group for one or multiple files. Accepts a map of file paths to permission settings.

[path]

object

required

Map of file paths to Permission objects

Show Permission properties

owner

string

Owner username

group

string

Group name

mode

integer

required

Permission mode in octal format (e.g., 644, 755)

{}

Rename or Move Files

curl -X POST http://localhost:44772/files/mv \
  -H "X-EXECD-ACCESS-TOKEN: your-token" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "src": "/workspace/old_name.txt",
      "dest": "/workspace/new_name.txt"
    },
    {
      "src": "/workspace/file.py",
      "dest": "/archive/file.py"
    }
  ]'

Renames or moves one or multiple files to new paths. Can be used for both renaming within the same directory and moving to different directories. Target directory must exist.

operations

array

required

Array of rename/move operations

Show Operation properties

src

string

required

Source file path

dest

string

required

Destination file path

{}

Search for Files

curl -X GET "http://localhost:44772/files/search?path=/workspace" \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

Searches for files matching a glob pattern within a specified directory and its subdirectories. Returns file metadata including path, permissions, owner, and group.

path

string

required

Root directory path to search in

pattern

string

default:"**"

Glob pattern to match files. Supports patterns like:

** - All files recursively
*.txt - All .txt files in directory
**/*.py - All .py files recursively
test_*.py - Files starting with “test_”

files

array

Array of matching FileInfo objects

Show FileInfo properties

path

string

Absolute file path

size

integer

File size in bytes

modified_at

string

Last modification time

created_at

string

File creation time

owner

string

File owner username

group

string

File group name

mode

integer

File permissions in octal format

[
  {
    "path": "/workspace/main.py",
    "size": 1024,
    "modified_at": "2025-11-16T14:30:45Z",
    "created_at": "2025-11-16T14:30:45Z",
    "owner": "admin",
    "group": "admin",
    "mode": 644
  },
  {
    "path": "/workspace/tests/test_main.py",
    "size": 512,
    "modified_at": "2025-11-16T15:20:10Z",
    "created_at": "2025-11-16T15:20:10Z",
    "owner": "admin",
    "group": "admin",
    "mode": 644
  }
]

Replace File Content

curl -X POST http://localhost:44772/files/replace \
  -H "X-EXECD-ACCESS-TOKEN: your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "/workspace/config.yaml": {
      "old": "localhost:8080",
      "new": "0.0.0.0:9090"
    },
    "/workspace/app.py": {
      "old": "DEBUG = True",
      "new": "DEBUG = False"
    }
  }'

Performs text replacement in one or multiple files. Replaces all occurrences of the old string with the new string (similar to strings.ReplaceAll). Preserves file permissions.

[path]

object

required

Map of file paths to replacement operations

Show Replacement properties

old

string

required

String to be replaced

new

string

required

Replacement string

{}

Upload Files

curl -X POST http://localhost:44772/files/upload \
  -H "X-EXECD-ACCESS-TOKEN: your-token" \
  -F 'metadata={"path":"/workspace/file.txt","owner":"admin","group":"admin","mode":644}' \
  -F 'file=@/local/path/file.txt'

Uploads one or multiple files to specified paths within the sandbox. Uses multipart form data with metadata and file content.

metadata

string

required

JSON-encoded file metadata

Show Metadata properties

path

string

required

Target file path in the sandbox

owner

string

File owner username

group

string

File group name

mode

integer

File permissions in octal format

file

binary

required

File content (binary)

{}

Download File

curl -X GET "http://localhost:44772/files/download?path=/workspace/data.csv" \
  -H "X-EXECD-ACCESS-TOKEN: your-token" \
  -o data.csv

Downloads a file from the specified path within the sandbox. Supports HTTP range requests for resumable downloads and partial content retrieval.

path

string

required

Absolute or relative path of the file to download

Range

string

HTTP Range header for partial content requests (e.g., “bytes=0-1023”)

body

binary

File content as binary stream

Content-Disposition

string

Attachment header with filename

Content-Length

integer

File size in bytes (or range size for partial requests)

Content-Range

string

Range of bytes being returned (only for 206 responses)

[Binary file content]

Create Directories

curl -X POST http://localhost:44772/directories \
  -H "X-EXECD-ACCESS-TOKEN: your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "/workspace/project": {
      "owner": "admin",
      "group": "admin",
      "mode": 755
    },
    "/workspace/logs": {
      "owner": "admin",
      "group": "admin",
      "mode": 755
    }
  }'

Creates one or multiple directories with specified permissions. Creates parent directories as needed (similar to mkdir -p).

[path]

object

required

Map of directory paths to Permission objects

Show Permission properties

owner

string

Owner username

group

string

Group name

mode

integer

required

Permission mode in octal format (e.g., 755)

{}

Delete Directories

curl -X DELETE "http://localhost:44772/directories?path=/workspace/temp" \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

Recursively deletes one or multiple directories and all their contents. Similar to rm -rf. Use with caution as this operation cannot be undone.

This operation permanently deletes directories and all their contents. There is no way to recover deleted data.

path

array

required

Directory path(s) to delete (can be specified multiple times)

{}

File Permissions

Unix-style file permissions use octal notation:

Octal	Binary	Permissions	Description
755	111 101 101	rwxr-xr-x	Owner: read+write+execute, Group/Others: read+execute
644	110 100 100	rw-r—r—	Owner: read+write, Group/Others: read only
600	110 000 000	rw-------	Owner: read+write, Group/Others: no access
777	111 111 111	rwxrwxrwx	Everyone: full access (use with caution)

Permission Breakdown

First digit: Owner permissions
Second digit: Group permissions
Third digit: Others permissions

Each digit is the sum of:

4 = Read (r)
2 = Write (w)
1 = Execute (x)

Examples

// Executable script
{
  "mode": 755,  // Owner can modify, everyone can read/execute
  "owner": "admin",
  "group": "admin"
}

// Configuration file
{
  "mode": 644,  // Owner can modify, everyone can read
  "owner": "admin",
  "group": "admin"
}

// Private key
{
  "mode": 600,  // Only owner can read/write
  "owner": "admin",
  "group": "admin"
}

Lifecycle API

Execution API

SDK Reference

Filesystem Operations

Get File Metadata

Delete Files

Change File Permissions

Rename or Move Files

Search for Files

Replace File Content

Upload Files

Download File

Create Directories

Delete Directories

File Permissions

Permission Breakdown

Examples

Build docs developers (and LLMs) love

Lifecycle API

Execution API

SDK Reference

​Get File Metadata

​Delete Files

​Change File Permissions

​Rename or Move Files

​Search for Files

​Replace File Content

​Upload Files

​Download File

​Create Directories

​Delete Directories

​File Permissions

​Permission Breakdown

​Examples

Build docs developers (and LLMs) love

Get File Metadata

Delete Files

Change File Permissions

Rename or Move Files

Search for Files

Replace File Content

Upload Files

Download File

Create Directories

Delete Directories

File Permissions

Permission Breakdown

Examples