# Manage server files

> Browse, edit, upload, download, archive and extract your server's files in the dashboard file manager.

Source: https://docs.coritan.com/managed-containers/files/

In the dashboard:

- /dashboard/servers/…/files: https://www.coritan.com/dashboard/servers

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](/managed-containers/sftp/) instead.

## Before you begin

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

## Find your way around

1. In the [dashboard](https://www.coritan.com/dashboard/servers), go to **Container Apps** 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.

## Edit a file

1. Select the file's name, or open the menu at the end of its row and select **Edit…**.
2. Make your change. Clear **Wrap long lines** to keep each line on one row.
3. Select **Save file**, or press <kbd>Ctrl</kbd>+<kbd>S</kbd> (<kbd>⌘</kbd>+<kbd>S</kbd> on a Mac).

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. An **Unsaved changes** badge shows until you save, and closing the editor with unsaved changes asks you to confirm with **Discard changes**.

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 asks you to reopen the file.

## Create a file or folder

1. Open the folder to create it in.
2. Select **New**, then **New file…** or **New folder…**.
3. Enter the **File name** or **Folder name**, then select **Create file** or **Create folder**.

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

## Upload files

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 100 MB. 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](#extract-an-archive), or use SFTP.

## Download files

- 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](#compress-files-into-an-archive) and download the archive.

## Download a file from a URL

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…**.
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 server downloads the file after you confirm, so a large file can take a while to appear. Select **Refresh** to check. Addresses on private networks are refused.

## Rename, move or duplicate

1. Open the menu at the end of the row and select **Rename**.
2. Type the new name and press <kbd>Enter</kbd>, or press <kbd>Esc</kbd> to cancel.

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.

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.

## Compress files into an archive

1. Tick the box beside each file and folder to include. The number you picked shows above the list.
2. Select **Compress…**, then **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. The **Archive name** you enter is not used. Open the root folder to find the new archive, then rename it if you want.

## Extract an archive

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.

## Change permissions

1. Open the menu at the end of the row and select **Permissions…**.
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**.

## Delete files and folders

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.

> [!CAUTION]
> Deleting a folder deletes everything in it, and you cannot undo it. The only way back is a [snapshot](/managed-containers/snapshots/) taken before you deleted the files.

## Result

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.

## Troubleshooting

`The file changed on the server since you opened it. Reopen it and save again.`
: The server, another person or an SFTP client changed the file after you opened it. Copy your change, close the editor, open the file again and make the change once more.

`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 100 MB`
: Upload the file [over SFTP](/managed-containers/sftp/), or use **Download from URL…** if the file is online.

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

`Free servers cannot modify or upload core server executables. …`
: On a free server you cannot upload, overwrite or rename the file the server runs, such as `server.jar`, or extract an archive that contains it. Change what the server runs on the **Software** tab. See [Change the server software](/managed-containers/software/).

`Free servers can extract archives of up to 1 GB through the panel, …`
: A free server checks every archive before it extracts it, and cannot check one over 1 GB. Extract the archive on your computer and upload the files.

`URL targets a private or reserved network`
: **Download from URL…** only fetches from public addresses.

`Too many requests for this action. Please wait and try again.`
: 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.

## Related

- [Connect to a server with SFTP](/managed-containers/sftp/) for large files and whole folders.
- [Take a server snapshot](/managed-containers/snapshots/) before a big change, so you can go back.
- [Server limits and rate limits](/managed-containers/limits/) lists every file limit.

## With the API

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`:

```bash
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.

```bash
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 100 MB. The response lists what landed in `files` and what did not, with the reason, in `failed`.

```bash
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:

| Route | Example body | What it does |
|---|---|---|
| `POST files/mkdir` | `{"root": "/", "name": "plugins"}` | Creates the folder `name` in `root`. |
| `POST files/copy` | `{"location": "/plugins/config.yml"}` | Copies a file into the same folder. |
| `POST files/rename` | `{"old_path": "/notes.txt", "new_path": "/old/notes.txt"}` | Renames or moves a file or folder. |
| `POST files/delete` | `{"path": "/logs"}` | Deletes one file, or one folder with everything in it. |
| `POST files/chmod` | `{"root": "/plugins", "files": [{"file": "config.yml", "mode": "644"}]}` | Sets permissions. `mode` is three octal digits, or four starting with `0`. |
| `POST files/compress` | `{"paths": ["/world", "/server.properties"], "archive_name": "world"}` | Makes a `.tar.gz` in `/`. `archive_name` is required but not used; the response's `archive` describes the new file. |
| `POST files/decompress` | `{"archive_path": "/uploads/world.zip", "destination": "/uploads"}` | Extracts into the folder that holds the archive. `destination` counts only when `archive_path` is a bare file name. |
| `POST files/pull` | `{"url": "https://example.com/plugin.jar", "destination_path": "/plugins", "filename": "plugin.jar"}` | Starts a download onto the server and returns its `identifier`. `filename` is optional. |

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, `file.read-content` to read or download, `file.create` to create, upload, copy or 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.

## API

- `POST /api/v1/client/servers/{uuid}/files/chmod`: Set the mode of files under root: [{"file": name, "mode": "0644"}] (https://docs.coritan.com/api/reference/client/container-apps/servers-files/#op-post-api-v1-client-servers-uuid-files-chmod)
- `POST /api/v1/client/servers/{uuid}/files/compress`: Create a compressed archive of files (https://docs.coritan.com/api/reference/client/container-apps/servers-files/#op-post-api-v1-client-servers-uuid-files-compress)
- `GET /api/v1/client/servers/{uuid}/files/contents`: Get contents of a file (https://docs.coritan.com/api/reference/client/container-apps/servers-files/#op-get-api-v1-client-servers-uuid-files-contents)
- `POST /api/v1/client/servers/{uuid}/files/copy`: Duplicate a file next to itself; Wings picks the name copy suffix (https://docs.coritan.com/api/reference/client/container-apps/servers-files/#op-post-api-v1-client-servers-uuid-files-copy)
- `POST /api/v1/client/servers/{uuid}/files/decompress`: Extract an archive on the server (https://docs.coritan.com/api/reference/client/container-apps/servers-files/#op-post-api-v1-client-servers-uuid-files-decompress)
- `POST /api/v1/client/servers/{uuid}/files/delete`: Delete a file (https://docs.coritan.com/api/reference/client/container-apps/servers-files/#op-post-api-v1-client-servers-uuid-files-delete)
- `GET /api/v1/client/servers/{uuid}/files/download`: Stream one file from Wings through the platform, as an attachment (https://docs.coritan.com/api/reference/client/container-apps/servers-files/#op-get-api-v1-client-servers-uuid-files-download)
- `GET /api/v1/client/servers/{uuid}/files/list`: List files in a server directory (https://docs.coritan.com/api/reference/client/container-apps/servers-files/#op-get-api-v1-client-servers-uuid-files-list)
- `POST /api/v1/client/servers/{uuid}/files/mkdir`: Create a folder name under root (https://docs.coritan.com/api/reference/client/container-apps/servers-files/#op-post-api-v1-client-servers-uuid-files-mkdir)
- `POST /api/v1/client/servers/{uuid}/files/pull`: Download and save a file from a URL (https://docs.coritan.com/api/reference/client/container-apps/servers-files/#op-post-api-v1-client-servers-uuid-files-pull)
- `POST /api/v1/client/servers/{uuid}/files/rename`: Rename a file (https://docs.coritan.com/api/reference/client/container-apps/servers-files/#op-post-api-v1-client-servers-uuid-files-rename)
- `POST /api/v1/client/servers/{uuid}/files/upload`: Multipart upload proxied to Wings, so the browser never talks to the node (https://docs.coritan.com/api/reference/client/container-apps/servers-files/#op-post-api-v1-client-servers-uuid-files-upload)
- `POST /api/v1/client/servers/{uuid}/files/write`: Write content to a file (https://docs.coritan.com/api/reference/client/container-apps/servers-files/#op-post-api-v1-client-servers-uuid-files-write)