Skip to main content
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.

​
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.
Or use parallax-cli start as syntactic sugar — it execs the sibling parallaxd with --daemon appended and the same global flags forwarded:
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:

​
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:
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:
You can override the location with --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

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 for the full sugar-command list. The most relevant for daemon lifecycle management is stop:
Under the hood parallax-cli stop invokes the admin_stop RPC method. You can also signal the process directly:
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:
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