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

# Advanced Azul configuration and push workflows

> Store daemon settings inside your place file, enable Rojo compatibility, manage Wally packages, and automate push mappings for repeatable workflows.

Once you've got the basic sync loop working, Azul gives you several ways to codify project behavior so your whole team stays consistent and common push operations require no manual flags. This page covers the features that matter most in larger or more structured projects.

## Per-place daemon configuration

You can store daemon overrides inside your Roblox place as a `ModuleScript`, so every collaborator gets project-specific behavior automatically when they connect — no CLI flags or local config files required.

<Steps>
  <Step title="Create the config script in Studio">
    In Roblox Studio, navigate to `ServerStorage`, create a folder named `Azul`, and inside it create a `ModuleScript` named `Config`.

    The full path should be: `ServerStorage > Azul > Config`
  </Step>

  <Step title="Return a configuration table">
    The script must return a plain Lua table. The daemon reads this table when the plugin connects.

    ```lua theme={null}
    -- ServerStorage/Azul/Config
    -- Returned table is sent to the Azul daemon when it connects.
    return {
        -- TCP port the daemon should be listening on (defaults to 8080).
        port = 8080,

        -- Emit extra debug logs from the Studio plugin/daemon handshake.
        debugMode = false,

        -- When the daemon connects, delete files in the sync directory that are
        -- not mapped to any instances. Keeps the local mirror clean between sessions.
        deleteOrphansOnConnect = true,

        -- One or more push mappings.
        pushMappings = {
            -- Mapping 1: map "Packages" to ReplicatedStorage.Packages
            {
                source = "Packages",
                destination = { "ReplicatedStorage", "Packages" },
                destructive = true,
                rojoMode = true,
            },
            -- Mapping 2: map "src/Server" to ServerScriptService.Server
            {
                source = "src/Server",
                destination = { "ServerScriptService", "Server" },
                destructive = false,
            },
        },
    }
    ```
  </Step>

  <Step title="Save and commit the place file">
    Save the place. Teammates who open it will automatically receive these settings the next time they connect.
  </Step>
</Steps>

### Config options reference

| Option                   | Type      | Description                                                                                                                                                                            |
| ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `port`                   | `number`  | The TCP port the daemon listens on. Defaults to `8080`.                                                                                                                                |
| `debugMode`              | `boolean` | When `true`, the daemon emits extra logs during the plugin/daemon handshake. Useful for diagnosing connection issues.                                                                  |
| `deleteOrphansOnConnect` | `boolean` | When `true`, the daemon deletes files in the sync directory that don't map to any instance on connect. Keeps the local mirror clean between sessions.                                  |
| `rojoMode`               | `boolean` | When `true`, enables Rojo compatibility mode for push operations.                                                                                                                      |
| `pushMappings`           | table     | Pre-specifies local-to-Studio push paths so `azul push` runs without manual `-s`/`-d` flags. Each entry requires `source`, `destination`, and optionally `destructive` and `rojoMode`. |

<Note>
  Only the options you specify are overridden. Any option you omit falls back to the CLI-level default or the daemon's built-in default.
</Note>

## Rojo compatibility mode

Azul works without a project file by default, but if you're importing from an existing Rojo-based folder structure, you can enable Rojo compatibility with the `--rojo` flag.

Use `--rojo` with `azul build` to perform a full push using the Rojo project file:

```bash theme={null}
azul build --rojo --rojo-project default.project.json
```

Use `--rojo` with `azul push` for a targeted push of a specific folder:

```bash theme={null}
azul push --rojo -s Packages -d ReplicatedStorage.Packages
```

In Rojo mode, Azul reads `default.project.json` (or the path you provide with `--rojo-project`) to interpret the folder structure before pushing instances into Studio.

<Tip>
  You don't need `--rojo` for normal sync sessions. Use it only when the folder you're pushing was created by or for a Rojo-based workflow — such as a Wally `Packages` directory.
</Tip>

## Package management with Wally

[Wally](https://wally.run/) produces a `Packages` folder with a Rojo-style layout. Use `azul push` to import those packages directly into `ReplicatedStorage.Packages` in Studio:

```bash theme={null}
azul push -s Packages -d ReplicatedStorage.Packages --destructive --rojo
```

* `-s Packages` — the local `Packages` folder produced by Wally
* `-d ReplicatedStorage.Packages` — the destination in Studio
* `--destructive` — removes stale packages in the destination that are no longer present locally
* `--rojo` — required because Wally uses Rojo-style folder conventions

<Warning>
  The `--destructive` flag deletes any instances in the destination that don't have a matching local file. Make sure the destination path is correct before running it for the first time.
</Warning>

## Automating package pushes

If you run the Wally push command regularly, add it as a `pushMappings` entry in your per-place config. This lets you run plain `azul push` without repeating the flags each time.

<Steps>
  <Step title="Open your per-place config">
    Open `ServerStorage > Azul > Config` in Studio.
  </Step>

  <Step title="Add a pushMappings entry">
    Add an entry to the `pushMappings` table that matches your `azul push` command:

    ```lua theme={null}
    pushMappings = {
        {
            source = "Packages",
            destination = { "ReplicatedStorage", "Packages" },
            destructive = true,
            rojoMode = true,
        },
    }
    ```
  </Step>

  <Step title="Run azul push without flags">
    After saving and reconnecting, run:

    ```bash theme={null}
    azul push
    ```

    Azul reads the `pushMappings` from the per-place config and executes all defined mappings automatically.
  </Step>
</Steps>

<Tip>
  You can define multiple entries in `pushMappings` to handle several folders in one command — for example, both a `Packages` folder and a `src/Server` folder.
</Tip>