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

# upload

Upload a file to Contree.

## TL;DR

* **Use when**: Single file, generated content
* **Returns**: File UUID for use with `run`
* **Cost**: No VM needed
* **Prefer**: `rsync` for multiple files (has caching)

## Parameters

| Parameter        | Type   | Required | Default | Description                                                                                                                                                                                        |
| ---------------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content`        | string | No\*     | -       | Text content                                                                                                                                                                                       |
| `content_base64` | string | No\*     | -       | Base64-encoded binary                                                                                                                                                                              |
| `path`           | string | No\*     | -       | Absolute path to a file on **local filesystem** to read and upload. Not a destination name — files are content-addressable (UUID). To name the file in a container, use `run`’s `files` parameter. |

\*One of `content`, `content_base64`, or `path` is required.

## Response

```json theme={null}
{
  "uuid": "file-uuid-123",
  "sha256": "abc123..."
}
```

## Examples

### Text Content

```json theme={null}
{"tool": "upload", "args": {
  "content": "print('hello world')"
}}
```

### Local File

```json theme={null}
{"tool": "upload", "args": {
  "path": "/path/to/script.py"
}}
```

### Binary (Base64)

```json theme={null}
{"tool": "upload", "args": {
  "content_base64": "SGVsbG8gV29ybGQ="
}}
```

## Using the Result

Pass the UUID to `run` via the `files` parameter:

```json theme={null}
// Step 1: Upload
{"tool": "upload", "args": {"content": "print('hello')"}}
// Returns: {"uuid": "file-uuid-123"}

// Step 2: Run
{"tool": "run", "args": {
  "command": "python /app/script.py",
  "image": "img-uuid",
  "files": {"/app/script.py": "file-uuid-123"}
}}
```

## Common Mistake

`path` reads from the **local MCP-server filesystem** — it does not set the file’s name in storage. The uploaded file is content-addressable and identified only by UUID. To place it at a specific path inside a container, pass the UUID to `run`’s `files` parameter:

```json theme={null}
{"tool": "run", "args": {
  "command": "python /app/script.py",
  "image": "img-uuid",
  "files": {"/app/script.py": "file-uuid-123"}
}}
```

## See Also

* [rsync](./rsync) - For multiple files (with caching)
* [run](./run) - Use uploaded files
* [download](./download) - Download from images