Execd Files API: Upload, Download, Search, and Manage

The execd filesystem API provides complete file and directory management inside a running sandbox. Endpoints cover reading file metadata, deleting files and directories, changing permissions and ownership, moving and renaming, glob-based search, batch content replacement, multipart upload, and binary download with HTTP range request support. All requests are served by the execd daemon at http://localhost:44772 and require the X-EXECD-ACCESS-TOKEN header.

GET /files/info

Retrieves detailed metadata for one or more files, including permissions, owner, group, size, and modification time. Returns a map of file paths to FileInfo objects. Auth: X-EXECD-ACCESS-TOKEN header required.

Query Parameters

path

array

required

File path(s) to retrieve metadata for. Can be specified multiple times for batch lookup.

Response — 200 OK

A JSON object mapping each requested path to its FileInfo:

{path}

object

Show FileInfo fields

path

string

Absolute file path.

type

string

Entry type. Enum: file, directory, symlink, other.

size

integer

File size in bytes.

modified_at

string

Last modification time (RFC 3339).

created_at

string

File creation time (RFC 3339).

owner

string

File owner username.

group

string

File group name.

mode

integer

Permission mode in octal, e.g. 755.

Example

curl "http://localhost:44772/files/info?path=/workspace/app.py&path=/workspace/config.yaml" \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

DELETE /files

Deletes one or more files from the sandbox. This endpoint removes files only — use DELETE /directories for recursive directory removal. Auth: X-EXECD-ACCESS-TOKEN header required.

Query Parameters

path

array

required

File path(s) to delete. Can be specified multiple times.

Example

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

POST /files/permissions

Changes permissions (mode), owner, and group for one or more files. Accepts a JSON object mapping file paths to permission settings. Auth: X-EXECD-ACCESS-TOKEN header required.

Request Body

A JSON object where each key is an absolute file path and each value is a Permission object:

{path}.mode

integer

required

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

{path}.owner

string

Owner username.

{path}.group

string

Group name.

Example

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 }
  }'

POST /files/mv

Renames or moves one or more files. The target directory must already exist. Accepts an array of {src, dest} pairs. Auth: X-EXECD-ACCESS-TOKEN header required.

Request Body

An array of rename/move items:

[].src

string

required

Source file path.

[].dest

string

required

Destination file path.

Example

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" }
  ]'

GET /files/search

Searches for files matching a glob pattern within a specified root directory and its subdirectories. Returns an array of FileInfo objects for matching files. Auth: X-EXECD-ACCESS-TOKEN header required.

Query Parameters

path

string

required

Root directory path to search in.

pattern

string

Glob pattern to match files. Supports **, *.txt, etc. Default: ** (all files).

Response — 200 OK

An array of FileInfo objects for all files matching the pattern.

Example

curl "http://localhost:44772/files/search?path=/workspace&pattern=*.py" \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

POST /files/replace

Performs batch text replacement across one or more files. Replaces all occurrences of old with new in each specified file (equivalent to strings.ReplaceAll). File permissions are preserved. Use the optional verbose query parameter to receive per-file replacement counts in the response body. Auth: X-EXECD-ACCESS-TOKEN header required.

Query Parameters

verbose

boolean

When true, the response body includes per-file replacement counts. Default: false (empty response body).

Request Body

A JSON object mapping absolute file paths to replacement specs:

{path}.old

string

required

String to find and replace (must not be empty).

{path}.new

string

required

Replacement string.

Response — 200 OK (verbose)

When verbose=true, returns an object mapping paths to replacement results:

{path}.replacedCount

integer

Number of occurrences replaced. 0 means the search string was not found.

Example

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" }
  }'

POST /files/upload

Uploads one or more files to specified paths inside the sandbox using multipart/form-data. Each file upload consists of two consecutive multipart parts: a JSON metadata part followed by the binary file part. Auth: X-EXECD-ACCESS-TOKEN header required.

Form Fields

metadata

string

JSON-encoded FileMetadata object specifying the target path and optional permissions.

{
  "path": "/workspace/upload.txt",
  "owner": "admin",
  "group": "admin",
  "mode": 755
}

file

binary

The file content to upload (application/octet-stream).

Example

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

GET /files/download

Downloads a file from the sandbox. Supports full binary download, HTTP range requests for partial content retrieval, and line-based text reads via offset/limit query parameters. Auth: X-EXECD-ACCESS-TOKEN header required.

Query Parameters

path

string

required

Absolute or relative path of the file to download.

offset

integer

Starting line number (1-based) for line-based reading. Mutually exclusive with the Range header. Returns text/plain content when used.

