DOCUMENTATION

Arkive — the complete guide

Everything you need to install, configure and operate Arkive on Bukkit / Spigot / Paper / Folia, BungeeCord and Velocity. Use the sidebar to jump around; every config key in this guide is documented in the generated config.yml as well.

Requirements

JarRuns onJavaNotes
Arkive-Bukkit.jarBukkit, Spigot, Paper, Purpur, Folia — 1.8 → latest8+Compiled against the 1.8 API; Folia uses the global region scheduler automatically.
Arkive-Bungee.jarBungeeCord, Waterfall8+Backs up the proxy folder.
Arkive-Velocity.jarVelocity 3.x, 4.x17+Native Adventure + SLF4J.

Optional: PlaceholderAPI (Bukkit) for %arkive_*% placeholders, mysqldump/pg_dump for database dumps, an open port for one-click cloud linking.

Installation

  1. Drop the jar for your platform into plugins/ and start the server once. plugins/Arkive/config.yml and messages.yml are generated.
  2. Open config.yml, set general.server-name and enable at least one entry under storages: (the local storage is enabled by default).
  3. Point your profile at those storages: profiles.full.storages: [local, s3].
  4. Run /arkive reload, then /arkive test — every storage must report ok.
  5. Run /arkive backup --force and watch the console. Done — the schedule takes over from here.
Tip

Config changes are only picked up on /arkive reload or a restart. A running backup is never interrupted by a reload.

Your first backup

> arkive test
[Arkive] Testing 2 storage(s)...
[Arkive] ✔ local (Local) ok (3 ms)
[Arkive] ✔ s3 (S3) ok (412 ms)
> arkive backup --force
[Arkive] Backup full queued.
[Arkive] Backup full started, you may notice a short lag spike...
[Arkive] Archive RetacafeSMP-full-2026-09-17_04-00-00.zip created: 41,208 files, 6.4 GB -> 2.1 GB
[Arkive] Uploaded RetacafeSMP-full-2026-09-17_04-00-00.zip to s3 (S3) in 1m 48s @ 19.7 MB/s
[Arkive] Pruned 1 old archive(s) from s3
[Arkive] Backup full finished (2.1 GB, 4m 36s)

--force bypasses the skip-if-no-players rule. Without a profile name every enabled profile runs one after another. Players with arkive.notify see the start/finish messages in chat.

Files & folders

PathPurpose
plugins/Arkive/config.ymlMain configuration (this guide).
plugins/Arkive/messages.ymlEvery chat/console message, colour codes with &. Missing keys are added on start.
plugins/Arkive/backups/Default folder of the local storage. Automatically excluded from archives.
plugins/Arkive/temp/Archives are assembled here before upload (change with general.temp-directory). Auto-excluded.
plugins/Arkive/tokens/OAuth tokens for Google Drive / Dropbox / OneDrive. Auto-excluded from archives — keep it private.
plugins/Arkive/restore/Downloads from /arkive restore.
plugins/Arkive/web/keystore.p12Self-signed certificate for the web-link server.
plugins/Arkive/history.jsonLast 50 backup results (feeds /arkive history and placeholders).

Profiles

A profile is one backup set: what to archive, when, where to upload it and how long to keep it. You can define as many as you like under profiles:. The key is the profile name and becomes the remote folder name.

profiles:
  full:                                  # whole server, nightly, off-site
    enabled: true
    schedule: { mode: cron, cron: "0 4 * * *" }
    include: []                           # empty = server root
    exclude: ["logs/**", "*.jar", "session.lock"]
    storages: [local, s3]
    file-name: "{server}-{profile}-{timestamp}"
    retention: { keep-last: 7, keep-weekly: 4, keep-monthly: 6 }

  worlds:                                # worlds only, hourly, local
    schedule: { mode: interval, interval: 1h, initial-delay: 10m }
    include: [world, world_nether, world_the_end]
    include-plugins: false
    storages: [local]
    retention: { keep-last: 24 }
