Manage server files

The Files tab is a file manager for your server's disk. Use it to change configuration files, add plugins or worlds and tidy up, without installing anything on your computer. For whole folders or files over 100 MB, connect with SFTP instead.

• On a server someone shared with you, the owner must have given you the Files permission. It covers everything on this page, and SFTP.
• You cannot change files while the server is installing or being moved, and you cannot open them at all during a move.
• Most games read their settings when they start. Restart the server after you edit a configuration file, and stop it before you replace its world, so it does not save over your change.

1. In the dashboard, go to App Deployment and open the server, then the Files tab.
2. Select a folder's name to open it. The path above the list shows where you are. Select any folder in the path, or the home icon at its start, to go back up.

The list shows each entry's Name, Size, Modified date and Mode, its permissions such as -rw-r--r--. Folders come first. A Symlink badge marks a link to another file. Select Refresh to read the folder again. The folder is part of the page address, so you can bookmark it or send the link to someone who shares the server.

1. Select the file's name, or open the menu at the end of its row and select Edit…. A page opens with the file's name as its heading, and its path and size under it. The folder it is in stays in the page address as ?edit= and the path, so you can bookmark the page.
2. Make your change. Clear Wrap long lines to keep each line on one row.
3. Select Save file, or press Ctrl+S (⌘+S on a Mac). The page stays open, so you can keep editing and save again.
4. Select Close, or the link above the heading, which reads Files, or Files in and the folder's name, to go back to the list.

The editor opens text files up to 2 MB, such as .yml, .json, .properties and .txt files. Selecting the name of any other file downloads it. Opening the page address of a file the editor cannot open shows This file is too large to edit here or This file is not text, with a Download button. An Unsaved changes badge shows until you save. Leaving the page with unsaved changes asks Discard your changes?: select Keep editing to stay, or Discard changes to leave. A transfer you started keeps reporting in Transfers while the editor is open.

The editor will not save over a change it has not shown you. If the file changed on the server after you opened it, the save stops and the page says the file changed on the server. Select Reload to read the new text, which replaces what you typed. Select Save over it to keep your text and replace the server's.

1. Open the folder to create it in.
2. Select New, then New file… or New folder….
3. A row opens at the top of the list. Enter the File name or Folder name, then select Create file or Create folder, or press Enter. Press Esc or select Cancel to close the row.

A new file is empty, so select its name to add content. The dashboard does not create a file or folder over one that already exists, and the row says so under the field. A name cannot contain / and can be up to 255 characters.

1. Open the folder to upload into.
2. Select Upload and choose one or more files, or drag files from your computer onto the list.

The Transfers panel shows each file's progress, and Cancel stops one. Each file can be up to 10 GB, and each goes up on its own, so a large file does not hold up the others. An upload replaces a file of the same name without asking.

The dashboard uploads files, not folders. To upload a folder, compress it on your computer, upload the archive and extract it, or use SFTP.

• Open the menu at the end of a file's row and select Download. Selecting the name of a file the editor cannot open downloads it too.
• To download a folder, compress it and download the archive.

Fetch a file straight onto the server, such as a plugin from its release page, without saving it on your computer first.

1. Open the folder to save the file in.
2. Select New, then Download from URL…. A card opens above the list.
3. Enter the URL, an http or https address.
4. Optionally, enter a name in Save as. Leave it empty to keep the name from the URL.
5. Select Download to server. The card closes, and focus returns to New.

If the server does not accept the address, the card stays open with what you typed and says why under Could not download from the URL. Press Esc or select Cancel to close it without downloading.

The download shows in the Transfers panel with its progress while the server fetches the file, and the folder shows the file once the server has it. Cancel stops the download on the server, and the panel marks it Cancelled. Dismiss clears a row that has ended.

Leaving the tab does not stop a download. When you come back, the panel picks up every download still running on the server, with its address, or Download started earlier when the server does not say. We fetch only public http and https addresses.

1. Open the menu at the end of the row and select Rename. The name turns into a field in the row.
2. Type the new name and press Enter or select Rename, or press Esc or select Cancel to leave the name as it was.

To move a file or folder, type a path relative to the current folder as its new name: ../Essentials.jar moves it up one folder, and old/Essentials.jar moves it into the old folder. A path that starts with / begins at the server root. The row refuses an empty name, a path above the server root and a name that is already taken in the same folder, and says why under the field.

To copy a file, select Duplicate in its menu. The copy appears in the same folder with copy in its name. Folders cannot be duplicated.

1. Tick the box beside each file and folder to include. The number you picked shows above the list.
2. Select Compress…. A card opens above the list and names what it includes.
3. Select Compress.

The archive is a .tar.gz file saved in the server root folder, whichever folder you are in, and the server chooses its name. Open the root folder to find the new archive, then rename it if you want. The job shows in Transfers.

Open the menu at the end of the archive's row and select Extract here. The files go into the folder that holds the archive, and they replace files with the same names.

Extract here appears for .zip, .tar, .tar.gz, .tgz, .tar.bz2, .tbz2, .tar.xz, .txz, .rar, .7z, .gz, .bz2 and .xz files.

