#process-manager #unix-socket #long-running #process #manager #sockets #user

bin+lib sopht

cute program for managing long running processes in a (slightly) more sophisticated way than tmux

4 releases (2 breaking)

0.3.0 Jan 17, 2024
0.2.0 Dec 22, 2023
0.1.1 Dec 17, 2023
0.1.0 Dec 16, 2023

#614 in Unix APIs

45 downloads per month

MIT license

58KB
1K SLoC

cute program for managing long running processes in a (slightly) more sophisticated way than tmux.

links

overview

sopht consists of two programs: a server (sophtd) which runs on a unix socket and listens for connections from a sopht client (sopht). the server is responsible for starting and managing any processes the client requests. the client is responsible for validating the user's commands, communicating with the server, and finally conveying its response in a readable way to the user.

sopht is a user-level level program. this means that each user in a multi-user environment is encouraged to have their own instance of sophtd running in the background. sopht should never be run as the root/admin user! in fact, it will fail if run as a privileged user like root because this user has no home directory, which sopht needs to create the unix socket. see the install section below for information on how to properly install the client and server.

usage

sopht v0.3.0
cute process manager
(slightly) more sophisticated than tmux

commands:
  help
    prints this message

  hello
    requests the server greet you. kinda like a ping command, but friendlier

  shutdown
    shuts the server down gracefully

  start <...>
    attempts to run the rest of the arguments <..> as a command and begins
    managing the resulting process. pass "--restart <policy>" to set the restart
    policy of the process. valid restart policies are "never", "always", and
    "on-failure". if setting the restart policy to "on-failure", the
    "--retries <retry-count>" option must also be specified.

  output <pid>
    completely retrives the output of the process with the specified PID

  status
    retrieves the status of all managed processes

  stop <pid>
    stops the process with the specified PID and sets its restart policy to
    "never"

  restart <pid>
    stops the process with the specified PID and runs the same command again,
    creating a new process with a different PID.

  send <pid> <...>
    sends the rest of the arguments <...> as input to the process with PID
    <pid> a newline is automatically appended onto the output given to the
    process.

  change-policy <pid> <policy>  
    changes the policy of process with PID <pid> to the policy given by
    <policy>. unlike the "start" command, the policy must be written as one
    string like "on-failure 3" or "always".

contributing

there are lots of ways to help, see the contributing document to learn how.

build and install

currently, sopht is hosted solely on sourcehut. it follows the regular cargo build procedure though, so just clone this repository and build it. (make sure you're using the --release option for optimized and stripped binaries!) after that, the best way to install sopht currently is to just use the builtin install program to copy it to /usr/local/bin:

install ./target/release/sopht /usr/local/bin/sopht
install ./target/release/sophtd /usr/local/bin/sophtd

after this, copy the sopht.service into /etc/systemd/user/. now, start and stop sophtd via systemctl --user start sopht and systemctl --user stop sopht. some may prefer to enable sopht via systemctl --user enable sopht so sopht is available on system startup.

additionally, sopht can be installed via crates.io if you have cargo. although, this will prevent you from running sopht via the service file provided above:

cargo install sopht

Dependencies

~4–16MB
~151K SLoC