Skip to main content
See Filesystem for usage examples.

​
SandboxFsOps

Filesystem accessor for a running sandbox. Obtained via Sandbox.FS(). All operations go through the same host-guest channel as command execution — no SSH, no network involved. For bulk file operations, consider using a volume instead. 
fs := sb.FS()

if err := fs.WriteString(ctx, "/tmp/config.json", `{"debug": true}`); err != nil {
    return err
}
content, err := fs.ReadString(ctx, "/tmp/config.json")

​
Read()

func (fs *SandboxFSOps) Read(ctx context.Context, path string) ([]byte, error)
Read the entire contents of a file as raw bytes. The default FFI buffer is 1 MiB. For files larger than ~750 KiB (after base64 inflation) the runtime returns BufferTooSmall on the single-shot path; this method transparently falls back to ReadStream so callers get a uniform “Read returns bytes” interface up to runtime memory limits. Parameters
NameTypeDescription
ctxcontext.ContextCancels the read
pathstringAbsolute path inside the guest (e.g. "/app/config.json")
Returns
TypeDescription
[]byteFile contents

​
ReadString()

func (fs *SandboxFSOps) ReadString(ctx context.Context, path string) (string, error)
Read the entire contents of a file and return as a string (UTF-8 reinterpretation of the bytes; no validation).

​
Write()

func (fs *SandboxFSOps) Write(ctx context.Context, path string, data []byte) error
Write bytes to a file, creating it if it doesn’t exist and truncating if it does.

​
WriteString()

func (fs *SandboxFSOps) WriteString(ctx context.Context, path, content string) error
Write a UTF-8 string to a file.

​
List()

func (fs *SandboxFSOps) List(ctx context.Context, path string) ([]FsEntry, error)
List the entries in a directory. Returns
TypeDescription
[]FsEntryDirectory entries
entries, err := fs.List(ctx, "/etc")
for _, e := range entries {
    fmt.Printf("%s (%s, %d bytes)\n", e.Path, e.Kind, e.Size)
}

​
Stat()

func (fs *SandboxFSOps) Stat(ctx context.Context, path string) (*FsStat, error)
Get detailed metadata for a file or directory. Returns
TypeDescription
*FsStatFile metadata

​
Mkdir()

func (fs *SandboxFSOps) Mkdir(ctx context.Context, path string) error
Create a directory and all missing parents.

​
Remove()

func (fs *SandboxFSOps) Remove(ctx context.Context, path string) error
Remove a single file. Use RemoveDir for directories.

​
RemoveDir()

func (fs *SandboxFSOps) RemoveDir(ctx context.Context, path string) error
Remove a directory recursively.

​
Copy()

func (fs *SandboxFSOps) Copy(ctx context.Context, src, dst string) error
Copy a file within the sandbox.

​
Rename()

func (fs *SandboxFSOps) Rename(ctx context.Context, src, dst string) error
Rename or move a file or directory within the sandbox.

​
Exists()

func (fs *SandboxFSOps) Exists(ctx context.Context, path string) (bool, error)
Report whether a path exists inside the sandbox.

​
CopyFromHost()

func (fs *SandboxFSOps) CopyFromHost(ctx context.Context, hostPath, guestPath string) error
Copy a file from the host machine into the sandbox. For transferring many files, consider a bind-mounted volume instead.

​
CopyToHost()

func (fs *SandboxFSOps) CopyToHost(ctx context.Context, guestPath, hostPath string) error
Copy a file from the sandbox to the host machine.

​
ReadStream()

func (fs *SandboxFSOps) ReadStream(ctx context.Context, path string) (*FsReadStream, error)
Open a streaming reader for a file. Data is transferred in chunks (~3 MiB each). Use this for files too large to fit in memory. The caller must Close the returned *FsReadStream. 
rs, err := fs.ReadStream(ctx, "/var/log/syslog")
if err != nil {
    return err
}
defer rs.Close()

// Streaming pattern.
for {
    chunk, err := rs.Recv(ctx)
    if err != nil {
        return err
    }
    if chunk == nil {
        break // EOF
    }
    os.Stdout.Write(chunk)
}

// Or as an io.WriterTo.
_, err = rs.WriteTo(os.Stdout)

​
WriteStream()

func (fs *SandboxFSOps) WriteStream(ctx context.Context, path string) (*FsWriteStream, error)
Open a streaming writer for a file. Use this for files too large to fit in memory. The caller must call Close(ctx) on the returned *FsWriteStream to finalise the operation. 
ws, err := fs.WriteStream(ctx, "/tmp/big.bin")
if err != nil {
    return err
}

if _, err := ws.Write(largeChunk); err != nil {
    return err
}
if err := ws.Close(ctx); err != nil {
    return err
}

​
Types

​
FsEntry

A single directory listing entry returned by List.
FieldTypeDescription
PathstringFile path
KindFsEntryKindEntry type
Sizeint64File size in bytes
Modeuint32Unix permission bits

​
FsEntryKind

type FsEntryKind string
ConstantValueDescription
FsEntryKindFile"file"Regular file
FsEntryKindDirectory"directory"Directory
FsEntryKindSymlink"symlink"Symbolic link
FsEntryKindOther"other"Other entry type

​
FsStat

Detailed file metadata returned by Stat.
FieldTypeDescription
PathstringFile path
Sizeint64File size in bytes
Modeuint32Unix permission bits
ModTimetime.TimeLast modified timestamp (zero value if the guest did not report one)
IsDirboolWhether the path is a directory

​
FsReadStream

Streaming file read returned by ReadStream. Must be closed when done. 
type FsReadStream struct { /* ... */ }
MethodReturnsDescription
Recv(ctx)([]byte, error)Receive the next chunk. Returns (nil, nil) at EOF
WriteTo(w io.Writer)(int64, error)Drain the stream into w using context.Background() — implements io.WriterTo
CopyTo(ctx, w io.Writer)(int64, error)Drain into w with caller-supplied context
Close()errorRelease the read stream handle
WriteTo and CopyTo leave the stream open on error and partial writes so the caller can decide how to recover; close it explicitly in either case.

​
FsWriteStream

Streaming file write returned by WriteStream. Must be closed via Close(ctx) to finalise. 
type FsWriteStream struct { /* ... */ }
MethodReturnsDescription
Write(p []byte)(int, error)Implements io.Writer. Uses context.Background() internally
WriteCtx(ctx, data []byte)errorWrite with explicit context
Close(ctx)errorSend EOF and finalise the file