Documentation Index
Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
Use this file to discover all available pages before exploring further.
See Filesystem for usage examples and extensible backends.
SandboxFs
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 *SandboxFs) Read(ctx context.Context, path string) ([]byte, error)
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
| Name | Type | Description |
|---|
| ctx | context.Context | Cancels the read |
| path | string | Absolute path inside the guest (e.g. "/app/config.json") |
| Type | Description |
|---|
[]byte | File contents |
ReadString()
func (fs *SandboxFs) ReadString(ctx context.Context, path string) (string, error)
Write()
func (fs *SandboxFs) Write(ctx context.Context, path string, data []byte) error
WriteString()
func (fs *SandboxFs) WriteString(ctx context.Context, path, content string) error
List()
func (fs *SandboxFs) List(ctx context.Context, path string) ([]FsEntry, error)
| Type | Description |
|---|
[]FsEntry | Directory 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 *SandboxFs) Stat(ctx context.Context, path string) (*FsStat, error)
| Type | Description |
|---|
*FsStat | File metadata |
Mkdir()
func (fs *SandboxFs) Mkdir(ctx context.Context, path string) error
Remove()
func (fs *SandboxFs) Remove(ctx context.Context, path string) error
RemoveDir for directories.
RemoveDir()
func (fs *SandboxFs) RemoveDir(ctx context.Context, path string) error
Copy()
func (fs *SandboxFs) Copy(ctx context.Context, src, dst string) error
Rename()
func (fs *SandboxFs) Rename(ctx context.Context, src, dst string) error
Exists()
func (fs *SandboxFs) Exists(ctx context.Context, path string) (bool, error)
CopyFromHost()
func (fs *SandboxFs) CopyFromHost(ctx context.Context, hostPath, guestPath string) error
CopyToHost()
func (fs *SandboxFs) CopyToHost(ctx context.Context, guestPath, hostPath string) error
ReadStream()
func (fs *SandboxFs) ReadStream(ctx context.Context, path string) (*FsReadStream, error)
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 *SandboxFs) WriteStream(ctx context.Context, path string) (*FsWriteStream, error)
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.
| Field | Type | Description |
|---|
| Path | string | File path |
| Kind | FsEntryKind | Entry type |
| Size | int64 | File size in bytes |
| Mode | uint32 | Unix permission bits |
FsEntryKind
| Constant | Value | Description |
|---|
FsEntryKindFile | "file" | Regular file |
FsEntryKindDirectory | "directory" | Directory |
FsEntryKindSymlink | "symlink" | Symbolic link |
FsEntryKindOther | "other" | Other entry type |
FsStat
Detailed file metadata returned by Stat.
| 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
Streaming file read returned by ReadStream. Must be closed when done.
type FsReadStream struct { /* ... */ }
| Method | Returns | Description |
|---|
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() | error | Release 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 { /* ... */ }
| Method | Returns | Description |
|---|
Write(p []byte) | (int, error) | Implements io.Writer. Uses context.Background() internally |
WriteCtx(ctx, data []byte) | error | Write with explicit context |
Close(ctx) | error | Send EOF and finalise the file |
