--- title: Filesystem description: Go SDK - Filesystem API reference --- Read and write files inside a running sandbox over the same host-guest channel as command execution: no SSH, no network. See [Filesystem](/sandboxes/filesystem) for usage examples. For bulk file transfer, prefer a [volume](/sdk/go/volumes).

Methods ยท SandboxFSOps16

fs.Read()read a file as bytes fs.ReadString()read a file as a string fs.Write()write bytes fs.WriteString()write a string fs.List()list a directory fs.Stat()file metadata fs.Mkdir()create a directory fs.Remove()delete a file fs.RemoveDir()delete a directory fs.Copy()copy within the guest fs.Rename()rename / move fs.Exists()test a path fs.CopyFromHost()host file into guest fs.CopyToHost()guest file to host fs.ReadStream()stream a large read fs.WriteStream()stream a large write

Types

FsEntry FsEntryKind FsStat FsReadStream FsWriteStream

Typical flow

```go import m "github.com/superradcompany/microsandbox/sdk/go" fs := sb.FS() // 1. get the accessor err := fs.WriteString(ctx, "/tmp/config.json", `{"debug":true}`) // 2. write if err != nil { return err } content, err := fs.ReadString(ctx, "/tmp/config.json") // 3. read back if err != nil { return err } fmt.Println(content) ``` ## Methods The accessor is obtained from a running sandbox via [`sb.FS()`](/sdk/go/sandbox#fs). Every method takes a `context.Context` first and returns an `error` (wrapped, inspectable with `m.IsKind`). --- #### fs.Read()
method
```go 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, and this method transparently falls back to [`ReadStream`](#fs-readstream) so callers get a uniform bytes-returning interface up to runtime memory limits.

Parameters

ctxcontext.Context
Cancels the read.
pathstring
Absolute path inside the guest, e.g. "/app/config.json".

Returns

[]byte
File contents.
```go data, err := fs.Read(ctx, "/etc/hostname") if err != nil { return err } fmt.Printf("%d bytes\n", len(data)) ``` --- #### fs.ReadString()
method
```go func (fs *SandboxFSOps) ReadString(ctx context.Context, path string) (string, error) ``` Read a file and return its contents as a string. The bytes are reinterpreted as UTF-8 without validation.

Parameters

ctxcontext.Context
Cancels the read.
pathstring
Absolute path inside the guest.

Returns

string
File contents.
```go content, err := fs.ReadString(ctx, "/tmp/config.json") ``` --- #### fs.Write()
method
```go func (fs *SandboxFSOps) Write(ctx context.Context, path string, data []byte) error ``` Write bytes to a file, creating it if it does not exist and truncating it if it does.

Parameters

ctxcontext.Context
Cancels the write.
pathstring
Absolute path inside the guest.
data[]byte
Bytes to write.
```go err := fs.Write(ctx, "/tmp/data.bin", []byte{0x00, 0x01, 0x02}) ``` --- #### fs.WriteString()
method
```go func (fs *SandboxFSOps) WriteString(ctx context.Context, path, content string) error ``` Write a UTF-8 string to a file. Convenience wrapper over [`Write`](#fs-write).

Parameters

ctxcontext.Context
Cancels the write.
pathstring
Absolute path inside the guest.
contentstring
Text to write.
```go err := fs.WriteString(ctx, "/tmp/hello.txt", "hi") ``` --- #### fs.List()
method
```go func (fs *SandboxFSOps) List(ctx context.Context, path string) ([]FsEntry, error) ``` List the entries in a directory inside the sandbox.

Parameters

ctxcontext.Context
Cancels the listing.
pathstring
Absolute directory path inside the guest.

Returns

[]FsEntry
Directory entries.
```go entries, err := fs.List(ctx, "/etc") if err != nil { return err } for _, e := range entries { fmt.Printf("%s (%s, %d bytes)\n", e.Path, e.Kind, e.Size) } ``` --- #### fs.Stat()
method
```go func (fs *SandboxFSOps) Stat(ctx context.Context, path string) (*FsStat, error) ``` Get detailed metadata for a file or directory.

Parameters

ctxcontext.Context
Cancels the stat.
pathstring
Absolute path inside the guest.

Returns

*FsStat
File metadata.
```go st, err := fs.Stat(ctx, "/etc/hosts") if err != nil { return err } fmt.Printf("%d bytes, dir=%v\n", st.Size, st.IsDir) ``` --- #### fs.Mkdir()
method
```go func (fs *SandboxFSOps) Mkdir(ctx context.Context, path string) error ``` Create a directory and any missing parents inside the sandbox.

Parameters

ctxcontext.Context
Cancels the operation.
pathstring
Absolute directory path inside the guest.
```go err := fs.Mkdir(ctx, "/app/cache/sessions") ``` --- #### fs.Remove()
method
```go func (fs *SandboxFSOps) Remove(ctx context.Context, path string) error ``` Delete a single file. Use [`RemoveDir`](#fs-removedir) for directories.

Parameters

ctxcontext.Context
Cancels the operation.
pathstring
Absolute file path inside the guest.
```go err := fs.Remove(ctx, "/tmp/scratch.txt") ``` --- #### fs.RemoveDir()
method
```go func (fs *SandboxFSOps) RemoveDir(ctx context.Context, path string) error ``` Remove a directory recursively.

Parameters

ctxcontext.Context
Cancels the operation.
pathstring
Absolute directory path inside the guest.
```go err := fs.RemoveDir(ctx, "/app/cache") ``` --- #### fs.Copy()
method
```go func (fs *SandboxFSOps) Copy(ctx context.Context, src, dst string) error ``` Copy a file within the sandbox.

Parameters

ctxcontext.Context
Cancels the operation.
srcstring
Source path inside the guest.
dststring
Destination path inside the guest.
```go err := fs.Copy(ctx, "/etc/hosts", "/tmp/hosts.bak") ``` --- #### fs.Rename()
method
```go func (fs *SandboxFSOps) Rename(ctx context.Context, src, dst string) error ``` Rename or move a file or directory within the sandbox.

Parameters

ctxcontext.Context
Cancels the operation.
srcstring
Current path inside the guest.
dststring
New path inside the guest.
```go err := fs.Rename(ctx, "/tmp/old.log", "/tmp/archive/old.log") ``` --- #### fs.Exists()
method
```go func (fs *SandboxFSOps) Exists(ctx context.Context, path string) (bool, error) ``` Report whether a file or directory exists at the given path.

Parameters

ctxcontext.Context
Cancels the check.
pathstring
Absolute path inside the guest.

Returns

bool
true if the path exists.
```go ok, err := fs.Exists(ctx, "/app/.initialized") if err != nil { return err } if !ok { // first boot } ``` --- #### fs.CopyFromHost()
method
```go 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](/sdk/go/volumes#mountbind) instead.

Parameters

ctxcontext.Context
Cancels the copy.
hostPathstring
Source path on the host.
guestPathstring
Destination path inside the guest.
```go err := fs.CopyFromHost(ctx, "./seed.db", "/app/data/seed.db") ``` --- #### fs.CopyToHost()
method
```go func (fs *SandboxFSOps) CopyToHost(ctx context.Context, guestPath, hostPath string) error ``` Copy a file from the sandbox to the host machine.

Parameters

ctxcontext.Context
Cancels the copy.
guestPathstring
Source path inside the guest.
hostPathstring
Destination path on the host.
```go err := fs.CopyToHost(ctx, "/app/output/report.csv", "./report.csv") ``` --- #### fs.ReadStream()
method
```go func (fs *SandboxFSOps) ReadStream(ctx context.Context, path string) (*FsReadStream, error) ``` Open a streaming reader for a file. Use this for files too large to fit in memory; data is delivered in chunks. The caller must `Close` the returned [`*FsReadStream`](#fsreadstream). [`Read`](#fs-read) falls back to this automatically when a file exceeds the single-shot buffer.

Parameters

ctxcontext.Context
Cancels opening the stream.
pathstring
Absolute path inside the guest.

Returns

*FsReadStream
Open read stream; close it when done.
```go rs, err := fs.ReadStream(ctx, "/var/log/syslog") if err != nil { return err } defer rs.Close() for { chunk, err := rs.Recv(ctx) if err != nil { return err } if chunk == nil { break // EOF } os.Stdout.Write(chunk) } // Or drain it as an io.WriterTo. _, err = rs.WriteTo(os.Stdout) ``` --- #### fs.WriteStream()
method
```go 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`](#fswritestream) to finalise the write.

Parameters

ctxcontext.Context
Cancels opening the stream.
pathstring
Absolute path inside the guest.

Returns

*FsWriteStream
Open write stream; Close(ctx) it to finalise.
```go 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
struct

Returned by List()

A single directory listing entry. | Field | Type | Description | |-------|------|-------------| | Path | `string` | File path | | Kind | [`FsEntryKind`](#fsentrykind) | Entry type | | Size | `int64` | File size in bytes | | Mode | `uint32` | Unix permission bits | ### FsEntryKind
type

Used by FsEntry.Kind

Classifies a directory listing entry. Defined as `type FsEntryKind string`. | Constant | Value | Description | |----------|-------|-------------| | `FsEntryKindFile` | `"file"` | Regular file | | `FsEntryKindDirectory` | `"directory"` | Directory | | `FsEntryKindSymlink` | `"symlink"` | Symbolic link | | `FsEntryKindOther` | `"other"` | Other entry type | ### FsStat
struct

Returned by Stat()

Detailed file metadata. | Field | Type | Description | |-------|------|-------------| | Path | `string` | File path | | Size | `int64` | File size in bytes | | Mode | `uint32` | Unix permission bits | | ModTime | `time.Time` | Last modified timestamp; zero value if the guest did not report one | | IsDir | `bool` | Whether the path is a directory | ### FsReadStream
struct

Returned by ReadStream()

An open streaming read from a guest file. Must be closed with `Close` when done. | Method | Returns | Description | |--------|---------|-------------| | `Recv(ctx context.Context)` | `([]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 context.Context, w io.Writer)` | `(int64, error)` | Drain into `w` honouring `ctx` for per-chunk cancellation | | `Close()` | `error` | Release the read stream handle | On a write error or partial write, `WriteTo` and `CopyTo` return the partial byte count and leave the stream open so the caller can recover; close it explicitly in either case. ### FsWriteStream
struct

Returned by WriteStream()

An open streaming write to a guest file. Must be closed with `Close(ctx)` to finalise the write. | Method | Returns | Description | |--------|---------|-------------| | `Write(p []byte)` | `(int, error)` | Send a chunk; implements `io.Writer`, uses `context.Background()` internally | | `WriteCtx(ctx context.Context, data []byte)` | `error` | Send a chunk with explicit context control | | `Close(ctx context.Context)` | `error` | Send the EOF marker and wait for the guest to confirm; must be called to complete the write |