---
sidebar_position: 6
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lium.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Backups

Lium runs a scheduled backup job for any pod you configure: it ZIPs a directory inside the pod, uploads the archive to AWS S3 in a bucket scoped to your account, and prunes archives older than the retention window. Use it to protect training checkpoints, model weights, and any work-in-progress that would be expensive to redo if the pod went away.

## How it works

1. You pick a **Backup Path** inside the pod and a **Frequency** + **Retention**.
2. The platform installs a cron job on the pod.
3. On every tick, the job ZIPs the directory and uploads the archive to S3.
4. Archives older than the retention window are auto-deleted.
5. Backup status (started / completed / failed / deleted / expired) shows up on the pod's **Backups** tab and on the global **Backups** page.

## Backup path: the rule that matters

**The backup path must be a subfolder of the pod's local volume mount.** The local mount is `/root` for every standard template — that's also your SSH home directory and where templates land your code.

The Backup Configuration modal calls this out at the top: *"Volume Path: `/root`. The backup path should be a subfolder of the volume path to ensure data persistence."*

### ✅ Valid backup paths

```
/root                       # entire local volume
/root/models                # one subdirectory
/root/checkpoints           # another subdirectory
/root/project/data          # nested subdirectory
```

### ❌ Invalid backup paths

```
/home/user/documents        # not under the local volume mount
/tmp/backup                 # tmpfs, not persistent — erased on pod restart
/var/log                    # system directory outside the local volume
/mnt                        # external Volume mount — outside the local volume
/mnt/datasets               # same — external Volumes are NOT in the backup scope
..                          # path traversal, rejected by the API
```

:::info The /mnt distinction
**External [Volumes](./volumes)** mounted at `/mnt` are *not* backed up by this system — they have their own durability via S3 already, and including them would double-bill your storage. Backup is for the **local** pod volume at `/root`.
:::

If a template uses a non-default volume mount (rare — some custom templates change `Volume` in the template definition), the rule becomes "subfolder of *that* path." The modal's banner reflects whatever the pod's mount actually is.

## Configure a backup in the UI

From the pod detail page:

1. Click **Backup** in the top-right action bar.
2. The **Backup Configuration** modal opens.
3. **Backup Path** — defaults to `/root`. Narrow it (e.g. `/root/checkpoints`) if the rest of `/root` is large and you don't need it backed up.
4. **Backup Frequency** (hours, 1–168).
5. **Retention** (days, 1–365).
6. **Save**.

![Backup Configuration modal on the pod detail page](./assets/backups-config-modal.png)

Tweak it later by clicking **Backup** again — the modal pre-fills with the existing config.

## See your backups

- **Per pod** — pod detail page → **Backups** tab. Shows recent runs and a **Restore From Backup** section listing restore jobs.
- **Globally** — sidebar → **Backups**. Filter by Type (Manual / Automatic), Status (Completed / Failed / Deleted / Expired), Pod ID, or search by name. Use **Delete All COMPLETED** to clean up.

![Global Backups page with filters and history](./assets/backups-list.png)

## Frequency cheatsheet

| You're doing | `backup_frequency_hours` |
|---|---|
| Active training run, costly to lose | `6` |
| Regular daily workload | `12`–`24` |
| Stable / inference-only project | `24`–`72` |
| Long-term archival | `168` (weekly) |

Pair with **Retention**: longer retention = bigger S3 bill. 7–30 days is typical for active work.

## What gets stored where

The archive is `<backup-path>.zip`, uploaded to a per-account S3 prefix the platform manages. You don't get raw S3 credentials — pull archives back through the [Restores](./restores) flow or via the API.

## Billing

Backups are billed transparently with no markup:

- **Storage** — by the actual compressed archive size, charged hourly.
- **Transfer** — pay AWS rates for the upload.
- **Retention runs** — free.
- **Pod stopped or deleted** — your archives stay live in S3 for the full retention window. Storage cost continues.

To stop charges entirely: delete the backup configuration **and** delete the existing archives (use **Delete All COMPLETED** on the Backups page, or delete by ID via the API).

## Triggering a manual backup

From the pod detail page **Backups** tab, the next scheduled run is governed by the cron job. To kick off a one-off backup right now, use the API call below — set `is_manual: true`. (A "Run now" button is on the roadmap.)

## Update or delete a configuration

In the dashboard, click **Backup** on the pod detail page and change the fields, or delete the configuration entirely from there.

<details>
<summary>For agents and automation: API + CLI</summary>

```bash
# Create a backup configuration
curl -X POST https://lium.io/api/backup-configs \
  -H "X-API-Key: $LIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pod_id": "<your-pod-uuid>",
    "backup_path": "/root/checkpoints",
    "backup_frequency_hours": 6,
    "retention_days": 30
  }'

# List configurations
curl https://lium.io/api/backup-configs \
  -H "X-API-Key: $LIUM_API_KEY"

# Get the config for one pod
curl https://lium.io/api/backup-configs/pod/<pod_id> \
  -H "X-API-Key: $LIUM_API_KEY"

# Update
curl -X PUT https://lium.io/api/backup-configs/<config_id> \
  -H "X-API-Key: $LIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"backup_frequency_hours": 12, "retention_days": 90, "backup_path": "/root"}'

# Delete (archives in S3 are kept for the retention window)
curl -X DELETE https://lium.io/api/backup-configs/<config_id> \
  -H "X-API-Key: $LIUM_API_KEY"
```

### Configuration schema

| Field | Type | Range | Notes |
|---|---|---|---|
| `pod_id` | UUID | — | Pod whose volume gets archived |
| `backup_path` | string | ≤ 500 chars | Must be under the pod's local volume mount (default `/root`); `..` rejected |
| `backup_frequency_hours` | int | 1–168 | 168 = weekly |
| `retention_days` | int | 1–365 | Older archives auto-deleted |

CLI shortcuts: `lium bk now / set / show / restore / rm / logs` ([reference](/developers/cli/reference/bk)). Get an [API key](./api-keys) first.
</details>