limit

integer

Number of lines to return when using line-based reading. Mutually exclusive with the Range header.

Request Headers

Range

string

Standard HTTP Range header for partial byte-range requests. Example: bytes=0-1023. Mutually exclusive with offset/limit.

Response

200 OK — Full file content (application/octet-stream) or line-based text (text/plain when offset/limit are used).
206 Partial Content — Partial file bytes when Range header is provided. Includes Content-Range and Content-Length headers.
416 Range Not Satisfiable — The requested byte range cannot be fulfilled.

Example

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

GET /directories/list

Lists entries under a directory with optional depth control. By default, only immediate children are returned (depth=1). Symbolic links are reported with type=symlink and are never traversed. Entries are returned in lexical order. Auth: X-EXECD-ACCESS-TOKEN header required.

Query Parameters

path

string

required

Directory path to list. Must not resolve to a symbolic link.

depth

integer

Maximum depth of descendants to include. 1 returns immediate children only. Default: 1.

Example

curl "http://localhost:44772/directories/list?path=/workspace/project&depth=2" \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

POST /directories

Creates one or more directories with specified permissions. Parent directories are created as needed (mkdir -p semantics). Accepts a JSON object mapping directory paths to permission objects. Auth: X-EXECD-ACCESS-TOKEN header required.

Example

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 }
  }'

DELETE /directories

Recursively deletes one or more directories and all their contents. Equivalent to rm -rf.

This operation is irreversible. All files and subdirectories within the specified paths will be permanently deleted.

Auth: X-EXECD-ACCESS-TOKEN header required.

Query Parameters

path

array

required

Directory path(s) to delete. Can be specified multiple times.

Example

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

GET /metrics

Returns a point-in-time snapshot of system resource utilization for the sandbox, including CPU count, CPU usage percentage, total memory, used memory, and a timestamp. Auth: X-EXECD-ACCESS-TOKEN header required.

Response — 200 OK

cpu_count

number

required

Number of CPU cores available.

cpu_used_pct

number

required

CPU usage as a percentage (0–100).

mem_total_mib

number

required

Total available memory in MiB.

mem_used_mib

number

required

Currently used memory in MiB.

timestamp

integer

required

Unix milliseconds when the metrics snapshot was collected.

Example

curl http://localhost:44772/metrics \
  -H "X-EXECD-ACCESS-TOKEN: your-token"

GET /metrics/watch

Streams system resource metrics in real-time using Server-Sent Events (SSE). The server emits a Metrics snapshot approximately once per second. The connection stays open until the client disconnects. Auth: X-EXECD-ACCESS-TOKEN header required.

Response — 200 OK (`text/event-stream`)

Each SSE event carries a Metrics object with the same fields as GET /metrics: cpu_count, cpu_used_pct, mem_total_mib, mem_used_mib, and timestamp.

Example

curl http://localhost:44772/metrics/watch \
  -H "X-EXECD-ACCESS-TOKEN: your-token" \
  --no-buffer

Overview

Lifecycle API

Execution API

Egress & Diagnostics

Documentation Index

​GET /files/info

​Query Parameters

​Response — 200 OK

​Example

​DELETE /files

​Query Parameters

​Example

​POST /files/permissions

​Request Body

​Example

​POST /files/mv

​Request Body

​Example

​GET /files/search

​Query Parameters

​Response — 200 OK

​Example

​POST /files/replace

​Query Parameters

​Request Body

​Response — 200 OK (verbose)

​Example

​POST /files/upload

​Form Fields

​Example

​GET /files/download

​Query Parameters

​Request Headers

​Response

​Example

​GET /directories/list

​Query Parameters

​Example

​POST /directories

​Example

​DELETE /directories

​Query Parameters

​Example

​GET /metrics

​Response — 200 OK

​Example

​GET /metrics/watch

​Response — 200 OK (text/event-stream)

​Example

Build docs developers (and LLMs) love

GET /files/info

Query Parameters

Response — 200 OK

Example

DELETE /files

Query Parameters

Example

POST /files/permissions

Request Body

Example

POST /files/mv

Request Body

Example

GET /files/search

Query Parameters

Response — 200 OK

Example

POST /files/replace

Query Parameters

Request Body

Response — 200 OK (verbose)

Example

POST /files/upload

Form Fields

Example

GET /files/download

Query Parameters

Request Headers

Response

Example

GET /directories/list

Query Parameters

Example

POST /directories

Example

DELETE /directories

Query Parameters

Example

GET /metrics

Response — 200 OK

Example

GET /metrics/watch

Response — 200 OK (`text/event-stream`)

Example