#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.

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#

Network Policy

Control network access and egress rules

Ports Exposure

Expose sandbox ports publicly

Sandbox Webhooks

Receive sandbox lifecycle and event callbacks