How to set up Auto-Sync

Auto-Sync automatically keeps your BedrockMap up to date whenever your server creates a new backup. Instead of manually downloading your world and re-uploading it each time, Auto-Sync handles the entire process for you.

There are three methods available, depending on your server setup:

• Server Pull — Backup File (SFTP/FTP) — BedrockMap connects to your server on a schedule via SFTP, FTP, or FTPS, finds the latest backup file, and downloads it automatically
• Server Pull — Live Server Folder (SFTP/FTP) — BedrockMap connects during a scheduled server shutdown window and downloads the raw world folder directly, without needing a backup file
• API Push — A script on your server uploads the latest backup to BedrockMap whenever it runs (via cron job or Task Scheduler)

Both methods feed into the same render pipeline — the result is identical to manually re-uploading your world from the dashboard. If you have Timelines enabled, each sync automatically creates a new timeline snapshot.

Before setting up Auto-Sync, ensure you have:

• BedrockMap Premium subscription — Auto-Sync is a Premium-only feature
• An existing world on BedrockMap — you must have already uploaded your world at least once
• Server backups or a scheduled shutdown window — either regular backups (for Backup File or API Push) or a daily time when your server is stopped (for Live Server Folder)

Additionally, depending on the method you choose:

All three methods achieve the same result. Choose whichever is easiest for your server setup:

Backup File mode lets BedrockMap connect to your server on a daily schedule via SFTP, FTP, or FTPS, find the latest backup file, and download it for rendering. This is the most common Server Pull setup.

1. Navigate to your world's Dashboard → Auto-Sync tab
2. Select the Server Pull (SFTP/FTP) sub-tab
3. Choose your Protocol:
   • SFTP — SSH File Transfer Protocol (port 22). The most common and most secure option. Used by most hosting providers.
   • FTPS — FTP over TLS (port 21). Encrypted FTP connection. Use this if your host only offers FTP with TLS.
   • FTP — Plain FTP (port 21). Unencrypted — only use this if your host doesn't support SFTP or FTPS. Credentials are sent in plain text.
4. Fill in your connection details:
   • Host — your server's hostname or IP address (e.g. play.myserver.com)
   • Port — usually 22 for SFTP or 21 for FTP/FTPS, but many game panels use a custom port like 2022 or 2222
   • Username — your SFTP/FTP username
   • Password — your password (stored encrypted, never in plain text)
   • Remote Backup Path — the full path to the folder on your server that contains the backup files
5. Click Test Connection to verify the credentials and path are correct. You should see a list of backup files found in the folder.
6. Configure the backup schedule:
   • Backup Time — the time your server creates its daily backup. The time picker is shown in your local timezone, with the UTC equivalent displayed alongside.
   • Check Delay — how long to wait after the backup time before downloading. This gives the backup process time to complete. 15–30 minutes is usually sufficient.
7. Click Save Configuration

Finding your connection details

Where to find your SFTP/FTP credentials depends on your hosting provider. Here are the most popular ones:

Common backup paths

The remote backup path depends on your server setup. Here are some common examples:

# Bisect Hosting / Sparked Host (Pterodactyl-based)
/home/container/backups/

# Shockbyte (check via their file manager)
/backups/

# Self-hosted Bedrock Dedicated Server
/opt/bedrock-server/backups/
/home/minecraft/backups/

# Self-hosted Java server
/opt/minecraft/backups/
/home/minecraft/server/backups/

File pattern

By default, Auto-Sync looks for *.mcworld and *.zip files. If your server uses a different file extension for backups, you can customise the file pattern in the advanced settings. Separate multiple patterns with commas.

Live Server Folder mode is designed for hosting providers that only give you SFTP/FTP access to the live server files — not to a separate backup folder. Instead of downloading a backup file, BedrockMap connects during a scheduled server shutdown window and downloads the raw world folder directly.

When to use this mode

• Your hosting provider only gives you SFTP/FTP access to the live server files (no backup folder)
• Your server doesn't create backup files, or the backups are stored somewhere inaccessible via SFTP/FTP
• You have a daily scheduled restart or maintenance window when the server is stopped

Setup steps

1. Navigate to your world's Dashboard → Auto-Sync tab
2. Select the Server Pull (SFTP/FTP) sub-tab
3. Choose your Protocol (SFTP, FTP, or FTPS) and fill in your connection details (host, port, username, password) as described in the Backup File section above
4. Under Source Type, select "Live server folder"
5. Set the Remote Path to the directory that contains your Minecraft world folder(s). Common paths:

   # Bedrock Dedicated Server
   /bedrock-server/worlds
   
   # Java Fabric/Vanilla server
   /minecraft
   
   # Pterodactyl-based hosts
   /home/container

6. Click Test Connection. BedrockMap will scan the remote directory and list any Minecraft worlds it finds. Each detected world shows its name, folder name, and edition (Bedrock or Java).
   • If one world is found, it is auto-selected
   • If multiple worlds are found, click the one you want to sync
   • If no worlds are found, check the remote path — it should point to the folder containing the world, not the world folder itself
