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

# Filesystem

> Complete guide to file operations in HopX sandboxes - reading, writing, listing, uploading, downloading, and watching files. Work with files in sandboxes using comprehensive file operations, from basic read/write to advanced file watching and bulk transfers. Includes Python and JavaScript SDK examples and REST API endpoints for all file operations.

Work with files in HopX sandboxes using comprehensive file operations. This hub covers all filesystem operations, from basic read/write to advanced file watching and bulk transfers.

## Related

* [CLI File Operations](/cli/commands/files) - File operations from CLI

## What You'll Learn

* How to read and write files in sandboxes
* How to list directories and navigate the filesystem
* How to upload and download files to/from sandboxes
* How to watch files for changes
* How to manage file permissions and metadata

## File Operations Overview

| Operation                                                | SDK Method                 | API Endpoint             |
| -------------------------------------------------------- | -------------------------- | ------------------------ |
| **[Reading](/core-concepts/filesystem/reading)**         | `sandbox.files.read()`     | `GET /files/read`        |
| **[Writing](/core-concepts/filesystem/writing)**         | `sandbox.files.write()`    | `POST /files/write`      |
| **[Listing](/core-concepts/filesystem/listing)**         | `sandbox.files.list()`     | `GET /files/list`        |
| **[Uploading](/core-concepts/filesystem/uploading)**     | `sandbox.files.upload()`   | `POST /files/upload`     |
| **[Downloading](/core-concepts/filesystem/downloading)** | `sandbox.files.download()` | `GET /files/download`    |
| **[Watching](/core-concepts/filesystem/watching)**       | `sandbox.files.watch()`    | `WebSocket /files/watch` |

## Core Concepts

### Reading Files

Read file contents from sandboxes as text or binary data.

* **[Reading Files](/core-concepts/filesystem/reading)** - Read file contents
* **SDK**: [Python: sandbox.files.read()](/sdk/python/files#read) | [JavaScript: sandbox.files.read()](/sdk/javascript/files#read)
* **API**: [GET /files/read](/api/vm-agent/read-file)

### Writing Files

Write text or binary data to files in sandboxes.

* **[Writing Files](/core-concepts/filesystem/writing)** - Write file contents
* **SDK**: [Python: sandbox.files.write()](/sdk/python/files#write) | [JavaScript: sandbox.files.write()](/sdk/javascript/files#write)
* **API**: [POST /files/write](/api/vm-agent/write-file)

### Listing Files

List directory contents and navigate the filesystem.

* **[Listing Files](/core-concepts/filesystem/listing)** - List directories and files
* **SDK**: [Python: sandbox.files.list()](/sdk/python/files#list) | [JavaScript: sandbox.files.list()](/sdk/javascript/files#list)
* **API**: [GET /files/list](/api/vm-agent/list-files)

### Uploading Files

Upload files from your local machine to sandboxes.

* **[Uploading Files](/core-concepts/filesystem/uploading)** - Upload files to sandboxes
* **SDK**: [Python: sandbox.files.upload()](/sdk/python/files#upload) | [JavaScript: sandbox.files.upload()](/sdk/javascript/files#upload)
* **API**: [POST /files/upload](/api/vm-agent/upload-file)

### Downloading Files

Download files from sandboxes to your local machine.

* **[Downloading Files](/core-concepts/filesystem/downloading)** - Download files from sandboxes
* **SDK**: [Python: sandbox.files.download()](/sdk/python/files#download) | [JavaScript: sandbox.files.download()](/sdk/javascript/files#download)
* **API**: [GET /files/download](/api/vm-agent/download-file)

### Watching Files

Watch files and directories for changes in real-time.

* **[Watching Files](/core-concepts/filesystem/watching)** - Monitor file changes
* **SDK**: [Python: sandbox.files.watch()](/sdk/python/files#watch) | [JavaScript: sandbox.files.watch()](/sdk/javascript/files#watch)
* **API**: [WebSocket /files/watch](/api/vm-agent/watch-file)

## SDK Reference

### Python SDK

Complete reference for Python file operations.

* **[Files Module](/sdk/python/files)** - Complete filesystem API
  * `files.read()` - Read files
  * `files.write()` - Write files
  * `files.list()` - List directories
  * `files.upload()` - Upload files
  * `files.download()` - Download files
  * `files.watch()` - Watch files
  * `files.exists()` - Check existence
  * `files.remove()` - Delete files
  * `files.mkdir()` - Create directories

### JavaScript SDK

Complete reference for JavaScript/TypeScript file operations.

* **[Files Module](/sdk/javascript/files)** - Complete filesystem API
  * `files.read()` - Read files
  * `files.write()` - Write files
  * `files.list()` - List directories
  * `files.upload()` - Upload files
  * `files.download()` - Download files
  * `files.watch()` - Watch files
  * `files.exists()` - Check existence
  * `files.remove()` - Delete files
  * `files.mkdir()` - Create directories

## API Reference

### VM Agent API

REST API endpoints for file operations.

* **[VM Agent API Overview](/api/vm-agent/overview)** - API overview
* **[Read File](/api/vm-agent/read-file)** - `GET /files/read` - Read file contents
* **[Write File](/api/vm-agent/write-file)** - `POST /files/write` - Write file contents
* **[List Files](/api/vm-agent/list-files)** - `GET /files/list` - List directory contents
* **[File Exists](/api/vm-agent/file-exists)** - `GET /files/exists` - Check file existence
* **[Remove File](/api/vm-agent/remove-file)** - `DELETE /files/remove` - Delete files
* **[Create Directory](/api/vm-agent/mkdir)** - `POST /files/mkdir` - Create directories

## Quick Start

If you're new to file operations, start here:

1. **[Reading Files](/core-concepts/filesystem/reading)** - Read your first file
2. **[Writing Files](/core-concepts/filesystem/writing)** - Write files to sandboxes
3. **[Listing Files](/core-concepts/filesystem/listing)** - Navigate directories

## Related Topics

* **[Code Execution](/core-concepts/code-execution/synchronous)** - Execute code that works with files
* **[Sandboxes](/core-concepts/sandboxes/creating)** - Create sandboxes for file operations
* **[Commands](/core-concepts/commands/running)** - Run shell commands for file operations
* **[Environment Variables](/core-concepts/environment/getting)** - Configure file paths

## Next Steps

* Learn about [Code Execution](/core-concepts/code-execution/synchronous) to process files
* Explore [Commands](/core-concepts/commands/running) for shell-based file operations
* Review [Uploading Files](/core-concepts/filesystem/uploading) for bulk transfers
* Check out [Watching Files](/core-concepts/filesystem/watching) for real-time monitoring