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

# File Operations

> File operations resource for reading, writing, and managing files in HopX sandboxes using the JavaScript/TypeScript SDK. Complete reference for the Files class including async methods for reading, writing, listing, uploading, downloading, and watching files. Includes TypeScript examples for all file operations.

**Version:** 0.1.22\
**Last Verified:** 2025-01-27\
**Package:** `@hopx-ai/sdk` on [npm](https://www.npmjs.com/package/@hopx-ai/sdk)

## Overview

The `Files` resource provides file operations for sandboxes. Access it via the `files` property on a `Sandbox` instance. All file operations are async and work with both text and binary files.

## Access

```typescript theme={null}
import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({ template: 'code-interpreter' });
const files = sandbox.files; // Lazy-loaded
```

## Methods

### `read`

Read text file contents.

```typescript theme={null}
async files.read(path: string): Promise<string>
```

**Parameters:**

* `path` (`string`): File path to read

**Returns:** `Promise<string>` - File contents as string

**Example:**

```typescript theme={null}
const content = await sandbox.files.read('/workspace/script.py');
console.log(content);
```

***

### `readBytes`

Read binary file contents.

```typescript theme={null}
async files.readBytes(path: string): Promise<Buffer>
```

**Returns:** `Promise<Buffer>` - File contents as Buffer

***

### `write`

Write text file.

```typescript theme={null}
async files.write(
    path: string,
    content: string,
    options?: FileWriteOptions
): Promise<void>
```

**Parameters:**

* `path` (`string`): File path to write
* `content` (`string`): Text content
* `options.mode` (`string`, optional): File permissions

***

### `writeBytes`

Write binary file.

```typescript theme={null}
async files.writeBytes(
    path: string,
    content: Buffer,
    options?: FileWriteOptions
): Promise<void>
```

***

### `list`

List directory contents.

```typescript theme={null}
async files.list(path: string): Promise<EnhancedFileInfo[]>
```

**Returns:** `Promise<EnhancedFileInfo[]>` - Array of file/directory information objects

***

### `exists`

Check if file/directory exists.

```typescript theme={null}
async files.exists(path: string): Promise<boolean>
```

**Returns:** `Promise<boolean>` - `true` if exists, `false` otherwise

***

### `remove`

Remove file or directory.

```typescript theme={null}
async files.remove(path: string): Promise<void>
```

***

### `mkdir`

Create directory.

```typescript theme={null}
async files.mkdir(path: string): Promise<void>
```

***

### `download`

Download file (alias for `readBytes`).

```typescript theme={null}
async files.download(path: string): Promise<Buffer>
```

***

## Examples

### Example 1: Basic File Operations

```typescript theme={null}
import { Sandbox } from '@hopx-ai/sdk';

async function main() {
    const sandbox = await Sandbox.create({ template: 'code-interpreter' });
    
    // Write a file
    await sandbox.files.write('/workspace/hello.py', "print('Hello, World!')");
    
    // Read it back
    const content = await sandbox.files.read('/workspace/hello.py');
    console.log(content);
    
    // Execute it
    const result = await sandbox.runCode(
        "exec(open('/workspace/hello.py').read())"
    );
    console.log(result.stdout);
    
    await sandbox.kill();
}

main();
```

***

## Related Classes

* **[Sandbox](/sdk/javascript/sandbox)** - Main sandbox class
* **[Commands](/sdk/javascript/commands)** - Command execution resource
* **[Types](/sdk/javascript/types)** - TypeScript type definitions

## See Also

* [Core Concepts: Files](/core-concepts/files) - Learn about file operations
* [Sandbox Class](/sdk/javascript/sandbox) - Access files via `sandbox.files`

## Related

* **[Python SDK: Files](/sdk/python/files)** - Python SDK file operations
* **[Reading Files](/core-concepts/filesystem/reading)** - Learn about reading files
* **[Writing Files](/core-concepts/filesystem/writing)** - Learn about writing files

## Next Steps

* Learn about [Reading Files](/core-concepts/filesystem/reading) to access file contents
* Explore [Writing Files](/core-concepts/filesystem/writing) to create files
* Review [Uploading Files](/core-concepts/filesystem/uploading) for local file transfers
* **[CLI File Operations](/cli/commands/files)** - Use file operations from CLI