KeyDefaultMeaning
enabledtrueDisabled profiles are never scheduled but can still be run manually with /arkive backup <profile>.
schedule.modeintervalinterval, cron or disabled (manual only).
schedule.interval6hDuration between runs (see durations).
schedule.cron0 4 * * *Five-field cron expression, evaluated in general.timezone.
schedule.initial-delay2mDelay before the first interval run after startup.
include[]Paths relative to the server folder. Empty = everything.
excludesee configGlob patterns (see include & exclude).
include-worldstruefalse adds every loaded world folder to the excludes (game servers).
include-pluginstruefalse excludes plugins/**.
storages[local]Storage ids to upload to. Empty = every enabled storage.
file-name{server}-{profile}-{timestamp}Placeholders: {server}, {profile}, {timestamp}, {platform}. Extension is added automatically.
retention.*—See retention.

Only one backup runs at a time. Scheduled runs that collide with a running backup are skipped and logged; manual runs with several profiles are queued one after another.

Scheduling & cron

Durations

Used by interval, initial-delay and elsewhere: 90s, 30m, 6h, 1d, 1w, combinations like 1d12h, or a plain number (minutes). Minimum interval is 60 seconds.

Cron

Standard five fields — minute hour day-of-month month day-of-week — with *, lists (1,15), ranges (1-5), steps (*/6, 0-30/10), month and weekday names (jan, mon; Sunday is 0 or 7) and the shortcuts @hourly, @daily, @weekly, @monthly.

ExpressionRuns
0 4 * * *Every day at 04:00
30 */3 * * *Every 3 hours at :30
0 2 * * sunSundays at 02:00
0 5 1 * *First day of every month at 05:00
0 0,12 * * mon-friWeekdays at midnight and noon
@hourlyEvery hour at :00

Set general.timezone (e.g. Asia/Jakarta) so cron times and archive timestamps match your wall clock; empty means the JVM default. /arkive status shows the next run of every profile.

Backup on shutdown

backup.backup-on-shutdown: true runs every enabled profile while the server stops (the stop waits for it, up to 30 minutes). World saving is skipped during shutdown because the server flushes worlds itself.

Include & exclude

Include entries are paths relative to the server folder (world, plugins/Essentials, server.properties). Leave it empty to archive the whole server folder. Exclude entries are glob patterns matched against the relative path with forward slashes:

