Filesystem

import "github.com/declaw-ai/declaw-go"

sbx.Files is the *Filesystem sub-object available on every Sandbox instance. All paths must be absolute paths within the sandbox filesystem.

`sbx.Files.Read()`

Read a file as a UTF-8 string from the sandbox.

content, err := sbx.Files.Read(ctx, "/home/user/script.py")
fmt.Println(content)

string

required

Absolute path inside the sandbox.

string

default:"server default"

Unix user context for file operations. Server defaults to "user" when not specified.

Returns (string, error)

`sbx.Files.ReadBytes()`

Read a file as raw bytes.

data, err := sbx.Files.ReadBytes(ctx, "/data/image.png")

Returns ([]byte, error)

`sbx.Files.Write()`

Write a UTF-8 string to a file. Creates parent directories automatically.

info, err := sbx.Files.Write(ctx, "/home/user/hello.py", "print('hello')")
fmt.Println(info.Path, info.Size)

string

required

Absolute path inside the sandbox.

string

required

Content to write.

Returns (*WriteInfo, error)

`sbx.Files.WriteBytes()`

Write raw bytes to a file. Uses the binary-safe PUT /files/raw endpoint.

info, err := sbx.Files.WriteBytes(ctx, "/tmp/blob.bin", rawBytes)

Returns (*WriteInfo, error)

`sbx.Files.WriteFiles()`

Write multiple files in a single batch request. More efficient than calling Write() in a loop.

err := sbx.Files.WriteFiles(ctx, []declaw.WriteEntry{
    {Path: "/home/user/main.py", Data: "import sys\nprint(sys.argv)"},
    {Path: "/home/user/data.json", Data: `{"key": "value"}`},
})

Each entry’s Data must be a string. Use WriteBytes for binary data.

[]WriteEntry

required

List of WriteEntry values. Each has Path (string) and Data (string).

Returns error

`sbx.Files.List()`

List the contents of a directory.

entries, err := sbx.Files.List(ctx, "/home/user")
for _, e := range entries {
    fmt.Println(e.Type, e.Path, e.Size)
}

string

required

Absolute path to the directory.

Returns ([]EntryInfo, error)

`sbx.Files.Exists()`

Check whether a file or directory exists.

exists, err := sbx.Files.Exists(ctx, "/home/user/output.csv")
if exists {
    content, _ := sbx.Files.Read(ctx, "/home/user/output.csv")
    fmt.Println(content)
}

Returns (bool, error)

`sbx.Files.GetInfo()`

Get metadata about a single file or directory.

info, err := sbx.Files.GetInfo(ctx, "/home/user/script.py")
fmt.Println(info.Path, info.Type, info.Size)

Returns (*EntryInfo, error)

`sbx.Files.Remove()`

Remove a file or directory.

err := sbx.Files.Remove(ctx, "/home/user/temp_output.txt")

Returns error

`sbx.Files.Rename()`

Rename or move a file or directory.

err := sbx.Files.Rename(ctx, "/home/user/draft.py", "/home/user/final.py")

Returns error

`sbx.Files.MakeDir()`

Create a directory (including parent directories if needed).

err := sbx.Files.MakeDir(ctx, "/home/user/output/results")

Returns error

`sbx.Files.Watch()`

Not yet implemented. Returns an error until server-side streaming support is available.

Watch a path for filesystem changes. Will return a *WatchHandle with an events channel.

Data models

`EntryInfo`

type EntryInfo struct {
    Path string
    Type FileType
    Size int64
}

`FileType`

const (
    FileTypeFile      FileType = "file"
    FileTypeDirectory FileType = "dir"
    FileTypeSymlink   FileType = "symlink"
    FileTypeOther     FileType = "other"
)

`WriteInfo`

type WriteInfo struct {
    Path string
    Size int64
}

`WriteEntry`

type WriteEntry struct {
    Path string
    Data interface{} // must be string for WriteFiles
}

Examples

Upload and execute a script

_, err := sbx.Files.Write(ctx, "/home/user/analyze.py", scriptContent)
if err != nil {
    log.Fatal(err)
}
result, err := sbx.Commands.Run(ctx, "python3 /home/user/analyze.py")
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.Stdout)

Batch upload files

err := sbx.Files.WriteFiles(ctx, []declaw.WriteEntry{
    {Path: "/data/config.json", Data: `{"batch_size": 32}`},
    {Path: "/data/input.csv", Data: csvContent},
})
if err != nil {
    log.Fatal(err)
}

Download generated output

_, _ = sbx.Commands.Run(ctx, `python3 -c "open('/tmp/out.csv','w').write('a,b\n1,2')"`)
content, err := sbx.Files.Read(ctx, "/tmp/out.csv")
if err != nil {
    log.Fatal(err)
}
_ = os.WriteFile("local_out.csv", []byte(content), 0644)

Python SDK

TypeScript SDK

Go SDK

`sbx.Files.Read()`

`sbx.Files.ReadBytes()`

`sbx.Files.Write()`

`sbx.Files.WriteBytes()`

`sbx.Files.WriteFiles()`

`sbx.Files.List()`

`sbx.Files.Exists()`

`sbx.Files.GetInfo()`

`sbx.Files.Remove()`

`sbx.Files.Rename()`

`sbx.Files.MakeDir()`

`sbx.Files.Watch()`

Data models

`EntryInfo`

`FileType`

`WriteInfo`

`WriteEntry`

Examples

Upload and execute a script

Batch upload files

Download generated output

​sbx.Files.Read()

​sbx.Files.ReadBytes()

​sbx.Files.Write()

​sbx.Files.WriteBytes()

​sbx.Files.WriteFiles()

​sbx.Files.List()

​sbx.Files.Exists()

​sbx.Files.GetInfo()

​sbx.Files.Remove()

​sbx.Files.Rename()

​sbx.Files.MakeDir()

​sbx.Files.Watch()

​Data models

​EntryInfo

​FileType

​WriteInfo

​WriteEntry

​Examples

​Upload and execute a script

​Batch upload files

​Download generated output

`sbx.Files.Read()`

`sbx.Files.ReadBytes()`

`sbx.Files.Write()`

`sbx.Files.WriteBytes()`

`sbx.Files.WriteFiles()`

`sbx.Files.List()`

`sbx.Files.Exists()`

`sbx.Files.GetInfo()`

`sbx.Files.Remove()`

`sbx.Files.Rename()`

`sbx.Files.MakeDir()`

`sbx.Files.Watch()`

Data models

`EntryInfo`

`FileType`

`WriteInfo`

`WriteEntry`

Examples

Upload and execute a script

Batch upload files

Download generated output