Skip to main content
Workflows run a sequence of file operations on a serverhost. You can run them manually or whenever a server starts or stops. This guide creates a backup workflow, runs it from the dashboard, and then shows you how to adapt it.

​
Run the backup workflow

1

Create the workflow

Create workflows/default/backup.yml in your serverhost directory:
workflows/default/backup.yml
2

Load the workflow

Restart the serverhost. SimpleCloud uses the file path as the workflow ID, so this workflow becomes default/backup.
3

Assign the workflow

In the dashboard, open a server group or persistent server and go to Settings > Workflows. Under Manual Workflows, add default/backup.
4

Run the workflow

Start the server if it is not already running. Then open its actions menu and run default/backup to test the workflow.
5

Check the backup

On the serverhost, open:
Confirm that the final directory contains the files you expected. Its timestamp and process ID keep separate backup runs apart.
A workflow is available only on serverhosts that contain its file. If the affected servers can run on multiple serverhosts, add the same file to each one and restart them.
The manual action copies files while the Minecraft server is running. Files that change during the copy, such as worlds and plugin data, may not form a consistent backup. For those files, add default/backup under On Stop Workflows and stop the server normally. Stop workflows run after the server process exits. Place default/backup before internal/cleanup.
internal/cleanup removes a group server’s running directory. Any workflow that reads that directory must run before cleanup.
This workflow creates file copies but does not test restores or remove old backups. Verify that you can restore the data you need and manage retention for templates/.backup/.

​
Understand the workflow file

The backup workflow contains the same basic structure as every workflow:
  • name identifies the workflow in serverhost logs.
  • steps contains the operations in the order they run.
  • name inside a step identifies that step in logs.
  • uses selects the action. This workflow uses simplecloud/copy.
  • with contains the values required by the action.
In this workflow, from points to the running server directory and to builds a unique backup path. If the source is missing, init-dir-if-missing: true creates an empty source directory instead of failing. Always verify that the resulting backup contains the expected files.

​
Values used by the workflow

Values inside {{ ... }} are replaced when the workflow runs.

​
Adapt the backup workflow

Use the backup workflow as a starting point:
1

Copy the workflow

Copy workflows/default/backup.yml to a new path, such as workflows/custom/world-backup.yml.
2

Change the workflow

Give it a new name, then change the copy paths and exclusions for your task.
3

Reload the workflows

Restart every serverhost that contains the new file.
4

Assign the new ID

Add custom/world-backup under Settings > Workflows. A workflow ID is always its path below workflows/, without .yml.

​
Change what gets copied

The simplecloud/copy action accepts these settings under with: For example, add an exclude list to skip logs and caches while keeping the rest of the backup unchanged:
Patterns in exclude are relative to from.

​
Available actions

simplecloud/copy copies a file or directory from from to to. Use replace to control whether existing files are overwritten and exclude to skip matching paths.
simplecloud/compress creates an archive and simplecloud/decompress extracts one. Both require from and to; replace is optional. The archive filename determines its format.
simplecloud/upload sends the file in from to the URL in to. It uploads files, not directories. You can also set the HTTP method and an authorization-bearer value.
Workflow files are plain text. Do not store long-lived access tokens in them.
simplecloud/delete removes the configured path. Use min-age, such as 7d, to keep newer files.
Delete paths are not limited to the server directory. Check the final path before running the workflow.
simplecloud/foreach runs nested steps for each entry in items. Set as to the variable name used by the nested steps.

​
Built-in workflows

Keep internal/setup and internal/cleanup assigned unless you intentionally replace their behavior.

​
Troubleshooting

Workflow IDs are entered manually in the dashboard. Confirm the file exists on the serverhost, restart the serverhost, and add the ID again.
Check that the ID matches the file path. For example, custom/world-backup must point to workflows/custom/world-backup.yml.
Check the serverhost logs for Backup Workflow and copy-running-to-backup. For an automatic backup, also confirm that default/backup comes before internal/cleanup.