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

# Garages & Multi-Server Storage

The Garage system provides persistent virtual vehicle storage, supporting standalone servers and cross-server proxy networks.

## Virtual Garage Mechanics

* Players open their garage using `/freecart garage`.
* Carts can be picked up, stored, retrieved, and inspected through the interactive GUI.
* Players unlock up to 18 garage slots based on permissions (`freecarts.garage.slots.<number>`).
* **Auto-Garage**: Automatically parks a vehicle into the owner's garage if the owner disconnects or leaves the cart unattended. Includes a grace window (`keep-window-seconds`) allowing passengers to keep the cart in the world.
* **Garage Finder**: Social menu allowing players to browse other players' public garages (`finder.enabled: true`).

## Storage Backends

Configured under `freecarts.database` in `config.yml`:

### Local YAML Storage

* Stores vehicle records in `plugins/FreeCarts/garage/playerdata/<UUID>.yml`.
* Recommended for single servers with moderate player counts.
* No external database setup required.

### SQL Database (MySQL & MariaDB)

* Required for multi-server proxy networks (BungeeCord, Velocity).
* Centralizes garage vehicles, depot networks, and paint ownership across all connected servers.
* Uses HikariCP connection pooling for asynchronous database operations.

```yaml
freecarts:
  database:
    enabled: true
    storage-type: sql
    host: localhost
    port: 3306
    database: freecarts
    username: root
    password: "your_password"
    table-prefix: "fc_"
```

## Cross-Server Inventory Synchronization

FreeCarts prevents item duplication across proxy networks:

* **Optimistic Locking**: Verifies database revision timestamps and persistent NBT tags before loading a cart.
* **Per-Server Isolation (Optional)**: Enable `multi-server.enabled: true` with a unique `server-name` if cart cargo inventories should remain restricted to specific sub-servers.

## Data Migration Commands

Administrators can switch storage engines at any time without data loss:

* `/freecart import`: Migrates all existing YAML garage and depot records into the connected SQL database.
* `/freecart export`: Exports all database records into flat YAML files.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://mavenverse.gitbook.io/mavenverse-docs/freecarts/garage-and-storage.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.