Set up the Tarkle remote for rclone

Beta. The rclone backend for Tarkle is in beta. It is not in any official rclone release yet, so a standard rclone install does not show a Tarkle storage type. The backend is in rclone pull request 10250, which rclone’s maintainers have not yet reviewed or merged. Until it is merged, you build rclone from Tarkle’s fork. This path is for people who are comfortable with Go and a terminal.

This page sets up a Tarkle remote in rclone and runs the first commands. One API key covers the API, the MCP server and rclone.

Build rclone from Tarkle’s fork

The fork needs Go 1.26. Clone it, switch to the tarkle-backend branch and build a binary:

git clone https://github.com/tarkleHQ/rclone
cd rclone
git checkout tarkle-backend
go build -o rclone-tarkle .
./rclone-tarkle version

The rest of this page runs ./rclone-tarkle in place of rclone. Build rclone from source describes the build in more detail.

Create the API key and find the workspace key

Only an owner or admin of the organization can create API keys. Open Settings, API and stay on the API keys tab. Click Create, enter a name and choose the Access. All workspaces lets the key reach every workspace of the organization. Only selected workspaces limits it to the workspaces you tick. The key is shown once, when it is created. You can copy it again later from the key’s menu with Copy token. The help article How to create and manage an API key shows the screen, and API keys explains the key itself.

A key does everything the API and the MCP server can do in the workspaces it reaches, and it acts as the person who made it. The one thing it cannot do is make purchases. A key with a Legacy badge was made with fewer permissions than a new key, so create a new key for rclone.

The workspace key is eight lowercase letters and digits. A key can reach more than one workspace, so rclone needs the workspace key to know which one to use. To list the workspace keys, call the workspaces endpoint with the API key. That call needs no workspace key:

curl -H "Authorization: Bearer <your-tarkle-key>" https://tarkle.com/api/v1/workspaces

The answer lists the workspaces the key can reach, and each one has a workspace_key. Copy the key of the workspace you want.

Set up the remote with rclone config

Run ./rclone-tarkle config and type n to make a new remote.
Type a name for the remote, for example tarkle.
At the storage prompt, type tarkle.
At token, paste your API key, <your-tarkle-key>. rclone stores it obscured in its config file.
At workspace, type the workspace key. Set it, because a key can reach more than one workspace.
Answer n at the advanced config question unless you need one of the advanced settings below.
Confirm the remote with y.

Set up the remote without prompts

Pass the same values to config create. Run the key through rclone obscure first, because rclone reads the token obscured:

./rclone-tarkle config create tarkle tarkle token="$(./rclone-tarkle obscure '<your-tarkle-key>')" workspace=<workspace-key>

To keep the key out of the config file, set environment variables instead. TARKLE_KEY is a shell variable you set yourself. rclone reads RCLONE_TARKLE_TOKEN and RCLONE_TARKLE_WORKSPACE:

export TARKLE_KEY='<your-tarkle-key>'
export RCLONE_TARKLE_TOKEN="$(./rclone-tarkle obscure "$TARKLE_KEY")"
export RCLONE_TARKLE_WORKSPACE=<workspace-key>
./rclone-tarkle lsf :tarkle:

What a blank workspace does

If you leave workspace empty, rclone does not choose a workspace, even when the key reaches only one. The next command you run stops with an error. That error lists the workspace keys and names the key can reach, and asks you to set the workspace to one of them. Set it to a key from that list and run the command again.

If the key is limited to chosen workspaces and you name a workspace it does not reach, Tarkle answers 403 no_access. Limits and errors lists the errors rclone can show.

Advanced settings

Leave these at their defaults unless you need to change them. Set them in rclone config, or with a flag such as --tarkle-upload-concurrency 2.

Setting	Default	What it does
`url`	`https://app.tarkle.com`	The address of the app. The API is served from `<url>/api/v1`.
`list_chunk`	`1000`	The number of items asked for in each list call. Accepts 1 to 1000.
`upload_concurrency`	`4`	The number of parts of one file uploaded at the same time. Each part is held in memory while it uploads, so the memory for one file is the part size chosen by Tarkle times this number.
`delete_transfers`	`false`	Also deletes the transfers that contain a file or folder being deleted. Without it, deleting an item in an active transfer fails and names the transfers. Feedback boards and paid transfers with purchases are never deleted this way.
`disable_listr`	`false`	Turns off the recursive listing (`GET /files?recursive=true`) that rclone can use for a whole folder tree.

First commands

Replace tarkle with your remote name, and put the local folder first in a copy or sync.

./rclone-tarkle lsf tarkle:
./rclone-tarkle copy ./photos tarkle:photos
./rclone-tarkle check ./photos tarkle:photos
./rclone-tarkle sync ./photos tarkle:photos --dry-run
./rclone-tarkle about tarkle:

lsf lists the files and folders at the top of your library.
copy sends files from your computer to the remote.
check compares the two sides by content. Tarkle supports SHA-256 hashes. Modification times have a precision of one second. sync works without --size-only.
sync makes the remote match the folder. A file on the remote that is not in the folder is deleted from the remote. Tarkle moves it to the bin. Run it with --dry-run first to see what would change.
about shows the storage in use. When the workspace has a storage limit, it also shows the total and free space.

Keep the key safe

Make one key for each use, for example one for a laptop and one for a server. Then you can delete one without stopping the others.
Delete a key you no longer use. Open its menu in Settings, API and choose Delete. The key stops working at once.
Never commit rclone.conf to Git or share it. rclone stores the key in it obscured, so treat the file like a password.

Next steps

Limits and errors covers file size, rate limits and the errors rclone shows. API errors lists every error code the API sends. Authentication explains how the API key and the workspace key are sent with each request.