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

# Copy File

> Copy a file or directory tree inside a runtime

`POST /v1/agents/runtime/{runtime_id}/files/copy`

Copies a path inside the runtime. Copying a directory requires `recursive`.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from gravixlayer import GravixLayer

  client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
  sandbox = client.runtime.create()  # defaults to template="base-small"

  sandbox.file.write("/workspace/config.json", '{"debug": false}\n')

  result = sandbox.file.copy("/workspace/config.json", "/workspace/config.bak.json")
  print(result.success, result.destination)

  # Copy a whole tree
  sandbox.file.copy("/workspace/src", "/workspace/src-backup", recursive=True)

  sandbox.kill()
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { GravixLayer } from 'gravixlayer';

  const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
  const sandbox = await client.runtime.create(); // defaults to template="base-small"

  await sandbox.file.write("/workspace/config.json", '{"debug": false}\n');

  const result = await sandbox.file.copy("/workspace/config.json", "/workspace/config.bak.json");
  console.log(result.success, result.destination);

  // Copy a whole tree
  await sandbox.file.copy('/workspace/src', '/workspace/src-backup', { recursive: true });

  await sandbox.kill();
  ```

  ```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  gravixlayer runtime files cp "$RT" /workspace/config.json /workspace/config.bak.json

  gravixlayer runtime files cp "$RT" /workspace/src /workspace/src-backup --recursive
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/files/copy" \
    -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"source": "/workspace/src", "destination": "/workspace/src-backup", "recursive": true}'
  ```
</CodeGroup>

## Parameters

| Parameter     | Type    | Required | Description                                                     |
| ------------- | ------- | -------- | --------------------------------------------------------------- |
| `source`      | string  | Yes      | Existing absolute path                                          |
| `destination` | string  | Yes      | Destination absolute path                                       |
| `recursive`   | boolean | No       | Required to copy a directory tree. Defaults to `false`          |
| `overwrite`   | boolean | No       | Replace `destination` if it already exists. Defaults to `false` |

Copying a directory without `recursive` fails rather than copying only the directory inode.

## Response (`FileCopyResponse`)

| Field         | Type    | Description                                               |
| ------------- | ------- | --------------------------------------------------------- |
| `success`     | boolean | Whether the copy succeeded                                |
| `source`      | string  | The path that was copied                                  |
| `destination` | string  | The new path                                              |
| `entry`       | object  | `FileInfo` for the destination, when the guest reports it |