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

> Create or overwrite a file inside a sandbox.

Writes a file to the specified path inside the sandbox. If the file already
exists it is overwritten. Parent directories are created automatically if they
do not exist. Returns the envd write response.

## Path Parameters

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

## Request Body

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

  Example: `"/home/user/script.py"`
</ParamField>

<ParamField body="data" type="string" required>
  File content as a UTF-8 string. This endpoint is **text-only** — it cannot
  carry arbitrary bytes. For binary payloads (images, compiled artifacts,
  base64-decoded blobs) use the streaming
  [`PUT /files/raw`](/api-reference/filesystem/write-raw) endpoint with
  `Content-Type: application/octet-stream` (500 MiB cap). The Python and
  TypeScript SDKs dispatch automatically based on payload type — pass `bytes`
  / `Uint8Array` to `files.write()` and the SDK routes to `/files/raw` for you.

  Example: `"print('hello')\n"`
</ParamField>

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

  Example: `"user"`
</ParamField>

## Response

Returns the envd write confirmation as a JSON object.

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.declaw.ai/sandboxes/sbx-a1b2c3d4/files \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "path": "/home/user/script.py",
      "data": "print(\"hello\")\n"
    }'
  ```

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

  sbx = Sandbox.connect("sbx-a1b2c3d4", api_key="YOUR_API_KEY", domain="api.declaw.ai")
  sbx.files.write("/home/user/script.py", "print('hello')\n")
  ```

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

  const sbx = await Sandbox.connect("sbx-a1b2c3d4", {
    apiKey: "YOUR_API_KEY",
    domain: "api.declaw.ai",
  });
  await sbx.files.write("/home/user/script.py", "print('hello')\n");
  ```
</CodeGroup>

## Error Responses

| Status | Cause                                                |
| ------ | ---------------------------------------------------- |
| `400`  | Invalid request body                                 |
| `401`  | Missing or invalid API key                           |
| `404`  | Sandbox not found                                    |
| `409`  | Sandbox is paused — resume it before accessing files |
| `410`  | Sandbox has been killed                              |
| `502`  | envd daemon unreachable                              |
| `503`  | Sandbox has no VM                                    |