PatternMatches
logs/**The logs folder and everything below it
*.jarAny file ending in .jar, at any depth (patterns without / match everywhere)
plugins/*/cache/**Every plugin's cache folder
world/region/r.-1.*.mcaSpecific files with wildcards
plugins/dynmap/web/tiles/**Large regenerable data

Always excluded regardless of config: the temp directory, plugins/Arkive/tokens, every local storage folder, and the archive currently being written. Files that are locked (e.g. session.lock, open region files on Windows) or vanish mid-backup are skipped and listed in the manifest and history — they never fail the run.

Retention

After every successful upload Arkive lists the profile folder on that storage and deletes old archives according to the profile's retention:

KeyDefaultRule
keep-last10The newest N archives are protected. 0 = unlimited.
max-age-days-1Unprotected archives older than N days are deleted.
max-total-size""Oldest unprotected archives are deleted while the folder exceeds this size (20GB, 500MB).
keep-daily0Protect the first archive of each of the last N days.
keep-weekly0Protect the first archive of each of the last N ISO weeks.
keep-monthly0Protect the first archive of each of the last N months.

How the rules combine: an archive is protected when it is among the keep-last newest or picked by a daily/weekly/monthly rule. Unprotected archives are removed when keep-last is set (> 0), when they are older than max-age-days, or — oldest first — while the folder exceeds max-total-size. With keep-last: 0 only the age and size limits delete anything.

Simple rotation

retention: { keep-last: 14 }

Always the 14 newest, nothing else.

Grandfather-father-son

retention:
  keep-last: 7
  keep-weekly: 4
  keep-monthly: 6

A week of dailies, a month of weeklies, half a year of monthlies.

Budget cap

retention:
  keep-last: 0
  max-total-size: 50GB

Keep as many as fit in 50 GB.

Time based

retention:
  keep-last: 3
  max-age-days: 30

Everything from the last 30 days, never fewer than 3.

/arkive prune [profile] applies the rules immediately on every ready storage. Arkive never deletes the archive it just uploaded.

Archives & manifest

Archives are zip (default, Zip64, any tool can open it) or tar.gz (backup.compression.format). compression.level goes from 0 (store, fastest) to 9 (smallest); 6 is a good balance, 1–3 if CPU is the bottleneck. Every archive contains arkive-manifest.json:

{
  "generator": "Arkive", "version": "1.0.0",
  "server": "RetacafeSMP", "platform": "Paper", "platformVersion": "1.21.4",
  "profile": "full", "createdAt": "2026-09-17T04:00:00Z", "format": "zip",
  "files": 41208, "rawBytes": 6871947673,
  "worlds": ["world", "world_nether", "world_the_end"],
  "include": [], "exclude": ["logs/**", "*.jar"],
  "databases": ["main"], "skipped": ["session.lock (locked)"]
}

Remote layout on every backend: <path or prefix>/<profile>/<file-name>.zip. With backup.verify-checksum: true a SHA-256 of the archive is stored in history.json and sent to webhooks. When a local storage is among the targets the archive is written straight into it (no extra copy).

Storage: Local disk

storages:
  local:
    type: local
    enabled: true
    path: backups            # relative to plugins/Arkive, or absolute: D:/Backups, /mnt/nas/mc

Any mounted drive or network share works. The folder is excluded from backups automatically. Several local storages (e.g. an internal disk and a NAS) are fine.

Storage: S3 & compatible

storages:
  s3:
    type: s3
    enabled: true
    endpoint: ""                 # empty for AWS, otherwise the provider URL
    region: us-east-1
    bucket: my-backups
    access-key: "AKIA..."
    secret-key: "..."
    prefix: minecraft            # key prefix inside the bucket
    path-style: false            # auto true when an endpoint is set
    storage-class: ""            # AWS only: STANDARD_IA, GLACIER_IR, DEEP_ARCHIVE
    part-size-mb: 32             # multipart chunk for archives > 64 MB
    chunked-encoding: true       # set false if a provider rejects streaming signatures
ProviderendpointregionNotes
AWS S3(empty)your bucket's regionOptional storage-class.
Cloudflare R2https://<account-id>.r2.cloudflarestorage.comautoToken from R2 → Manage API Tokens with Object Read & Write. Use path-style: true.
Backblaze B2https://s3.<region>.backblazeb2.come.g. us-west-004Application key with read/write on the bucket.
MinIOhttp://minio.local:9000us-east-1Self-hosted; http is fine on a LAN.
Wasabihttps://s3.<region>.wasabisys.come.g. eu-central-1
DigitalOcean Spaceshttps://<dc>.digitaloceanspaces.come.g. nyc3
Hetzner Object Storagehttps://<loc>.your-objectstorage.come.g. fsn1

If access-key is empty Arkive falls back to the AWS credential chain (environment variables, ~/.aws/credentials, instance profile) and logs a warning. Archives above 64 MB are sent as multipart uploads and aborted cleanly on failure. Test with /arkive test s3.

Storage: FTP / FTPS

  ftp:
    type: ftp
    enabled: true
    host: ftp.example.com
    port: 21                     # 990 for implicit TLS
    username: user
    password: "secret"
    secure: false                # true = FTPS
    implicit-tls: false          # implicit (port 990) instead of explicit AUTH TLS
    passive: true                # almost always right behind NAT
    path: /backups
    timeout-seconds: 30

Folders are created as needed. Prefer SFTP or FTPS — plain FTP sends the password unencrypted.

Storage: SFTP

  sftp:
    type: sftp
    enabled: true
    host: backup.example.com
    port: 22
    username: minecraft
    password: ""                 # password auth, or ...
    private-key: keys/id_ed25519 # ... key file (relative to plugins/Arkive or absolute)
    private-key-passphrase: ""
    path: backups                # relative to the SSH home, or absolute /srv/backups
    known-hosts: ""              # optional known_hosts file
    strict-host-key-checking: false
    timeout-seconds: 30

Generate a key on the server with ssh-keygen -t ed25519 -f plugins/Arkive/keys/id_ed25519 and add the .pub to ~/.ssh/authorized_keys on the backup host. RSA, ECDSA and Ed25519 keys are supported (OpenSSH and PEM formats). Set strict-host-key-checking: true with a known-hosts file to pin the host key.

Storage: WebDAV

  webdav:
    type: webdav
    enabled: true
    url: https://cloud.example.com/remote.php/dav/files/<user>/MinecraftBackups
    username: user
    password: "app-password"
    bearer-token: ""             # alternative to basic auth
    timeout-seconds: 60
ServiceURL pattern
Nextcloud / ownCloudhttps://host/remote.php/dav/files/<user>/<folder> — use an app password.
Synology (WebDAV Server)https://nas:5006/<shared-folder>
Hetzner Storage Boxhttps://<user>.your-storagebox.de/<folder>
Apache / nginx DAVAny collection URL.

Storage: Google Drive

  google-drive:
    type: google-drive
    enabled: true
    client-id: "....apps.googleusercontent.com"
    client-secret: "GOCSPX-..."
    folder: "Arkive Backups"      # created in My Drive (or the shared drive)
    shared-drive-id: ""          # optional Google Workspace shared drive

Arkive uses your own OAuth client, so nothing goes through third-party servers. Create it once:

  1. Open Google Cloud Console, create a project and enable the Google Drive API.
  2. Configure the OAuth consent screen (External, add yourself as a test user — no verification is needed for personal use).
  3. Create credentials → OAuth client ID:
    • TVs and Limited Input devices for the manual device-code flow, or
    • Web application with the authorised redirect URI https://<public-host>:<port>/callback/google-drive for one-click linking.
  4. Put client-id and client-secret in the config, /arkive reload, then /arkive link google-drive.

Arkive only requests the drive.file scope: it can see and manage the files it created, nothing else in your Drive. Uploads are resumable and existing files with the same name are replaced.

Storage: Dropbox

  dropbox:
    type: dropbox
    enabled: true
    app-key: "..."
    folder: "Arkive Backups"
  1. Create an app at dropbox.com/developers/apps: Scoped access, Full Dropbox or App folder.
  2. Permissions tab: enable files.metadata.read, files.content.write, files.content.read, account_info.read.
  3. For one-click linking add https://<public-host>:<port>/callback/dropbox under Redirect URIs.
  4. Copy the App key into the config. No secret is needed (PKCE).
  5. /arkive link dropbox — with web-link you just sign in; manually you paste the code back with /arkive link dropbox <code>.

Archives above 100 MB use upload sessions with 32 MB chunks.

Storage: OneDrive

  onedrive:
    type: onedrive
    enabled: true
    client-id: "00000000-0000-0000-0000-000000000000"
    client-secret: ""            # only for a confidential "Web" registration
    tenant: common               # common | consumers | organizations | <tenant-id>
    folder: "Arkive Backups"
  1. Open Microsoft Entra admin center → App registrations → New registration. Supported account types: Personal Microsoft accounts and any organization.
  2. Authentication → enable Allow public client flows (needed for the device code).
  3. For one-click linking add the platform Mobile and desktop applications with redirect URI https://<public-host>:<port>/callback/onedrive.
  4. API permissions: Files.ReadWrite, offline_access, User.Read (delegated).
  5. Copy the Application (client) ID into the config and run /arkive link onedrive.

Works with personal OneDrive and OneDrive for Business. Files above 4 MB use chunked upload sessions (10 MiB chunks).

Linking accounts (web-link)

Google Drive, Dropbox and OneDrive need a one-time authorisation. Arkive offers two ways:

A One-click web link

Arkive runs a small built-in HTTPS server. Click the printed link, sign in, done — the token is stored automatically. Needs one free port and a domain.

B Manual (device / paste code)

/arkive link <storage> --manual. Google & OneDrive show a short code to enter on a page; Dropbox gives a code to paste back. No inbound port needed.

Setting up the web link

web-link:
  enabled: true
  port: 8443                   # a FREE port (extra allocation on hosting panels)
  bind-address: "0.0.0.0"
  public-host: mc.example.com  # the DOMAIN of your server (Google refuses raw IPs)
  https: true                  # providers require https; a self-signed cert is generated
  on-demand: true              # only listen while a link is in progress
  timeout-minutes: 10
  1. Get a port. Pterodactyl / Pelican: Network tab → add an allocation → use that port. Self-hosted: pick a free port and open it in the firewall.
  2. Use a domain. public-host must be a hostname that resolves to your server (the domain players connect with, or the panel's node domain). Google rejects https://1.2.3.4:8443.
  3. Register the callback URL in the provider console exactly as https://<public-host>:<port>/callback/<storage-id> (e.g. https://mc.example.com:8443/callback/google-drive).
  4. /arkive reload then /arkive link google-drive. Arkive prints the sign-in link, the callback URL, and warnings about your setup.
  5. Open the link, sign in. Your browser shows a certificate warning once (self-signed) — continue. You land on a green "Linked!" page and the console confirms the account.
Warnings Arkive prints for you

Port already in use → pick another allocation. public-host is an IP → Google will refuse it. https disabled → providers only allow plain http on localhost. keytool not found → your Java has no keytool; install a full JDK or place your own PKCS12 keystore (password arkive-web) at plugins/Arkive/web/keystore.p12.

Tokens are saved in plugins/Arkive/tokens/<id>.json, refreshed automatically, and never leave your server. /arkive unlink <id> deletes them. The callback server only accepts requests carrying a valid one-time state and stops itself after the link (on-demand mode).

Database dumps

backup:
  databases:
    main:
      enabled: true
      type: mysql               # mysql | mariadb | postgres | custom
      host: 127.0.0.1
      port: 3306
      database: minecraft
      username: backup
      password: "secret"
      executable: ""            # e.g. /usr/bin/mysqldump when not on PATH
      extra-args: ["--skip-lock-tables"]
    stats:
      type: custom
      command: "sqlite3 plugins/Stats/data.db .dump > {output}"

Each dump is written to arkive-databases/<id>.sql inside the archive. MySQL/MariaDB use mysqldump --single-transaction --quick --routines --triggers with the password passed through MYSQL_PWD (not visible in the process list); PostgreSQL uses pg_dump with PGPASSWORD. A failed dump makes the backup partial (the archive is still created and uploaded) and the error is reported in Discord and history. Dumps time out after 30 minutes.

Hooks

backup:
  hooks:
    before:
      - "console:say Backup starting in a moment"
      - "sh /opt/scripts/pause-dynmap.sh"
    after:
      - "console:say Backup finished"
      - "/opt/scripts/notify.sh"

Entries prefixed with console: run as server console commands (on the main thread). Everything else runs in the OS shell (sh -c / cmd /c) from the server folder with a 10-minute timeout and these environment variables:

VariableValue
ARKIVE_PROFILEProfile name
ARKIVE_TRIGGERscheduled, manual (name), shutdown
ARKIVE_STATUSrunning (before) / success, partial, failed (after)
ARKIVE_ARCHIVEAbsolute path of the archive (after hooks; empty if it was already deleted)
ARKIVE_SERVERgeneral.server-name

Hook failures are logged but never abort the backup.

Discord & webhooks

notifications:
  discord:
    enabled: true
    webhook-url: "https://discord.com/api/webhooks/..."
    username: "Arkive"
    avatar-url: ""
    on-start: false
    on-success: true
    on-failure: true
  webhook:
    enabled: true
    url: "https://n8n.example.com/webhook/arkive"
    headers:
      Authorization: "Bearer xyz"

Discord receives a colour-coded embed (green success, yellow partial, red failed) with archive name, sizes, file count, duration, per-storage result and pruned counts. The generic webhook receives JSON:

{
  "event": "backup.finish", "server": "RetacafeSMP", "timestamp": 1758081876000,
  "result": {
    "profile": "full", "trigger": "scheduled", "status": "SUCCESS",
    "startedAt": 1758081600000, "finishedAt": 1758081876000,
    "archiveName": "RetacafeSMP-full-2026-09-17_04-00-00.zip",
    "archiveBytes": 2254857830, "rawBytes": 6871947673, "files": 41208,
    "sha256": "9f86d0...", "error": null,
    "skippedFiles": ["session.lock (locked)"],
    "storages": { "local": "ok", "s3": "ok" },
    "pruned": { "local": 1, "s3": 1 }
  }
}

event is backup.start or backup.finish. Use it with n8n, Zapier, Uptime Kuma (push monitor), Home Assistant or your own API.

Restoring

  1. Find the archive: /arkive list s3 full.
  2. Download it: /arkive restore s3 full RetacafeSMP-full-2026-09-17_04-00-00.zip --extract. The file lands in plugins/Arkive/restore/, --extract unpacks it next to it.
  3. Stop the server.
  4. Copy the folders you need (e.g. world/) from the restore folder over the live ones. Database dumps are in arkive-databases/ — import them with mysql < main.sql / psql -f main.sql.
  5. Start the server and delete the restore folder when you are done.
By design

Arkive never overwrites live worlds or plugin data on its own. A wrong click must not be able to roll back a running server — restoring always involves you stopping the server and copying files consciously.

Archives are plain zip/tar.gz: you can also just download them from your bucket/Drive and extract them anywhere.

BungeeCord & Velocity

The proxy jars use exactly the same config, commands, storages and retention. Differences:

Typical proxy setup: a small profile every 6 hours to the same S3 bucket under a different prefix (e.g. proxy), keep-last: 20.

Performance tuning

SettingEffect
general.thread-priority1–10. Lower = less CPU competition with the main thread. 3 is a good default; use 1 on single-core hosts.
backup.compression.levelRegion files compress poorly; level 1–3 is often 2× faster for a few % larger archives. 0 = store only.
general.upload-throttle-mbpsCaps upload bandwidth so players' latency is unaffected.
general.temp-directoryPut it on the fastest disk. If a local storage is a target, the archive is written there directly.
skip-if-no-playersSkips scheduled runs when nobody joined since the last backup — avoids identical archives overnight.
ExcludesExclude logs/**, cache/**, libraries/**, versions/**, dynmap tiles, and plugin caches. A 6 GB server usually archives in a few minutes.
ProfilesCombine a frequent small worlds profile with a nightly full profile instead of one huge hourly backup.

The only main-thread work is save-all before archiving and re-enabling auto-save afterwards; everything else (walking, compressing, hashing, uploading, pruning) happens on the Arkive worker thread.

config.yml reference

general

KeyDefaultDescription
server-nameserverUsed in archive names, Discord embeds and the manifest.
debugfalseVerbose logging: skipped files, upload progress, stack traces.
temp-directory""Staging folder; empty = plugins/Arkive/temp.
timezone""IANA zone for cron and timestamps, e.g. Asia/Jakarta.
date-formatyyyy-MM-dd_HH-mm-ssJava DateTimeFormatter pattern for {timestamp}.
thread-priority3Backup worker thread priority 1–10.
upload-throttle-mbps0Upload cap in megabits/s, 0 = unlimited.

backup

KeyDefaultDescription
compression.formatzipzip or tar.gz.
compression.level60–9.
skip-if-no-playerstrueSkip scheduled runs without player activity since the last backup.
prepare-servertruesave-all + pause auto-save while archiving (game servers).
verify-checksumtrueSHA-256 of every archive.
backup-on-shutdownfalseRun all enabled profiles on stop.
delete-temp-after-uploadtrueRemove the staging archive after uploads.
upload-retries2Retries per storage with increasing delay.
announce.start / finish / failuretrueIn-game messages to players with announce.permission.
announce.permissionarkive.notifyWho sees announcements.
hooks.before / after[]See hooks.
databases.*{}See database dumps.

profiles.<name>

See profiles and retention.

storages.<id>

type (local, s3, ftp, sftp, webdav, google-drive, dropbox, onedrive) and enabled are common to all; the rest is documented per storage. Type aliases: minio, b2, r2, wasabi → s3; ftps → ftp; nextcloud → webdav; gdrive → google-drive.

web-link

See linking accounts.

notifications

See Discord & webhooks.

Commands & permissions

CommandPermissionDescription
/arkive helparkive.useCommand list.
/arkive backup [profile] [--force]arkive.backupRun one profile, or every enabled profile in sequence. --force ignores the no-players rule.
/arkive statusarkive.statusRunning backup (phase, progress, elapsed), profiles with last/next run, storages and their state.
/arkive historyarkive.historyLast 10 results.
/arkive list <storage> [profile]arkive.listArchives on a storage with size and date.
/arkive test [storage]arkive.testConnectivity/credential test for one or all storages.
/arkive link <storage> [code | --manual | --web]arkive.linkAuthorise a cloud account. Web flow when web-link is enabled, otherwise device/paste code.
/arkive unlink <storage>arkive.unlinkDelete the stored token.
/arkive restore <storage> <profile> <archive> [--extract]arkive.restoreDownload (and unpack) into the restore folder.
/arkive prune [profile]arkive.pruneApply retention now.
/arkive reloadarkive.reloadReload config, messages, storages, schedules and the web-link server.

arkive.admin grants every command, arkive.notify receives announcements. Console always has full access. Aliases: /backup, /ark (Bukkit), /arkivebackup, /ark (proxies). Tab completion covers sub-commands, profiles, storages and flags.

Placeholders

With PlaceholderAPI installed on Bukkit/Paper, Arkive registers the arkive expansion automatically (no ecloud download needed). Use them in scoreboards, tab lists, holograms, MOTDs:

PlaceholderExample
%arkive_running%true / false
%arkive_phase%uploading s3 42% or idle
%arkive_progress%42 (empty when unknown)
%arkive_current_profile%full
%arkive_last_status%success, partial, failed, never
%arkive_last_profile%full
%arkive_last_time%2026-09-17 04:04:36
%arkive_last_ago%2h 13m
%arkive_last_size%2.1 GB
%arkive_last_duration%4m 36s
%arkive_last_files%41208
%arkive_last_archive%RetacafeSMP-full-2026-09-17_04-00-00.zip
%arkive_last_error%Error text of the last run, or empty
%arkive_next_profile%Profile that runs next
%arkive_next_time%2026-09-17 10:00:00
%arkive_next_in%5h 55m
%arkive_profile_<name>_enabled%true
%arkive_profile_<name>_last_status% (also last_time, last_ago, last_size, last_duration, last_files, last_archive)Per-profile values
%arkive_profile_<name>_next_time% / _next_in%Per-profile schedule
%arkive_storage_<id>_type%S3
%arkive_storage_<id>_status%ready / not linked
%arkive_storage_<id>_target%Bucket / path / account
%arkive_storages_count%, %arkive_profiles_count%Counts
%arkive_history_count%, %arkive_success_count%, %arkive_failed_count%From the last 50 results

Developers on any platform can call core.placeholders().resolve("last_status") directly.

messages.yml

Every message Arkive sends is in messages.yml. Colour codes use &, placeholders are written as {name} and listed next to each key. The prefix is prepended to most messages; help.lines is a multi-line block. Keys missing from an older file are added automatically on start, so updates never break your customisations.

prefix: "&8[&bArkive&8] &7"
backup:
  started: "&7Backup &f{profile}&7 started, you may notice a short lag spike..."
  finished: "&aBackup &f{profile}&a finished &8(&f{size}&8, &f{duration}&8)"

Troubleshooting

SymptomCause & fix
Unable to load credentials from any of the providers in the chainAn S3-type storage has an empty access-key. Check every entry with type: s3 (also the ones you didn't mean to change) and run /arkive reload. Startup logs name the offending storage.
Bucket 'x' is not accessible (403)Wrong keys, or the token has no permission on that bucket. For R2 create the token with Object Read & Write scoped to the bucket.
S3 upload fails with a signature / STREAMING-AWS4 errorSet chunked-encoding: false for that storage.
Port 8443 is already in useAnother process uses the web-link port. Pick a different allocation.
Google: redirect_uri_mismatch / invalid_requestThe callback URL must match exactly (scheme, host, port, path) and must be a domain, not an IP. Register it on a Web application client.
Browser: certificate warning on the callback pageExpected — the certificate is self-signed. Continue. Delete plugins/Arkive/web/keystore.p12 after changing public-host to regenerate it.
keytool not foundYour Java runtime is a minimal JRE. Install a full JDK/JRE, or place your own PKCS12 keystore (password arkive-web) at plugins/Arkive/web/keystore.p12.
Storage 'x' is not linkedRun /arkive link x. Tokens live in plugins/Arkive/tokens/.
Backup partial with "N skipped"Locked or vanished files (session.lock, open region files on Windows). Enable general.debug to see which; usually harmless.
Skipping backup: no player activityWorking as intended (skip-if-no-players). Use --force or disable the option.
SFTP: Auth failCheck username, key path and that the public key is in authorized_keys. With a passphrase-protected key set private-key-passphrase.
Dropbox: 409 path/not_found on listFolder does not exist yet — the first upload creates it.
Nothing happens on scheduleCheck /arkive status for next; profiles with mode: disabled or enabled: false never run. Cron errors are logged on start.

For anything else enable general.debug: true, reproduce, and post the log in the resource discussion or Discord.

FAQ

Does it lag the server?

No. One save-all on the main thread, then everything runs on a low-priority background thread with optional bandwidth throttling.

Is my data sent to Wureta?

Never. Arkive talks only to the storages you configure, using your own credentials and OAuth apps. There is no telemetry.

Can I backup to several places at once?

Yes — list several storage ids in a profile. Each storage gets its own retention pass and result.

Can I run it on a proxy and on the backend servers?

Yes, one licence covers all your servers. Use different server-name/prefix values so archives don't mix.

Can I use a different world container / multiple servers in one folder?

Use include with the exact folders you want, and separate profiles per server if they share a disk.

Where are updates?

Through the resource page where you bought it (SpigotMC / BuiltByBit). The version is printed on startup and in /arkive status.

Lite edition

Arkive Lite is the free build on SpigotMC, available for Bukkit / Spigot / Paper / Folia only. It uses the same engine, config, commands and docs with these limits:

FeatureLiteFull
PlatformsBukkit / Spigot / Paper / Folia+ BungeeCord / Waterfall, Velocity
Storageslocal, sftp, ftp+ s3 (AWS, R2, B2, MinIO, Wasabi…), google-drive, dropbox, onedrive, webdav
Profiles1 (the first one in the config)unlimited
Database dumps—MySQL / MariaDB / PostgreSQL / custom
One-click cloud linking (web-link)—✓
Cron, retention, safe archiving, Discord, restore, hooks, placeholders✓✓

Storages or profiles beyond the Lite limits are ignored with a warning in the console — nothing breaks. To upgrade, replace the jar with the full edition from BuiltByBit; your config.yml carries over unchanged.

Not an official Minecraft product. Not approved by or associated with Mojang or Microsoft.