SANDBOX/Files

#Files

Manage files and directories within a sandbox. The Files API provides full POSIX file operations including read, write, delete, move, and real-time file watching.

Files written to the sandbox writable filesystem are restored across checkpointed pause/resume for the same sandbox identity, including paths that are not backed by mounted Volumes. They are deleted with the sandbox identity unless you publish a rootfs snapshot or fork before cleanup. Use Snapshot And Restore for sandbox rootfs checkpoints, restore, and fork operations. Use Volumes for data that must be shared across sandboxes or accessed directly without a running sandbox.

File Model#

FileInfo#

Field	Type	Description
`name`	string	File name
`path`	string	Full path
`type`	string	File type: `file`, `dir`, `symlink`
`size`	integer	File size in bytes
`mode`	string	Unix file mode (e.g., `0755`)
`mod_time`	string	Last modification time (ISO 8601)
`is_link`	boolean	Whether it's a symlink
`link_target`	string	Symlink target path (if applicable)

Write File#

Write content to a file. Creates the file if it doesn't exist.

POST/api/v1/sandboxes/{id}/files

Query Parameters#

Parameter	Type	Description
`path`	string	File path to write (required)

Request Body#

Binary file content (raw bytes).

go
// Write file content
content := []byte("Hello from Sandbox0!\n")
_, err := sandbox.WriteFile(ctx, "/workspace/hello.txt", content)
if err != nil {
  log.Fatal(err)
}
fmt.Println("File written successfully")

Read File#

Read file content from a sandbox.

GET/api/v1/sandboxes/{id}/files

Query Parameters#

Parameter	Type	Description
`path`	string	File path to read (required)

go
// Read the file
readResult, err := sandbox.ReadFile(ctx, "/workspace/hello.txt")
if err != nil {
  log.Fatal(err)
}
fmt.Printf("File content: %s\n", strings.TrimSpace(string(readResult)))

Create Directory#

Create a new directory.

POST/api/v1/sandboxes/{id}/files

Query Parameters#

Parameter	Type	Description
`path`	string	Directory path to create (required)
`mkdir`	boolean	Set to `true` to create directory
`recursive`	boolean	Create parent directories if needed

go
// Create directory (with parent directories)
_, err = sandbox.Mkdir(ctx, "/workspace/project/src", true)
if err != nil {
  log.Fatal(err)
}
fmt.Println("Directory created")

Move File or Directory#

Move or rename a file or directory.

POST/api/v1/sandboxes/{id}/files/move

Request Body#

Field	Type	Description
`source`	string	Source path
`destination`	string	Destination path

go
// Move/rename file
_, err = sandbox.MoveFile(ctx, "/workspace/hello.txt", "/workspace/new-hello.txt")
if err != nil {
  log.Fatal(err)
}
fmt.Println("File moved")

Delete File or Directory#

Delete a file or directory.

DELETE/api/v1/sandboxes/{id}/files

Query Parameters#

Parameter	Type	Description
`path`	string	Path to delete (required)

ℹ

Deleting a directory removes all its contents recursively. This action cannot be undone.

go
// Delete file
_, err = sandbox.DeleteFile(ctx, "/workspace/new-hello.txt")
if err != nil {
  log.Fatal(err)
}
fmt.Println("File deleted")

Get File Info (Stat)#

Get metadata about a file or directory.

GET/api/v1/sandboxes/{id}/files/stat

Query Parameters#

Parameter	Type	Description
`path`	string	File path to stat (required)

go
// Get file info
info, err := sandbox.StatFile(ctx, "/workspace/hello.txt")
if err != nil {
  log.Fatal(err)
}
if name, ok := info.Name.Get(); ok {
  fmt.Printf("Name: %s\n", name)
}
if size, ok := info.Size.Get(); ok {
  fmt.Printf("Size: %d bytes\n", size)
}
if fileType, ok := info.Type.Get(); ok {
  fmt.Printf("Type: %s\n", fileType)
}
if mode, ok := info.Mode.Get(); ok {
  fmt.Printf("Mode: %s\n", mode)
}

List Directory#

List contents of a directory.

GET/api/v1/sandboxes/{id}/files/list

Query Parameters#

Parameter	Type	Description
`path`	string	Directory path to list (required)

go
// List directory contents
entries, err := sandbox.ListFiles(ctx, "/workspace")
if err != nil {
  log.Fatal(err)
}
for _, entry := range entries {
  path, ok := entry.Path.Get()
  if !ok {
      continue
  }
  fileType, _ := entry.Type.Get()
  size, _ := entry.Size.Get()
  fmt.Printf("- %s (%s, %d bytes)\n", path, fileType, size)
}

Watch Files#

Watch a directory for file system changes in real-time via WebSocket.

GET/api/v1/sandboxes/{id}/files/watch

WebSocket Protocol#

Client Messages:

Action	Description	Example
`subscribe`	Subscribe to a path	`{"action": "subscribe", "path": "/tmp", "recursive": true}`
`unsubscribe`	Unsubscribe from a watch	`{"action": "unsubscribe", "watch_id": "watch-123"}`

Server Messages:

Type	Description	Example
`subscribed`	Subscription confirmed	`{"type": "subscribed", "watch_id": "watch-123", "path": "/tmp"}`
`event`	File event occurred	`{"type": "event", "watch_id": "watch-123", "event": "write", "path": "/tmp/a.txt"}`
`unsubscribed`	Unsubscription confirmed	`{"type": "unsubscribed", "watch_id": "watch-123"}`
`error`	Error occurred	`{"type": "error", "error": "permission denied"}`

File Events#

Event	Description
`create`	File or directory created
`write`	File content modified
`rename`	File or directory renamed
`chmod`	File permissions changed
`remove`	File or directory deleted

go
// Watch files for changes
watchCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()

events, errs, unsubscribe, err := sandbox.WatchFiles(watchCtx, "/workspace", true)
if err != nil {
  log.Fatal(err)
}
defer func() {
  if err := unsubscribe(); err != nil {
      log.Printf("cleanup unsubscribe watch: %v", err)
  }
}()

// Process events
for {
  select {
  case ev, ok := <-events:
      if !ok {
          return
      }
      fmt.Printf("Event: %s on %s\n", ev.Event, ev.Path)
  case err, ok := <-errs:
      if ok && err != nil {
          log.Printf("Watch error: %v", err)
      }
  case <-watchCtx.Done():
      fmt.Println("Watch timeout")
      return
  }
}

Next Steps#

SSH

Connect to sandboxes with standard SSH clients for shell and file-copy workflows.

Network

Configure outbound network policy, traffic rules, and protocol-aware restrictions.