> For the complete documentation index, see [llms.txt](https://machina-1.gitbook.io/machina-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://machina-1.gitbook.io/machina-docs/llamas/storage-runs.md).

# Storage runs

A storage run is the heart of Caravans: when your packs fill up out in the world, send half the caravan back to deposit cargo while you keep exploring. They leave on foot, slip out of sight, bank the goods in the depots you've recorded, and wander back empty a little later.

It's all driven by the **Khipu** — the knotted-cord ledger.

## Khipu gestures

| Gesture                                | What it does                                               |
| -------------------------------------- | ---------------------------------------------------------- |
| **Right-click a barrel or chest**      | Record it as a depot                                       |
| **Sneak + right-click that container** | Forget that depot                                          |
| **Right-click the air**                | Read the ledger (following / guarding / depots / runs out) |
| **Sneak + right-click the air**        | Send a storage run (crouch-whistle again to confirm)       |

## How a run works

1. **Record at least one depot** — tap the containers you want cargo dropped into. They fill in the order you recorded them.
2. **Dispatch** — sneak-whistle with the Khipu. Half of your caravan splits off, carrying half the cargo. Your **following llamas count even if you've walked ahead** — a momentary gap won't refuse the run. (Only **llamas** are sent on a run — donkeys and mules just keep marching with you.)
3. **They leave on foot.** A courier only vanishes once it's genuinely out of your sight — outside your view cone, hidden by terrain, or after a stuck-timeout — so it never pops away in front of you. It carries its **whole** load — every saddlebag page, not just the page on screen.
4. **They deposit** the cargo into your depots (loading the chunk if needed — items are never lost), then **reappear behind you and walk back in**, rejoining the caravan empty.

While a run is out, a **boss bar** tracks it — counting down while the packs are away, flipping to *returning* on the way home, and clearing when the last courier is back. Quiet particle puffs mark each llama leaving and returning.

{% hint style="success" %}
Every transfer is a real item move — cargo is **never duplicated or voided**. If a depot is full, the leftovers simply ride back with the llama.
{% endhint %}

## Automatic runs

You don't have to babysit the dispatch. Once a **following** caravan crosses a fullness threshold (default **80%** of its storage slots), it **sends a run on its own** — same path, same item-safety. It checks fullness on a light interval (no per-tick cost), waits out a cooldown between auto-runs, and **backs off longer if your depots came back full**, so it never flings couriers at chests with no room. Turn it off or retune it under `storage-run.auto` in [Configuration](/machina-docs/llamas/configuration.md).

## How long it takes

The return time **scales with how far your nearest depot is** — a depot right next to you comes back in about **10 seconds**, a far-flung one ramps up to a **90-second** cap, and anywhere in between is proportional. The boss bar counts down the time it actually picked. So a depot near your base keeps the loop snappy when you're close, without making long-range runs instant.

Leading the caravan with a seasoned [**lead camel**](/machina-docs/llamas/the-lead-camel.md) trims that wait further — its quartermaster tier shaves up to 40% off the return time.

## Tuning

The return-time range and distances, how far a llama must walk before it's allowed to slip away, and the view/occlusion rules are all in [Configuration](/machina-docs/llamas/configuration.md) under `storage-run` and `out-of-view`.

***

*Caravans is built by* [***Machina***](https://wearemachina.com) *— custom Minecraft plugins and more at* [*wearemachina.com*](https://wearemachina.com)*.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://machina-1.gitbook.io/machina-docs/llamas/storage-runs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.