---
title: "Files"
description: "Read and write files in a sandbox by path, with sizes, modes and errors."
---

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

# Files

You read and write one file at a time, by its absolute path in the sandbox. A file call on a
suspended sandbox resumes it first; on a stopped sandbox it's refused with
`409 sandbox_not_running`.

```sh
ezgh sandboxes cp ./job.sh scratch:/work/job.sh
ezgh sandboxes cp scratch:/work/result.json ./result.json
ezgh sandboxes cp scratch:/var/log/job.log -
```

One side is `<sandbox>:<absolute path>`. `-` is stdin or stdout.

## Write a file

[Write a file](/sandboxes-api/WriteFile/): the request body is the file.

| | |
| --- | --- |
| Size | At most 5 GiB. |
| Time | At most 900 seconds a transfer. |
| `path` | Absolute, at most 4096 bytes. |
| `mode` | The file's permission bits as three octal digits; default `0644`. `--mode` in the CLI. |

A write replaces the file at the path only once all of it has arrived. A transfer that ends early
writes nothing, and the file that was there stays as it was.

## Read a file

[Read a file](/sandboxes-api/ReadFile/) streams the file's bytes. The answer has no length:
a transfer that ends early is an error, and the CLI never leaves a partial file that
looks complete.

## Directories

A file call takes one file, and no call lists a directory or describes a file: run a
[command](/sandboxes/commands) such as `ls -l` or `stat` for that. Copy a directory with `tar` through an
[interactive command](/sandboxes/commands#interactive-commands):

```sh
tar -C ./src -cf - . | ezgh sandboxes exec -i scratch -- tar -xf - -C /work
ezgh sandboxes exec scratch -- tar -C /work -cf - out | tar -xf -
```

## Errors

| Answer | Means |
| --- | --- |
| `404 not_found` | There's no file at the path. |
| `400 invalid_request` | The path is a directory. |
| `403 file_permission_denied` | The file can't be read or written there. |
| `413` | The file is over 5 GiB. |
| `507 disk_full` | The sandbox's disk is full. |

Source: https://docs.ezghcloud.com/sandboxes/files/index.mdx
