immortal/immortal

---

immortal/immortal.json

{
  "createdAt": "2016-06-30T17:02:27Z",
  "defaultBranch": "master",
  "description": "⭕  A *nix cross-platform (OS agnostic) supervisor",
  "fullName": "immortal/immortal",
  "homepage": "https://immortal.run",
  "language": "Go",
  "name": "immortal",
  "pushedAt": "2024-07-21T19:15:39Z",
  "stargazersCount": 827,
  "topics": [
    "daemon",
    "http",
    "nix-cross-platform",
    "os-agnostic",
    "process",
    "supervisor",
    "unix",
    "unix-socket"
  ],
  "updatedAt": "2025-11-18T07:37:07Z",
  "url": "https://github.com/immortal/immortal"
}

⭕ immortal

A *nix cross-platform (OS agnostic) supervisor

https://immortal.run/

Linux precompiled binaries

run on behalf other system user

If services need to run on behalf other system user www, nobody, www-data, not root, immortal should be compiled from source for the desired target/architecture, otherwise, this error may be returned:

Error looking up user: "www". user: Lookup requires cgo

See more: https://golang.org/cmd/cgo/

If using FreeBSD or macOS you can install using pkg/ports or homebrew, for other platforms work is in progress, any help for making the port/package for other systems would be appreciated.

Compile from source

Setup go environment https://golang.org/doc/install

go >= 1.12 is required

For example using $HOME/go for your workspace

$ export GOPATH=$HOME/go

Create the directory:

$ mkdir -p $HOME/go/src/github.com/immortal

Clone project into that directory:

$ git clone git@github.com:immortal/immortal.git $HOME/go/src/github.com/immortal/immortal

Build by just typing make:

$ cd $HOME/go/src/github.com/immortal/immortal
$ make

To install/uninstall:

$ make install
$ make uninstall

configuration example

Content of file /usr/local/etc/immortal/www.yml:

# pkg install go-www
cmd: www
cwd: /usr/ports
log:
    file: /var/log/www.log
    age: 10  # seconds
    num: 7   # int
    size: 1  # MegaBytes
wait: 1
require:
  - foo
  - bar

If foo and bar are not running, the service www will not be started. Skip age, num & size options to avoid log-rotation completely.

foo and bar are the names for the services defined on the same path www.yaml is located, foo.yml & bar.yml

Paths

When using immortaldir:

/usr/local/etc/immortal
|--foo.yml
|--bar.yml
`--www.yml

The name of the file.yml will be used to reference the service to be daemonized excluding the extension .yml.:

foo
bar
www

/var/run/immortal/

/var/run/immortal
|--foo
|  |-lock
|  `-immortal.sock
|--bar
|  |-lock
|  `-immortal.sock
`--www
   |-lock
   `-immortal.sock

immortal like non-root user

Any service launched like not using using immortaldir will follow this structure:

~/.immortal
|--(pid)
|  |--lock
|  `--immortal.sock
|--(pid)
|  |--lock
|  `--immortal.sock
`--(pid)
   |--lock
   `--immortal.sock

The -name argument takes a non-path (e.g., “myservice”), and the argument will be used instead of the pid in the directory structure. For example, immortal -ctl myservice sleep 1000 will be:

~/.immortal
|--myservice
|  |--lock
|  `--immortal.sock

The -ctl argument takes precedence over the -name argument.

immortalctl

Will print current status and allow to manage the services

debug

pgrep -fl "immortal -ctl"  | awk '{print $1}' | xargs watch -n .1 pstree -p

Test status using curl & jq

status:

curl --unix-socket immortal.sock http:/status -s | jq

note the single ’/’ https://superuser.com/a/925610/284722

down:

curl --unix-socket immortal.sock http://im/signal/d -s | jq

up:

curl --unix-socket immortal.sock http://im/signal/u -s | jq