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

# Filesystem

> Read, write, and transfer guest files with the Ruby SDK.

See [Filesystem](/sandboxes/filesystem) for usage examples.

## Sandbox

#### <span className="msb-recv">sandbox.</span><span className="msb-hn">fs</span>

```ruby theme={null}
sandbox.fs # => Microsandbox::Filesystem
```

Get the filesystem helper for this sandbox.

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Microsandbox::Filesystem</span></div>
    <div className="msb-param-desc">Guest filesystem operations.</div>
  </div>
</div>

## Filesystem

These helpers also have direct sandbox equivalents: `sandbox.fs_read`, `fs_write`, `fs_mkdir`, `fs_list`, `fs_stat`, `fs_exists?`, `fs_copy`, `fs_rename`, `fs_remove`, `fs_remove_dir`, `fs_copy_from_host`, and `fs_copy_to_host`, with the same arguments and return values.

#### <span className="msb-recv">fs.</span><span className="msb-hn">read()</span>

```ruby theme={null}
fs.read(path) # => String
```

<Accordion title="Example">
  ```ruby theme={null}
  puts sandbox.fs.read("/tmp/message.txt")
  ```
</Accordion>

Read file bytes.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Guest path.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Read file bytes.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">write()</span>

```ruby theme={null}
fs.write(path, data) # => nil
```

<Accordion title="Example">
  ```ruby theme={null}
  sandbox.fs.write("/tmp/message.txt", "hello")
  ```
</Accordion>

Write a Ruby string as bytes.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Guest path.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>data</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">File contents as bytes.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">nil</span></div>
    <div className="msb-param-desc">No return value.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">mkdir()</span>

```ruby theme={null}
fs.mkdir(path) # => nil
```

Create a guest directory.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Guest path.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">nil</span></div>
    <div className="msb-param-desc">No return value.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">list()</span>

```ruby theme={null}
fs.list(path) # => Array<Hash>
```

List directory entries.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Guest path.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Array\<Hash></span></div>
    <div className="msb-param-desc">List directory entries.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">stat()</span>

```ruby theme={null}
fs.stat(path) # => Hash
```

Read metadata.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Guest path.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Hash</span></div>
    <div className="msb-param-desc">Read metadata.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">exists?()</span>

```ruby theme={null}
fs.exists?(path) # => Boolean
```

Check whether a path exists.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Guest path.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Boolean</span></div>
    <div className="msb-param-desc">Check whether a path exists.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">copy()</span>

```ruby theme={null}
fs.copy(from, to) # => nil
```

Copy within the guest.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>from</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Source guest path.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>to</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Destination guest path.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">nil</span></div>
    <div className="msb-param-desc">No return value.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">rename()</span>

```ruby theme={null}
fs.rename(from, to) # => nil
```

Rename within the guest.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>from</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Source guest path.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>to</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Destination guest path.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">nil</span></div>
    <div className="msb-param-desc">No return value.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">remove()</span>

```ruby theme={null}
fs.remove(path) # => nil
```

Remove a file.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Guest path.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">nil</span></div>
    <div className="msb-param-desc">No return value.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">remove\_dir()</span>

```ruby theme={null}
fs.remove_dir(path) # => nil
```

Remove a directory.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Guest path.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">nil</span></div>
    <div className="msb-param-desc">No return value.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">copy\_from\_host()</span>

```ruby theme={null}
fs.copy_from_host(host_path, guest_path) # => nil
```

Transfer from host to guest.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>host\_path</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Path on the host.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>guest\_path</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Path inside the guest.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">nil</span></div>
    <div className="msb-param-desc">No return value.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">copy\_to\_host()</span>

```ruby theme={null}
fs.copy_to_host(guest_path, host_path) # => nil
```

<Accordion title="Example">
  ```ruby theme={null}
  sandbox.fs.copy_to_host("/tmp/message.txt", "./message.txt")
  ```
</Accordion>

Transfer from guest to host.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>guest\_path</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Path inside the guest.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>host\_path</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Path on the host.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">nil</span></div>
    <div className="msb-param-desc">No return value.</div>
  </div>
</div>

## Metadata

Hashes use string keys. Optional timestamps are omitted when unavailable. Ruby does not expose streaming filesystem handles.

<p className="msb-label">Fields</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>"path"</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Entry path; returned by list</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>"kind"</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">file, directory, symlink, or other</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>"size"</code><span className="msb-type">Integer</span></div>
    <div className="msb-param-desc">Size in bytes</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>"mode"</code><span className="msb-type">Integer</span></div>
    <div className="msb-param-desc">File mode</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>"uid", "gid"</code><span className="msb-type">Integer</span></div>
    <div className="msb-param-desc">Owner and group IDs</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>"modified", "accessed"</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">RFC 3339 timestamps, when available</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>"readonly"</code><span className="msb-type">Boolean</span></div>
    <div className="msb-param-desc">Returned by stat</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>"created"</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Creation timestamp, when available from stat</div>
  </div>
</div>