7. Set the shutdown time — the time your server is reliably stopped every day. The time picker is shown in your local timezone, with the UTC equivalent displayed alongside. BedrockMap will connect shortly after this time to download the world.
8. Set the buffer time — how long to wait after the shutdown time before connecting. Minecraft servers shut down almost instantly, so 1 minute is usually enough.
9. Click Save Configuration

API Push uses a script running on your server that finds the latest backup and uploads it to BedrockMap. This is ideal when you have SSH access and can set up a scheduled task.

Step 1: Generate an API key

1. Navigate to your world's Dashboard → Auto-Sync tab
2. Select the API Push sub-tab
3. Click Generate API Key
4. Your API key and a one-line install command will be displayed

Step 2: Install the sync script

Copy the one-line install command from the dashboard and run it on your server via SSH. The installer will:

• Create a ~/.bedrockmap/ config directory
• Save your API key and endpoint URLs to a config file
• Download the sync script to ~/bedrockmap-sync.sh (Linux/Mac) or bedrockmap-sync.ps1 (Windows)
• Make the script executable

Linux/Mac installer:

curl -sSL "https://bedrockmap.online/api/sync/setup/YOUR_TOKEN" | bash

Windows (PowerShell) installer:

irm "https://bedrockmap.online/api/sync/setup/YOUR_TOKEN?platform=windows" | iex

Step 3: Test the script

Run the script manually first to make sure everything works:

~/bedrockmap-sync.sh /path/to/your/backup/folder

The script will:

1. Find the newest .mcworld or .zip file in the folder
2. Check if the file is still being written (waits 3 seconds to verify the file size is stable)
3. Check locally if the file has changed since the last sync
4. Ask the BedrockMap server if an upload is needed (preflight check)
5. Upload the file if everything passes

A successful run looks like:

[2025-01-15 09:35:12] BedrockMap Auto-Sync starting...
  Backup folder: /home/amp/.ampdata/instances/MyServer/Backups
  Latest backup: MyWorld-2025-01-15.zip (788.68 MB)
  Modified: 2025-01-15 09:00:05
  Checking with BedrockMap server...
  Uploading MyWorld-2025-01-15.zip (788.68 MB)...
[OK] Upload complete! Render has been queued.
[2025-01-15 09:35:45] Sync finished successfully.

If the file hasn't changed, you'll see:

[SKIP] File unchanged since last sync (local check).

Using sudo for protected backup folders

If the backup folder is owned by a different user (common with game panels like CubeCoders AMP), you'll need to run the script with sudo:

sudo ~/bedrockmap-sync.sh /path/to/backup/folder

The script automatically detects when running via sudo and reads the config from the original user's home directory (not root's).

Once you've confirmed the script works by running it manually, set up automatic scheduling:

Linux/Mac: cron job

Open your crontab editor:

crontab -e

Add one of these lines:

# Run every hour
0 * * * * ~/bedrockmap-sync.sh /path/to/backups >> ~/bedrockmap-sync.log 2>&1

# Run every 6 hours
0 */6 * * * ~/bedrockmap-sync.sh /path/to/backups >> ~/bedrockmap-sync.log 2>&1

# Run once daily at 10:00 AM (server local time)
0 10 * * * ~/bedrockmap-sync.sh /path/to/backups >> ~/bedrockmap-sync.log 2>&1

If the backup folder requires sudo:

# With sudo (use full path to script)
0 * * * * sudo /home/youruser/bedrockmap-sync.sh /path/to/backups >> /home/youruser/bedrockmap-sync.log 2>&1

Windows: Task Scheduler

1. Open Task Scheduler (search for it in the Start menu)
2. Click Create Basic Task
3. Give it a name like BedrockMap Auto-Sync
4. Set the trigger (e.g. Daily, or at a specific time)
5. For the action, select Start a program
6. Set the program to: powershell.exe
7. Set the arguments to: -ExecutionPolicy Bypass -File "C:\Users\YourName\bedrockmap-sync.ps1" "C:\path\to\backups"
8. Click Finish

You can monitor your sync status from two places:

• Auto-Sync tab on your world's dashboard — shows the last sync status, recent sync history, and any error messages
• Sync log file (API Push only) — if you set up logging in your cron job, check ~/bedrockmap-sync.log

The sync history table shows each sync attempt with a colour-coded status:

• Success — file uploaded and render queued
• Skipped — file unchanged since last sync, nothing to do
• Failed — something went wrong (hover for error details)
• In Progress — currently downloading/processing

Manual Sync

For Server Pull configs, you can trigger an immediate sync at any time using the Sync Now button on the Auto-Sync settings page. This bypasses the daily schedule and dedup checks — useful for testing your setup or forcing a re-render after configuration changes. The sync will be picked up by the worker within 5 minutes of clicking the button.

Common issues

Auto-Sync handles sensitive credentials. Here's how they are protected:

• SFTP/FTP passwords are encrypted using AES-256-GCM with a per-encryption random salt and IV before being stored in the database. They are never stored in plain text.
• API keys (for API Push) are stored only on your server in the ~/.bedrockmap/config file. BedrockMap stores a hashed version for validation.
• Setup tokens (the one-line install command) expire after 15 minutes and can only be used once.
• Premium downgrade — if your Premium subscription expires, all sync configs are automatically deactivated and API keys are cleared.