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

# Write File (Raw / Binary)

> Stream raw bytes into a sandbox file. Binary-safe, up to 500 MiB per request.

Streams the request body directly into a file on the sandbox disk without
buffering in memory. Use this endpoint for any binary payload — images,
archives, compiled artifacts, base64-decoded blobs — or for uploads larger
than the 10 MiB JSON gateway cap.

For UTF-8 text, the JSON [`POST /files`](/api-reference/filesystem/write)
endpoint is usually the simpler choice.

## Path Parameters

<ParamField path="sandbox_id" type="string" required>
  The sandbox identifier. Format: `sbx-<8 chars>`.
</ParamField>

## Query Parameters

<ParamField query="path" type="string" required>
  Absolute path to write inside the sandbox. Parent directories are created
  automatically.

  Example: `/home/user/image.png`
</ParamField>

<ParamField query="username" type="string">
  Unix user to own the written file. Defaults to the envd default user.
</ParamField>

## Request Headers

<ParamField header="Content-Type" type="string" required>
  Must be `application/octet-stream`.
</ParamField>

## Request Body

Raw bytes. Up to **500 MiB** per request. The body is streamed to disk with a
flat memory footprint on the orchestrator.

## Response

```json theme={null}
{
  "path": "/home/user/image.png",
  "size": 4096
}
```

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.declaw.ai/sandboxes/sbx-a1b2c3d4/files/raw?path=/home/user/image.png" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/octet-stream" \
    --data-binary @image.png
  ```

  ```python Python theme={null}
  from declaw import Sandbox

  sbx = Sandbox.connect("sbx-a1b2c3d4", api_key="YOUR_API_KEY", domain="api.declaw.ai")

  # The SDK automatically routes bytes payloads to /files/raw.
  with open("image.png", "rb") as f:
      sbx.files.write("/home/user/image.png", f.read())
  ```

  ```typescript TypeScript theme={null}
  import { Sandbox } from "@declaw/sdk";
  import { readFileSync } from "node:fs";

  const sbx = await Sandbox.connect("sbx-a1b2c3d4", {
    apiKey: "YOUR_API_KEY",
    domain: "api.declaw.ai",
  });

  // Pass a Uint8Array — the SDK routes to /files/raw for binary payloads.
  const bytes = new Uint8Array(readFileSync("image.png"));
  await sbx.files.write("/home/user/image.png", bytes);
  ```
</CodeGroup>

## When to use this vs. other endpoints

| Payload                                        | Use                                                       |
| ---------------------------------------------- | --------------------------------------------------------- |
| UTF-8 text, \< 10 MiB                          | [`POST /files`](/api-reference/filesystem/write) (JSON)   |
| Binary (any size up to 500 MiB)                | `PUT /files/raw` (this endpoint)                          |
| Very large payloads (hundreds of MB, GB-class) | `sbx.upload_url(path)` / `sbx.download_url(path)` helpers |

## Error Responses

| Status | Cause                                                |
| ------ | ---------------------------------------------------- |
| `400`  | Missing `path` query parameter                       |
| `401`  | Missing or invalid API key                           |
| `404`  | Sandbox not found                                    |
| `409`  | Sandbox is paused — resume it before accessing files |
| `410`  | Sandbox has been killed                              |
| `413`  | Request body exceeds 500 MiB                         |
| `502`  | envd daemon unreachable                              |
| `503`  | Sandbox has no VM                                    |