1. Open the menu at the end of the row and select Permissions…. A card opens above the list with the file's name in its heading.
2. Tick Read, Write and Execute for Owner, Group and Others, or type three digits in Octal, such as 644 for a file or 755 for a folder.
3. Select Apply permissions. Select Cancel or press Esc to close the card without a change.

1. Open the menu at the end of the row and select Delete file… or Delete folder…. To delete several at once, tick their boxes and select Delete….
2. Confirm with Delete file, Delete folder, or the button that gives the number of items.

Each action confirms with a message, such as File saved. or Folder created., and the list shows the change. Uploads, downloads, archives and downloads from a URL report in the Transfers panel, which marks each one Done or says why it failed.

<file name> changed on the server

The server, another person or an SFTP client changed the file after you opened it, so the editor did not save. Select Reload to read the new text, or Save over it to replace the server's text with yours.

File changes are paused while the server is installing.

The server is installing or being moved. Try again when it has finished.

File exceeds maximum upload size of 10 GB

Upload the file over SFTP, or use Download from URL… if the file is online.

Network error on an upload

The upload sent nothing for 60 seconds, usually because the connection dropped. Upload the file again. On an unreliable connection, upload large files over SFTP, where a client such as FileZilla can resume.

Could not list this folder

The dashboard could not read the folder, and the message under it gives the reason. Try again, and if the server is being moved, wait until it finishes.

URL targets a private or reserved network

Download from URL… only fetches from public addresses.

URL scheme must be one of: https, http

The address starts with something else, such as ftp://. Use the file's https or http address, or download it to your computer and upload it.

A download from a URL shows Done, but the file is not in the folder

The panel marks a download Done once the server stops working on it, and the server does not say whether it got the file. When the file is missing, the server could not fetch it, for example because the address needs a sign-in. Open the address in a browser to check it, then try again, or download the file to your computer and upload it.

Could not stop the download

The server did not answer the request to stop it, so the download stays in the panel. Select Cancel again.

Too many requests for this action. Try again later.

You compressed and extracted more than 24 times, or downloaded from a URL more than 24 times, on this server in 60 seconds. Wait a minute and try again.

Edit… is missing from the menu

The editor opens text files up to 2 MB. Download a larger file, edit it on your computer and upload it again, or edit it over SFTP.

• Connect to a server with SFTP for large files and whole folders.
• Take a server snapshot before a big change, so you can go back.
• Server limits and rate limits lists every file limit.

Every file route is under /api/v1/client/servers/{uuid}/files/. Paths start at the server root, such as /plugins/config.yml. A path that climbs above the root with .. is refused, and a request that names several files takes up to 200.

List a folder with GET files/list:

curl "https://api.coritan.com/api/v1/client/servers/$SERVER/files/list?directory=/plugins" \
  -H "Authorization: Bearer $CORITAN_TOKEN"

The response is {"files": [...]}. Each entry has name, size in bytes, mode (such as -rw-r--r--), mode_bits (such as 644), file, directory and symlink (each true or false), mime, created and modified.

GET files/contents?path=/server.properties returns the file's text as content and its SHA-256 as hash. POST files/write takes path, content (up to 8 MB) and expected_hash:

• Send the hash you read, and the write is refused if the file has changed since.
• Send "", and the write only creates a new file.
• Leave expected_hash out to overwrite the file whatever it holds.

curl -X POST https://api.coritan.com/api/v1/client/servers/$SERVER/files/write \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/server.properties", "content": "motd=Welcome to survival-smp\n", "expected_hash": "<hash from files/contents>"}'

A refused write answers 409 with code set to file_conflict, the file's current_hash, and missing set to true when the file is gone. A successful write returns the new hash.

Upload with POST files/upload, a multipart form with one files field per file, each up to 10 GB. A request can carry up to 10 GB in all; over that, it answers 413 with {"error":"Request body too large"}, so send large files one per request. The response lists what landed in files and what did not, with the reason, in failed.

curl -X POST "https://api.coritan.com/api/v1/client/servers/$SERVER/files/upload?directory=/plugins" \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -F "files=@EssentialsX.jar"

GET files/download?path=/logs/latest.log streams the file as an attachment. With curl, add -OJ to save it under its own name.

The other routes take a JSON body:

GET files/pull/status lists the downloads still running on the server in downloads, each with its identifier, its url and its progress from 0 to 1. A download leaves the list when the server stops working on it. POST files/pull/cancel?download_id=<identifier> stops one:

curl -X POST "https://api.coritan.com/api/v1/client/servers/$SERVER/files/pull/cancel?download_id=$DOWNLOAD" \
  -H "Authorization: Bearer $CORITAN_TOKEN"

While the server is installing or being moved, changes answer 409 with reason set to server_busy, the server's status and a message.

On a server shared with you, each route needs one permission: file.read to list files or running downloads, file.read-content to read or download, file.create to create, upload, copy, pull or stop a pull, file.update to write, rename or change permissions, file.delete to delete, and file.archive to compress or extract. The Files permission in the dashboard grants all of them, and file.sftp as well.