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

# Move File

> Move or rename a file or directory inside a runtime

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

Moves or renames a path. The guest uses the native `rename` syscall when the source and
destination live on the same filesystem, which is atomic and does not copy any data.
Across filesystems it falls back to a copy followed by an unlink.

<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/draft.txt", "hello\n")

  result = sandbox.file.move("/workspace/draft.txt", "/workspace/final.txt")
  print(result.success, result.source, result.destination)

  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/draft.txt", "hello\n");

  const result = await sandbox.file.move("/workspace/draft.txt", "/workspace/final.txt");
  console.log(result.success, result.source, result.destination);

  await sandbox.kill();
  ```

  ```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  gravixlayer runtime files mv "$RT" /workspace/draft.txt /workspace/final.txt
  ```

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

## Parameters

| Parameter     | Type    | Required | Description                                                     |
| ------------- | ------- | -------- | --------------------------------------------------------------- |
| `source`      | string  | Yes      | Existing absolute path                                          |
| `destination` | string  | Yes      | New absolute path                                               |
| `overwrite`   | boolean | No       | Replace `destination` if it already exists. Defaults to `false` |

Without `overwrite`, moving onto an existing path fails rather than silently destroying it.

## Response (`FileMoveResponse`)

| Field         | Type    | Description                                               |
| ------------- | ------- | --------------------------------------------------------- |
| `success`     | boolean | Whether the move succeeded                                |
| `source`      | string  | The path that was moved                                   |
| `destination` | string  | The path it now occupies                                  |
| `entry`       | object  | `FileInfo` for the destination, when the guest reports it |