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

# SFTP Upload

> Agent tool that delivers a platform file to a folder on a connected SFTP server.

This document covers `export_to_sftp` (display name **"SFTP Upload"**), the agent tool that delivers a platform file to a folder on a connected SFTP server.

For automated inbound folder polling, see [SFTP File Import Trigger](/docs/tools/sftp-file-import).

## Authentication and enablement

The tool uses a workspace SFTP credential integration (`integrations.service_name = 'sftp'`). The hidden `integration_id` is resolved from the configured tool binding with `first_active`; credentials are loaded in the worker only after verifying that the integration belongs to the task workspace and is active.

Both password and PEM private-key authentication are supported. Every export requires the host-key fingerprint captured during connection validation, so the tool does not silently fall back to an unverified SSH host.

Off by default — enable it in the agent's Tools panel. It is billed at the same per-call rate as the OneDrive and SharePoint export tools.

## Inputs

Required:

* `file_url`: URL of the source file in platform storage, or from a tool such as `generate_file`, `python_code`, or another file-producing tool.
* `file_name`: Destination filename including its extension, for example `invoice-1722000000.edi`. It must be a single filename, not a path.

Optional:

* `folder_path`: Folder beneath the integration's configured `base_path`, for example `qa/reports`. Missing folders are created automatically. Omitted means the configured base path.
* `conflict_behavior`:
  * `replace` (default): converge on one destination path. An existing file is atomically replaced using the OpenSSH POSIX rename extension.
  * `rename`: preserve the existing file and choose `name (1).ext`, `name (2).ext`, and so on.
  * `fail`: return an error without changing the existing file.

Absolute paths, `..` traversal, sibling-prefix escapes, separators in `file_name`, and NUL bytes are rejected before upload.

## Upload mechanics

1. Download the complete source through the platform file-storage service.
2. Resolve the destination beneath the connection's absolute `base_path`.
3. Write a unique hidden temporary sibling such as `.report.csv.part-<uuid>`.
4. Close the complete temporary file.
5. Rename it into the final destination.
6. Stat the final file and verify its byte count.

Temporary files are removed on handled failures. A worker or server crash can leave an orphaned `.part-*` file, but it cannot expose a partial file under the requested final name.

Replacing an existing file requires server support for `posix-rename@openssh.com`; the tool returns an error instead of falling back to non-atomic remove-then-rename behavior. New files and `rename` deliveries use standard SFTP rename.

## Size and retry behavior

The maximum source size is **500 MB**, matching platform file storage. The current implementation downloads and uploads the content from worker memory.

The default `replace` behavior is retry-friendly: repeating the same call converges on the same path and content. `rename` intentionally creates another uniquely named file on a retry. If exactly-once delivery matters, use a deterministic filename with `replace`, or make the receiving system idempotent.

## Output

The structured result contains:

* `tool_name`
* the final `file_name` (including any conflict suffix)
* requested `folder_path`
* `file_size`
* applied `conflict_behavior`
* `completed_at`

SFTP does not provide a public file URL, so the tool returns destination metadata rather than a link.

## Auditing and errors

Connect, stat, create-folder, put, rename, and cleanup operations emit host-only `external_call` audit events under `ProviderSftp`. Audit events do not include remote paths, file names, credentials, or file contents.

Common failures include:

* missing or expired source `file_url`
* invalid destination path or filename
* inactive or cross-workspace integration
* missing or changed host-key fingerprint
* authentication or remote folder permission failure
* same-name collision with `conflict_behavior: "fail"`
* SFTP server without POSIX rename support when replacing an existing file
* final remote size not matching the source byte count