File System

The File System API is provided by envd's filesystem.Filesystem Connect RPC service and the /files HTTP API. It is used to read and write files, list directories, move and delete files, and watch directory changes.

Before calling this API, see the Sandbox Runtime API to get the envd endpoint and envdAccessToken.

Connect RPC APIs use Authorization: Basic <base64("user:")> to specify the file operation user inside the sandbox. If no user is specified, envd uses the sandbox default user. Request and response bodies use protobuf JSON field names, which are lowerCamelCase.

Connect RPC Paths

Method	Request Path	Type	Description
Stat	/filesystem.Filesystem/Stat	Unary	Get file or directory information
ListDir	/filesystem.Filesystem/ListDir	Unary	List directory contents
MakeDir	/filesystem.Filesystem/MakeDir	Unary	Create a directory
Move	/filesystem.Filesystem/Move	Unary	Move or rename a file or directory
Remove	/filesystem.Filesystem/Remove	Unary	Delete a file or directory
WatchDir	/filesystem.Filesystem/WatchDir	Server streaming	Watch directory changes
CreateWatcher	/filesystem.Filesystem/CreateWatcher	Unary	Create a non-streaming directory watcher
GetWatcherEvents	/filesystem.Filesystem/GetWatcherEvents	Unary	Fetch watcher events
RemoveWatcher	/filesystem.Filesystem/RemoveWatcher	Unary	Delete a watcher

EntryInfo Fields

Field	Type	Description
name	string	File name
type	string	File type. Available values: FILE_TYPE_FILE, FILE_TYPE_DIRECTORY
path	string	Full path
size	integer	File size in bytes
mode	integer	File mode
permissions	string	Permission string
owner	string	Owner
group	string	Group
modifiedTime	string	Last modified time
symlinkTarget	string	Symbolic link target path

Get File Information

Request Path

POST /filesystem.Filesystem/Stat

Request Parameters

Parameter	Type	Required	Description
path	string	Yes	File or directory path

Request Example

curl -X POST "$ENVD_API_BASE/filesystem.Filesystem/Stat" \
  -H "X-Access-Token: $ENVD_ACCESS_TOKEN" \
  -H "Authorization: Basic dXNlcjo=" \
  -H "Connect-Protocol-Version: 1" \
  -H "Content-Type: application/json" \
  -d '{"path": "/tmp/hello.txt"}'

List a Directory

Request Path

POST /filesystem.Filesystem/ListDir

Request Parameters

Parameter	Type	Required	Description
path	string	Yes	Directory path
depth	integer	No	Recursive depth

Response Fields

Field	Type	Description
entries	EntryInfo[]	Directory contents

Request Example

curl -X POST "$ENVD_API_BASE/filesystem.Filesystem/ListDir" \
  -H "X-Access-Token: $ENVD_ACCESS_TOKEN" \
  -H "Authorization: Basic dXNlcjo=" \
  -H "Connect-Protocol-Version: 1" \
  -H "Content-Type: application/json" \
  -d '{"path": "/tmp", "depth": 1}'

Create a Directory

Request Path

POST /filesystem.Filesystem/MakeDir

Request Parameters

Parameter	Type	Required	Description
path	string	Yes	Directory path

Returns the created EntryInfo on success.

Move a File or Directory

Request Path

POST /filesystem.Filesystem/Move

Request Parameters

Parameter	Type	Required	Description
source	string	Yes	Source path
destination	string	Yes	Destination path

Returns the moved EntryInfo on success.

Delete a File or Directory

Request Path

POST /filesystem.Filesystem/Remove

Request Parameters

Parameter	Type	Required	Description
path	string	Yes	File or directory path

Returns an empty object on success.

Watch Directory Changes

Request Path

POST /filesystem.Filesystem/WatchDir

Request Parameters

Parameter	Type	Required	Description
path	string	Yes	Directory path
recursive	boolean	No	Whether to recursively watch subdirectories

Event Types

Event	Description
EVENT_TYPE_CREATE	File or directory created
EVENT_TYPE_WRITE	File written
EVENT_TYPE_REMOVE	File or directory deleted
EVENT_TYPE_RENAME	File or directory renamed
EVENT_TYPE_CHMOD	Permission changed

Non-Streaming Directory Watchers

If your calling environment cannot conveniently consume streaming responses, use a non-streaming watcher.

Create a Watcher

POST /filesystem.Filesystem/CreateWatcher

Request parameters:

Parameter	Type	Required	Description
path	string	Yes	Directory path
recursive	boolean	No	Whether to recursively watch

Response fields:

Field	Type	Description
watcherId	string	Watcher ID

Fetch Events

POST /filesystem.Filesystem/GetWatcherEvents

Request parameters:

Parameter	Type	Required	Description
watcherId	string	Yes	Watcher ID

Delete a Watcher

POST /filesystem.Filesystem/RemoveWatcher

Request parameters:

Parameter	Type	Required	Description
watcherId	string	Yes	Watcher ID

Download a File

Request Path

GET /files

Request Parameters

Parameter	Type	Required	Description
path	string	No	File path. Must be URL-encoded and can be relative to the user's home directory
username	string	No	User used to resolve relative paths
signature	string	No	File access signature. Not required when using X-Access-Token
signature_expiration	integer	No	Signature expiration time, as a Unix timestamp in seconds

Returns application/octet-stream file content on success.

Request Example

curl -X GET "$ENVD_API_BASE/files?path=%2Ftmp%2Fhello.txt" \
  -H "X-Access-Token: $ENVD_ACCESS_TOKEN" \
  -o hello.txt

Upload a File

Request Path

POST /files

Request Parameters

Query parameters are the same as the download file API. The request body uses multipart/form-data with a field named file.

Returns an array of written EntryInfo objects on success.

Request Example

curl -X POST "$ENVD_API_BASE/files?path=%2Ftmp%2Fhello.txt" \
  -H "X-Access-Token: $ENVD_ACCESS_TOKEN" \
  -F "file=@hello.txt"

Related Documents

• Sandbox Runtime
• Processes and Terminals