> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phones.farm/llms.txt
> Use this file to discover all available pages before exploring further.

# Virtual File System

> Accessing and managing sandbox file systems, configuration uploads, and log extraction on connected devices.

## 1.Virtual File System

Provides file system access to the iOS device container.

💡 Use cases

This feature is very useful as a file relay/transfer mechanism in jailbroken environments.

### Feature Overview

| Feature | Description | Interface Name |
| - | - | - |
| 📂 **Read Directory** | List files/directories under a path (includes size & mtime) | `readSandboxPath` |
| 📄 **Read File** | Read binary file content (Buffer) | `readSandboxFile` |
| ✍️ **Write File** | Write UTF-8 text into a file (atomic write) | `writeSandboxFile` |
| 🗑️ **Delete File** | Delete a file by absolute path | `deleteSandboxFile` |

### Path Notes

* For directory listing, `path` is **optional**: if omitted, it reads the App Group container root.
* For read/write/delete, `file` must be a path that is accessible on the device side.
* It’s recommended to obtain the sandbox root from device info `device.info.sandboxPath`, then build sub-paths with template strings, e.g. `${_device.info.sandboxPath}/result.txt`.

## 2.Read Directory

List files and folders under a given directory path. Each entry includes name, whether it is a directory, size, and last modified time.

### Endpoint Description

#### Endpoint Type

```
readSandboxPath
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |
| `path` | string | ❌ | Target directory path (if omitted or empty, defaults to sandbox root, same as `device.info.sandboxPath`) |

#### Response Payload

Returns an array:

```
[
    {
        name: "result.txt",
        dir: false,
        size: 1234,
        mtime: 1710000000000
    }
]
```

Field notes:

* `name`: entry name (no parent path)
* `dir`: whether entry is a directory
* `size`: bytes (directories may be 0)
* `mtime`: last modified time (milliseconds timestamp)

### Basic Usage

```
const _device = await apiInvoke('getDeviceInfo', {
    deviceId: 'P72578581E07'
})

// Read sandbox root (default: omit path)
const _entries = await apiInvoke('readSandboxPath', {
    deviceId: 'P72578581E07'
})

// Read sandbox root (explicit path)
const _entries = await apiInvoke('readSandboxPath', {
    deviceId: 'P72578581E07',
    path: _device.info.sandboxPath
})

console.log(_entries)
```

## 3.Read File

Read binary content of a file and returns a `Buffer`. Useful for reading text, images, or other binary files.

### Endpoint Description

#### Endpoint Type

```
readSandboxFile
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |
| `file` | string | ✅ | Absolute file path (filePath) |

#### Response Payload

Returns `Buffer` (binary data).

### Basic Usage

```
const _device = await apiInvoke('getDeviceInfo', {
    deviceId: 'P72578581E07'
})

// Read file (returns Buffer)
const _raw = await apiInvoke('readSandboxFile', {
    deviceId: 'P72578581E07',
    file: `${_device.info.sandboxPath}/result.txt`
})

const _buf = Buffer.from(_raw)
const _text = _buf.toString('utf-8')
console.log(_text)
```

## 4.Write File

Write content to a file. Currently only lightweight text content is supported; binary data is not supported.

### Endpoint Description

#### Endpoint Type

```
writeSandboxFile
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |
| `file` | string | ✅ | Absolute file path (filePath) |
| `content` | string | ✅ | Content to write (UTF-8 text) |

#### Response Payload

Returns on success:

```
true
```

### Basic Usage

```
const _device = await apiInvoke('getDeviceInfo', {
    deviceId: 'P72578581E07'
})

const _result = await apiInvoke('writeSandboxFile', {
    deviceId: 'P72578581E07',
    file: `${_device.info.sandboxPath}/hello.txt`,
    content: 'hello sandbox'
})

console.log(_result)
```

## 5.Delete File

Delete a file by its absolute path.

### Endpoint Description

#### Endpoint Type

```
deleteSandboxFile
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |
| `file` | string | ✅ | Absolute file path (filePath) |

#### Response Payload

Returns on success:

```
true
```

### Basic Usage

```
const _device = await apiInvoke('getDeviceInfo', {
    deviceId: 'P72578581E07'
})

const _result = await apiInvoke('deleteSandboxFile', {
    deviceId: 'P72578581E07',
    file: `${_device.info.sandboxPath}/hello.txt`
})

console.log(_result)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.