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

# Daemon mode

The Parallax node can run in the foreground as an interactive process or detach into the background as a long-running daemon, in the same spirit as Bitcoin Core's `bitcoind -daemon` flag. The daemon lives in the `parallaxd` binary; `parallax-cli` is the companion client that talks to it over JSON-RPC.

## Foreground mode (default)

Running `parallaxd` with no special flags starts the node attached to the terminal. Logs stream to stderr, `Ctrl-C` (SIGINT) or SIGTERM triggers a graceful shutdown. This is the mode you want during development or when running under a supervisor like systemd that expects the process to stay in the foreground.

```sh theme={null}
parallaxd --datadir ~/.parallax
```

## Background mode (`--daemon`)

Passing `--daemon` detaches the process from the controlling terminal, redirects stdout and stderr to a log file inside the data directory, writes a PID file, and exits the parent process with status 0. The node continues running in its own session.

```sh theme={null}
parallaxd --datadir ~/.parallax --daemon
```

Or use `parallax-cli start` as syntactic sugar — it execs the sibling `parallaxd` with `--daemon` appended and the same global flags forwarded:

```sh theme={null}
parallax-cli --datadir ~/.parallax start                    # same as parallaxd --daemon
parallax-cli --datadir ~/.parallax start /etc/parallax.toml # + --config <path>
```

`parallax-cli start` looks for `parallaxd` next to the `parallax-cli` binary first, then falls back to `$PATH`. If you install the binaries under `/usr/local/bin/` (the default for the Dockerfile and release tarballs) both locations resolve correctly.

On success the parent prints a single line before exiting:

```
parallax daemon started (pid 12345, logs: /home/user/.parallax/parallax.log)
```

### What `--daemon` does under the hood

* Re-executes the `parallaxd` binary with the same arguments and a sentinel environment variable (`PARALLAX_DAEMONIZED=1`) so the child knows not to daemonize again.
* On Unix, places the child in its own session via `setsid(2)`, decoupling it from the controlling terminal's signal delivery. On Windows, the child is spawned with `DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP`.
* Redirects the child's stdout and stderr to `<datadir>/parallax.log` (append mode).
* Closes stdin by binding it to `/dev/null`.
* The child writes its own PID to the PID file after the node has finished starting up, and removes it on clean shutdown.

### Log file

Stdout and stderr are redirected to:

```
<datadir>/parallax.log
```

The file is opened in append mode, so successive daemon runs accumulate history. Rotate it externally (e.g. with `logrotate`) for long-running installations.

### PID file

By default the PID file is:

```
<datadir>/parallax.pid
```

You can override the location with `--pid`:

```sh theme={null}
parallaxd --daemon --pid /var/run/parallax.pid
```

The PID file is removed automatically when the node shuts down cleanly. If the node crashes the file may be left behind; on the next `--daemon` start parallaxd checks whether the recorded PID is still alive (via `signal 0` on Unix) and either refuses to start if a live daemon is present or silently overwrites the stale file.

### Refusing to start when a daemon is already running

```sh theme={null}
$ parallaxd --datadir ~/.parallax --daemon
parallax daemon already running (pid 12345, pidfile /home/user/.parallax/parallax.pid)
```

This check only protects against accidental double-start within the same data directory. For multi-tenant setups pin distinct data directories or PID file paths per instance.

## Managing a running daemon

`parallax-cli` talks to a running daemon over the IPC socket at `<datadir>/parallax.ipc` — see [Command-line RPC](../interacting-with-parallax/command-line-rpc) for the full sugar-command list. The most relevant for daemon lifecycle management is `stop`:

```sh theme={null}
parallax-cli --datadir ~/.parallax stop
# → Parallax server stopping
```

Under the hood `parallax-cli stop` invokes the [`admin_stop`](../interacting-with-parallax/json-rpc-namespaces/admin#admin_stop) RPC method. You can also signal the process directly:

```sh theme={null}
kill -TERM "$(cat ~/.parallax/parallax.pid)"
```

Both paths trigger the same graceful shutdown sequence: stop protocols, flush the transaction pool, persist the trie cache, close databases, remove the IPC socket and PID file.

## systemd example

Daemon mode composes with systemd if you use `Type=forking` so the unit treats the parent exit as readiness:

```ini theme={null}
[Unit]
Description=Parallax node
After=network-online.target
Wants=network-online.target

[Service]
Type=forking
PIDFile=/var/run/parallax.pid
ExecStart=/usr/local/bin/parallaxd --datadir /var/lib/parallax --daemon --pid /var/run/parallax.pid
ExecStop=/usr/local/bin/parallax-cli --datadir /var/lib/parallax stop
Restart=on-failure
User=parallax

[Install]
WantedBy=multi-user.target
```

For most modern setups, prefer `Type=simple` without `--daemon` — systemd already handles log capture (via the journal), PID tracking, and graceful shutdown. Use `--daemon` when integrating with init systems that expect a forking service, or for manual long-running setups without a supervisor.

## Flag reference

| Flag       | Description                                                                                |
| ---------- | ------------------------------------------------------------------------------------------ |
| `--daemon` | Detach and run the node as a background daemon. Logs redirect to `<datadir>/parallax.log`. |
| `--pid`    | PID file path when running with `--daemon`. Defaults to `<datadir>/parallax.pid`.          |