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

# Managing Disk Storage

> A task-by-task guide for administrators: see what fills the disk, get warned before it is full, free space, delete old content by rule or by person, get something back, and check who deleted what.

## Overview

**Settings → Configuration → Storage** is where an administrator looks after the disk Genesis keeps its data on. It is one page with five tabs, plus a few pieces on other pages. This guide is organised by what you want to do. For every setting and limit, see the reference page, [Storage Management](https://docs.genesiscomputing.com/docs/deployments/Storage-Management.md).

> [!NOTE]
>
> Everything here needs the **Access config panel** permission, which the
> built-in `admin` role holds. Listing or deleting other people's chats also
> needs **See every user's chat threads**. People without the permission don't
> see the page.

### Where everything is

| What | Where |
| - | - |
| The Storage page | **Settings → Configuration → Storage** (`/config/storage/`) |
| How full the disk is, and by whom | Storage → **Overview** |
| Genesis's own leftover files | Storage → **System** |
| Rules that delete old chats, missions, apps and dataset versions; restoring what they deleted | Storage → **Retention** |
| Every stored item, with its owner | Storage → **Items** |
| Deleting what a person or role made | Storage → **Cleanup** |
| The low-disk alert | The bell icon, top right (admins only) |
| Deleted missions you can restore | **Work → Missions**, status filter **Deleted, recoverable** |
| Who deleted what | **Settings → Configuration → Admin Audit Log**, target type `storage` |
| Job intervals and on/off switches | **Settings → Configuration → Advanced Settings**, sections **Storage**, **System Cleanup**, **Retention** |
| Which jobs are scheduled | **Scheduler** page |

### Three questions decide everything

Every delete on the Storage page works the same way: choose a kind of content or a rule, **Review** exactly what would go, then confirm. You never pick a file by hand. Before deleting, three things decide what happens:

1. **Is it Genesis's own file or something a person made?** Genesis's own files (temporary files, old logs, environments) are cleaned on the **System** tab. Genesis makes temporary files and environments again when it needs them; removed old logs are gone for good. What people made is deleted on **Retention** or **Cleanup**.
2. **Can it come back?** A chat or mission can be restored, but only if a [state snapshot](https://docs.genesiscomputing.com/docs/deployments/State-Snapshots-And-Migration.md) holds it. Apps, repositories, datasets and document indexes are deleted for good, and the review makes you tick a box saying so.
3. **Is it protected?** Agent memory, wiki, Context Graph, skills and blueprints are never deleted by a rule or a cleanup. Neither is anything someone chose to keep.

## See what fills the disk

Open **Storage → Overview**.

![Storage Overview tab: a bar of used and free space coloured by content type, and a table of sizes by content type with Open buttons.](https://mintcdn.com/genesiscomputing/HOz9gKqA_10UFMXY/images/storage_overview_actual.png?fit=max\&auto=format\&n=HOz9gKqA_10UFMXY\&q=85\&s=7c253adc1d3e1b692a289c5d77c42af7)

* The bar shows used and free space. The coloured part is Genesis's files, by type. The grey part is everything else on the disk.
* **By content type** lists each type's size, file count and share. **Open** goes to the page that owns that content, for example Chat, Git or Apps.
* **By person** and **By role**, below it, show who made what. A person counts in each of their roles.
* Genesis measures every six hours. Press **Measure now** for a fresh reading; the footer says when the last one ran.

To see the actual items, open **Storage → Items**. Pick a type, then filter by owner or by who can see it. **Open** on a row goes to that item.

## Get warned before the disk fills up

1. On **Storage → Overview**, press **Warning level**.
2. Set the free space below which the disk counts as low, the percentage used at which it does, or both.
3. Save.

When the disk crosses the level, three things happen:

* The Storage page shows "The disk is past its warning level."
* Every administrator gets one bell notification, "Disk space is running low". It links to the Storage page.
* You get another notification only after the disk recovers and then crosses the level again.

## Free space now

Start with Genesis's own files. Temporary files, environments and copies are safe to remove: Genesis makes them again when it needs them. Old logs are removed for good, so keep them if you still need their history.

1. Open **Storage → System**. **Genesis's own files** lists each kind with its age limit and how much it would free now.
2. Press **Review** on a row. The dialog lists exactly what would be removed, with each item's size and age.
3. Press **Remove N items**.

![System tab with the review dialog for Context Graph copies of repositories, listing five items with size and age and a Remove 5 items button.](https://mintcdn.com/genesiscomputing/HOz9gKqA_10UFMXY/images/storage_system_review_actual.png?fit=max\&auto=format\&n=HOz9gKqA_10UFMXY\&q=85\&s=dc1b4bb4622360bbf224b51edf3e3dbd)

If that isn't enough, check the Overview for the biggest types and owners, then use [a retention rule](#remove-old-content-automatically) or [a cleanup](#remove-everything-a-person-or-group-made).

> [!TIP]
>
> A run removes exactly the list you reviewed. If the list changed since you
> opened it, the run is refused and the new list is shown.

## Remove old content automatically

Retention rules delete content nobody has used for longer than an age you set. There are rules for chats, missions, apps and dataset versions.

![Retention tab: the state snapshots card naming the newest snapshot and the snapshot location, and the retention rules table for chats, missions, apps and dataset versions with Review buttons.](https://mintcdn.com/genesiscomputing/HOz9gKqA_10UFMXY/images/storage_retention_actual.png?fit=max\&auto=format\&n=HOz9gKqA_10UFMXY\&q=85\&s=b7bd1476d800e0e8fa90f2a9addb03e2)

### Before you start: snapshots

Chats and missions are deleted only once a **state snapshot** holds them, so they can be restored. Without a snapshot location, the chat and mission rules delete nothing.

1. Press **Retention settings** and set **Snapshot location**, for example `s3://bucket/prefix/instance`, and its region.
2. Take snapshots regularly. See [State Snapshots and Migration](https://docs.genesiscomputing.com/docs/deployments/State-Snapshots-And-Migration.md).
3. The **State snapshots** card shows the newest snapshot, which the rules rely on. It also shows the oldest one still held, which is how far back you can restore.

Keep snapshots at least as long as your audit period. Once the snapshot that holds a deleted item is gone, that item can't come back.

### Set a rule

1. Press **Retention settings**.
2. For each rule, set the age, for example 365 days.
3. Turn on **Daily** for the rules that should run by themselves. A rule that is off still lets you review it and delete by hand.
4. Save.

### Review and delete now

1. Press **Review** on a rule. The dialog lists every item the rule would delete, with its owner, who can see it, its size and when it was last active.
2. Press **Keep** on any item that must stay. It moves to the **Kept** list and no rule deletes it.
3. Press **Delete N**.

![Review dialog for old chat threads: four threads with owner, who sees it, size, last active, a Keep button on each, and Delete 4 threads.](https://mintcdn.com/genesiscomputing/HOz9gKqA_10UFMXY/images/storage_retention_review_actual.png?fit=max\&auto=format\&n=HOz9gKqA_10UFMXY\&q=85\&s=1126527716d7d14bd6c6f67332fdaa4a)

> [!WARNING]
>
> **Apps are deleted for good.** A snapshot can't restore a single app, so the
> apps review asks you to tick **Delete these apps for good**. Turning on the
> apps rule's daily switch counts as that consent for scheduled runs.

Dataset versions work differently. Each dataset keeps its newest 30 versions by default, and older ones are pruned on the dataset cleanup's schedule and on each refresh. You change the number in **Retention settings**. There is no on/off switch for this rule.

## Get something back

Only a chat or mission deleted by a retention rule or a cleanup can be restored, and only while the snapshot that holds it is kept.

1. Open **Storage → Retention** and scroll to **Deleted, recoverable**. Each row names the snapshot that holds the item.
2. Press **Restore**. The item comes back with its files, its owner and who could see it.

For missions, the same list is also on **Work → Missions**: set the status filter to **Deleted, recoverable**.

A restore is refused, and nothing changes, if the item already exists again or its snapshot is no longer at the snapshot location.

A restore doesn't bring back everything:

* A restored chat comes back without its skill-use history, room subscriptions or mailbox.
* Apps, repositories, datasets and document indexes can't be restored at all.

## Keep something from being deleted

* **Keep one item:** press **Keep** on it in any retention review. To undo, go to **Retention → Kept** and press **Stop keeping**.
* **Keep a whole type:** add it to `retention.protected_types` in **Advanced Settings → Retention**. Agent memory, wiki, Context Graph, skills and blueprints are protected by default.
* **Always kept:** pinned chats, chats a mission is running in, unfinished missions and apps that ship with Genesis.

Owners can keep their own chats, missions and apps only through the API for now (`PUT /api/storage/holds/{type}/{id}`). There is no Keep button on the Chat, Missions or Apps pages yet.

## Remove everything a person or group made

Use this after a training week, a pilot, or when someone leaves.

1. Open **Storage → Cleanup**.
2. Pick **People**, **Roles**, or both. Pick the **Types** to remove and the **Made between** dates. Both days are included, and the dates are in UTC.
3. Press **Review what would be removed**.

![Cleanup tab: People, Roles and Types pickers, a Made between date range, the Review what would be removed button, and a Cleanups list with one finished run.](https://mintcdn.com/genesiscomputing/HOz9gKqA_10UFMXY/images/storage_cleanup_actual.png?fit=max\&auto=format\&n=HOz9gKqA_10UFMXY\&q=85\&s=5da78e829b018c8844892626376bf7b8)

The review sorts every item into three groups:

| Group | What happens |
| - | - |
| **Restorable after deleting** | Chats and missions a snapshot holds. They are deleted and can be restored from Retention. |
| **No snapshot holds these** | Everything else selected. It is deleted for good, and only if you tick **Also delete these for good**. |
| **Kept** | Protected and kept items, items in use, chat uploads, skills and blueprints. They are not touched. |

4. Type `delete` in the box and press **Delete N items**.

![Review the cleanup dialog: one restorable chat thread with owner, who sees it and size, and a Type delete to confirm box.](https://mintcdn.com/genesiscomputing/HOz9gKqA_10UFMXY/images/storage_cleanup_review_actual.png?fit=max\&auto=format\&n=HOz9gKqA_10UFMXY\&q=85\&s=29e68b5391cf21ff97f75f54d34cb6bf)

The cleanup runs in the background. **Cleanups**, below the form, shows each run's status, how many items are done and the space freed. If the server restarts mid-run, the run shows as interrupted. **Run again** finishes the items it had left; it never makes a new selection.

> [!NOTE]
>
> A cleanup matches items on their owner only, and only items with a known
> creation date. Content the system owns is never selected.

## Check who deleted what

Open **Settings → Configuration → Admin Audit Log** and set **Target type** to `storage`. Every measurement, settings change, removal, deletion, keep and restore is listed there. Each row has the person, or `system` for a scheduled run, the item's type and owner, and the space freed. Titles and file paths are never recorded.

## What runs by itself, and where to change it

| Job | Runs | First run after a start | Change it in |
| - | - | - | - |
| Measuring the disk | Every 6 hours | 5 minutes | Advanced Settings → **Storage** |
| Genesis's own files (System tab) | Daily | 15 minutes | Kinds and ages: **Cleanup settings** on the System tab. Interval: Advanced Settings → **System Cleanup** |
| Retention rules | Daily, for rules with **Daily** on | 15 minutes | **Retention settings** on the Retention tab. Interval: Advanced Settings → **Retention** |
| Dataset versions | Every 6 hours, and on each refresh | — | **Retention settings** |

On/off switches take effect at the next run. An interval change takes effect after the next restart.

The System tab also lists **Other cleanup jobs**, which existed before the Storage page and have their own settings:

* orphaned uploads
* expired datasets
* old notifications
* old cost records
* app runtime folders
* the agent folder check
* the thread archive

> [!WARNING]
>
> **Thread archive** (`archive.threads.enabled`, off by default) is an older,
> separate way to remove idle chats: it writes them to its own S3 archive.
> Don't turn it on where the chat retention rule is on, or two jobs will remove
> the same chats in different ways. Prefer the retention rule: it has a
> review, Keep, protected types, restore and an audit trail.

## Troubleshooting

| You see | Why, and what to do |
| - | - |
| The chat or mission rule deletes nothing | No snapshot location is set, or no snapshot holds the items yet. Set it in **Retention settings** and take a snapshot. Items changed since the newest snapshot are listed under **Waiting for the next snapshot**. |
| A rule says why it deletes nothing | Chat and mission rules work only where the metadata database is genesis.db and chats are stored as files. The message names what is missing. |
| A just-finished chat isn't deleted | Its last message must be at least 14 hours older than the newest snapshot. It's picked up after a later snapshot. |
| "Restore" is refused | The item exists again, or its snapshot was removed from the snapshot location. |
| The Overview says the measurement is partial | It ran out of its time budget, 120 seconds by default. Raise `storage.usage_scan.budget_seconds` in Advanced Settings. |
| A cleanup by date range skips some items | Items with no creation date are never selected by a date range. |
| A change in Advanced Settings didn't take effect | Interval settings are read when the server starts. Restart it. |
| **Next run** is blank on the System tab | The job is turned off, or it runs on a scheduler the page doesn't read. |