# daemon

## `atuin daemon`

The Atuin daemon is a background daemon designed to

1. Speed up database writes
2. Allow machines to sync when not in use, so they're ready to go right away
3. Provide a hot in-memory fuzzy searcher
4. Store [captured command output](/guide/output-capture/)
5. Perform background maintenance

It may also work around issues with ZFS/SQLite performance.

## To enable

```shell
atuin setup --only --daemon
```

Setup sets `enabled = true` and `autostart = true` in the `[daemon]` section of
your config, and sets the search mode to
[`daemon-fuzzy`](/reference/config/general/#search_mode).
`atuin setup --only --no-daemon` turns the daemon off and stops it. On macOS,
setup also removes the launchd agent that autostart installed.

To enable the daemon by hand, add the following to the bottom of your Atuin
config file:

```toml
[daemon]
enabled = true
autostart = true
```

With `autostart = true`, the CLI will automatically start and manage a local daemon for history hook calls.
If you use systemd socket activation, keep `autostart = false`.
If a legacy experimental daemon is already running, autostart can't upgrade it in-place. Restart the daemon manually once.

If you prefer running the daemon yourself (for example via systemd/tmux), keep `autostart = false` and run `atuin daemon`.

## Autostart on macOS

When you're logged in graphically, autostart runs the daemon as a launchd
agent at `~/Library/LaunchAgents/sh.atuin.daemon.plist`. macOS tells you that
it added a background item the first time. With `ATUIN_HOME` or
`ATUIN_CONFIG_DIR` set, Atuin starts the daemon itself instead.

The agent is listed as `atuin` in System Settings, under General > Login Items.
Switched off there, Atuin leaves it off and works without the daemon until you
switch it back on. If the agent won't start, `daemon.stderr.log` in Atuin's
logs directory says why.

The agent gets the environment variables that your config's paths use, such as
`HISTDIR` for `db_path = "$HISTDIR/history.db"`. It also gets the ones that say
where your coding agents keep their sessions, such as `CODEX_HOME` or
`HERMES_HOME`. It keeps the values they had when Atuin installed it, so run
`atuin daemon restart` after you add or change one.

`atuin daemon stop` stops the agent, but with `autostart` on, the next command
that needs the daemon starts it again. `atuin setup --only --no-daemon` turns
the daemon off and removes the agent.

## Configuration

The daemon's settings are in the [`[daemon]` table](/reference/config/daemon/).