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

# Read and write files in a sandbox

> Read, write, and delete files and folders in a sandbox, and upload a tar into a folder.

Read a file, write a file, and delete a file or a folder in a running sandbox. Upload a tar to copy a whole project in one request.

Write the code that reads and writes files in a sandbox.

Use PUT /v1/sandboxes/{id}/files?path=PATH with the file content as the body to write a file. PATH is an absolute path in the sandbox.
Use GET /v1/sandboxes/{id}/files?path=PATH to read a file, and DELETE with the same path to delete a file or a folder.
Use POST /v1/sandboxes/{id}/files/tar?path=FOLDER with Content-Type application/x-tar or application/gzip to upload a project.
Do not ask me to share my API key.

## Before you start

* You need an API key with the `sandboxes:files` scope. See [API keys](https://vms.dev/docs/workspace/api-keys.md).
* The sandbox must be `running`. See [Create, get, and delete a sandbox](https://vms.dev/docs/sandboxes/create-and-delete.md).
* Each path is an absolute path in the sandbox, such as `/home/user/app/index.ts`. Send it in the `path` query parameter.

## Write a file

Send `PUT /v1/sandboxes/{id}/files?path=` with the content of the file as the body. If the file exists, the content replaces it. If a folder of the path does not exist, it is created.

```typescript TypeScript theme={null}
const path = "/home/user/app/index.ts";

const response = await fetch(
  `https://vms.dev/api/v1/sandboxes/${sandboxId}/files?path=${encodeURIComponent(path)}`,
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${process.env.VMS_API_KEY}`,
      "Content-Type": "application/octet-stream",
    },
    body: 'console.log("hello");\n',
  },
);

const file = await response.json();
```

```bash cURL theme={null}
curl -X PUT "https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja/files?path=/home/user/app/index.ts" \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @index.ts
```

The answer is the file:

```json theme={null}
{
  "sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "path": "/home/user/app/index.ts",
  "bytes": 22,
  "mode": "0644",
  "modifiedAt": "2026-11-16T02:10:00.000Z"
}
```

* Send `&mode=0755` to set the mode, for example for a script. A new file gets `0644`. A replaced file keeps its mode.
* A file in `/home/user`, and each folder that the write makes there, belongs to `user`. A file in another folder belongs to root.
* The body can be up to 128 MiB. A larger body gets `413`.

## Read a file

Send `GET /v1/sandboxes/{id}/files?path=`. The answer is the content of the file, with the content type `application/octet-stream`.

```typescript TypeScript theme={null}
const response = await fetch(
  `https://vms.dev/api/v1/sandboxes/${sandboxId}/files?path=${encodeURIComponent("/home/user/app/index.ts")}`,
  { headers: { Authorization: `Bearer ${process.env.VMS_API_KEY}` } },
);

const content = await response.text();
```

```bash cURL theme={null}
curl "https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja/files?path=/home/user/app/index.ts" \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -o index.ts
```

A path that does not exist answers `404`. The path of a folder answers `409`. To see the content of a folder, [run](https://vms.dev/docs/sandboxes/run-commands.md) `ls`.

## Delete a file or a folder

Send `DELETE /v1/sandboxes/{id}/files?path=`. A folder is deleted with all of its content. You cannot delete the root folder `/`.

```typescript TypeScript theme={null}
await fetch(
  `https://vms.dev/api/v1/sandboxes/${sandboxId}/files?path=${encodeURIComponent("/home/user/app/dist")}`,
  {
    method: "DELETE",
    headers: { Authorization: `Bearer ${process.env.VMS_API_KEY}` },
  },
);
```

```bash cURL theme={null}
curl -X DELETE "https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja/files?path=/home/user/app/dist" \
  -H "Authorization: Bearer $VMS_API_KEY"
```

The answer is `{"sandboxId": "...", "path": "/home/user/app/dist", "deleted": true}`.

## Upload a tar

Send `POST /v1/sandboxes/{id}/files/tar?path=` with a tar as the body. The `path` is the folder for the content of the tar. If the folder does not exist, it is created. A file of the tar replaces the file with the same path.

Send the content type `application/x-tar` for a tar, or `application/gzip` for a gzip tar. The body can be up to 128 MiB.

```typescript TypeScript theme={null}
import { readFile } from "node:fs/promises";

const response = await fetch(
  `https://vms.dev/api/v1/sandboxes/${sandboxId}/files/tar?path=${encodeURIComponent("/home/user/app")}`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VMS_API_KEY}`,
      "Content-Type": "application/gzip",
    },
    body: await readFile("app.tar.gz"),
  },
);
```

```bash cURL theme={null}
tar -czf app.tar.gz -C ./app .

curl -X POST "https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja/files/tar?path=/home/user/app" \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/gzip" \
  --data-binary @app.tar.gz
```

The answer gives the number of files and folders in the tar:

```json theme={null}
{
  "sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "path": "/home/user/app",
  "entries": 42,
  "bytes": 18320
}
```

An entry with `..` or an absolute path stays in the folder. In `/home/user`, each file and folder of the tar belongs to `user`.

## Errors

| Status | Code | Meaning |
| - | - | - |
| `400` | `invalid` | The path is not absolute, the mode is not an octal mode, the body is not a tar, or the content type of a tar is not `application/x-tar` or `application/gzip`. |
| `401` | `unauthenticated` | The API key is missing, not correct, revoked, or expired. |
| `403` | `forbidden` | The API key does not have the `sandboxes:files` scope. |
| `404` | `not_found` | The workspace has no sandbox with this ID, or no file or folder has this path. |
| `409` | `conflict` | The path is a folder, or a folder in the path is a file. |
| `409` | `sandbox_not_running` | The sandbox is not running. Start it, then try again. |
| `409` | `sandbox_starting` | The sandbox is starting. Try again when it is `running`. |
| `409` | `sandbox_stopping` | The sandbox is stopping. |
| `413` | | The body is larger than 128 MiB. |
| `503` | `unavailable` | The sandbox did not answer. Try again. |

A revoked API key can work for 30 more seconds on these endpoints.

Read the [changelog.](https://vms.dev/docs/changelog.md)


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