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

# Automations

> Teach your workspace how to run itself.

Automations are how your workspace learns to operate itself. They turn repeated
setup, run, verify, cleanup, and review steps into actions that humans and
agents can both use.

They can be scripts, like copying env files or starting Docker. They can also
launch agents, like a session that reviews recent Neroli runs and suggests
better automations. Claude, Codex, OpenCode, and other agents can create or
update automations from inside Neroli.

Agents launched inside Neroli know about the current session, visible panes,
attached browser, simulator, known services, and available automations, so they
can use the same workspace controls you do.

<Frame caption="Automations can be toolbar buttons, lifecycle hooks, scheduled agent sessions, or cleanup scripts with stop behavior.">
  <div className="not-prose rounded-xl border border-dashed border-gray-300 bg-gray-50 p-8 text-center text-sm text-gray-600 dark:border-gray-700 dark:bg-gray-900 dark:text-gray-300">
    Placeholder image: a Neroli Automations view showing Prepare session, Run dev, Build, Verify, Improve my automations, and Docs from shipped work.
  </div>
</Frame>

## Two kinds of automations

| Type               | What it does                                          | Example                                                                         |
| ------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------- |
| Script automation  | Runs deterministic shell work in the current session. | Copy `.env.local`, assign ports, start Docker, run Build, stop services.        |
| Agentic automation | Starts an isolated agent session with a job.          | Review recent sessions, improve automations, update docs from shipped features. |

Both are workspace-native. They can show up in the top bar, command palette,
sidebar, or session menu. They can also run on a schedule or when a session is
created, moved, archived, or removed.

Sidebar automations can live on workflow groups like Planning, In Review, Merge,
or Done. When you run one from a group header, it receives that group and the
sessions inside it. When you drag a session between groups, **Session moved**
automations can run for the destination group.

## Automations worth creating

| Automation             | Why it is useful                                                                                      |
| ---------------------- | ----------------------------------------------------------------------------------------------------- |
| Prepare session        | Copies env files, installs deps, assigns unique ports, and creates isolated Docker or database state. |
| Run dev                | Starts the dev server or stack from the current session, often as a pinned toolbar button.            |
| Stop / teardown        | Stops the dev server, shuts down Docker, frees ports, and removes generated state.                    |
| Build / Verify         | Gives humans and agents the same one-click checks before work lands.                                  |
| Improve my automations | Agentic automation that inspects recent sessions and proposes easier setup/run/verify flows.          |
| Docs from shipped work | Agentic automation that drafts docs updates from new features and merged sessions.                    |
| Review before merge    | Agentic automation that checks diffs, migrations, env changes, tests, docs gaps, and risky files.     |
| Browser verification   | Opens the app, drives the attached browser, and captures evidence for the review.                     |
| Verify Merge           | Runs checks or starts review agents for sessions waiting in Merge.                                    |
| Cleanup Done           | Archives or summarizes completed sessions after validation.                                           |

## The isolated dev environment pattern

The most useful automation is often **Prepare session**.

<Steps>
  <Step title="Copy local config">
    Copy `.env.local`, certificates, or generated files into the session without committing secrets.
  </Step>

  <Step title="Assign unique ports">
    Give each session its own backend, database, or frontend ports so parallel runs do not collide.
  </Step>

  <Step title="Provision services">
    Start or prepare an isolated Docker database, queue, cache, or local stack for that session.
  </Step>

  <Step title="Expose buttons">
    Pin Run, Build, and Verify to the toolbar so humans and agents use the same workflow.
  </Step>

  <Step title="Add stop behavior">
    Give services a Stop script so Neroli can tear them down cleanly when the run ends.
  </Step>
</Steps>

## Let agents improve the workspace

Because Neroli sessions can inspect their own workspace and recent runs, you can
ask an agent to set this up for you:

```txt theme={null}
Create Neroli automations for this repo:
- Prepare session: copy env, assign unique ports, install deps, prepare Docker
- Run dev: start the app from the current session
- Stop: tear down services cleanly
- Verify: run the checks we should use before review
```

It can inspect package scripts, Docker config, previous commands, and failed
sessions, then create automations that make the next session smoother.

## Make automations visible

Good automations should be easy to launch from where the work happens:

* pin Run, Build, and Verify in the session toolbar
* place group actions on the sidebar groups where they are useful
* keep Stop paired with anything that starts a server or service
* use lifecycle setup when every new session needs the same preparation
* use Session moved automations when entering In Review, Merge, or Done should trigger follow-up work
* use scheduled or agentic automations for ongoing maintenance, docs, and improvements
* keep personal machine-specific actions local, and share repo-wide actions with the team

<Tip>
  Shared automations can live with the repo. Personal automations can stay local to your machine.
</Tip>

Next: use [Recipes and gotchas](/docs/recipes) to turn automations into isolated dev sessions, cloud handoff, group actions, and review workflows.