The server waits for incoming connections and spawns a new thread for each client.

Each process runs in its own thread, too.


Every command you send to the server returns a status:

  • OK
  • OFFLINE process(es) do(es) not exist
  • EXISTS (returned by start) a process with this name is already running
  • UNKNOWN unknown error
  • PERMISSION_DENIED requested action needs other/higher privileges
  • ERROR protocol error
  • AUTHENTICATION_REQUIRED waiting for credentials
  • AUTHENTICATION_ERROR authentication failed (E.g. wrong credentials)

If a command returns additional information, it is prepended. E.g. list and cat return an additional part after the status.

The regex:-lines below show protocol syntax. (Tip: \d{2} means 2 numbers)


All parts are prefixed by their length!

E.g. The first part of each line, the command, is prefixed by 2 digits:

  • 05start…
  • 07command…
  • 03cat…

The regex: would be \d{2}command (following the arguments).


When a client connects it needs to authenticate first! Available authentication methods depend on whether your using a tcp socket or a unix domain socket.

username and password are both prefixed by 2 numbers.

regex: \d{2}username\d{2}password

All processes are executed as the configured user. You can configure a default user and/or specific ones for each virtual-user

TCP socket

E.g. tcprocd -H localhost -P 20103 or just tcprocd

When connecting, the server will always respond with AUTHENTICATION_REQUIRED and wait for credentials.

regex: \d{2}username\d{2}password



SECURITY RISK: Not configuring a user and group results in the processes being executed as root if tcprocd itself is run as root!

Unix domain socket

E.g. tcprocd -s /var/run/tcprocd.socket

The username will be the connected local user.

All processes are executed as the connected user by default. (Instead of the configured tcprocd default user!) This can still be changed at the user level.

When connecting to the server (E.g. tcproc -s /var/run/tcprocd.socket) it will either respond with OK or AUTHENTICATION_REQUIRED.

The password is optional for unix domain socket connections! If a user has a password the server will ask for it by returning AUTHENTICATION_REQUIRED. (Send only the password!)

regex: \d{2}password





regex: 04list

(no arguments)

List running processes of the connected user. One item per line.

The list will contain all processes if the connected user is an admin.


regex: 05start\d{2}process\d{3}command\d{3}path

Start a new named process. The path to run the command in is optional (just pass 000).

E.g. Run java -jar minecraft_server.1.8.jar -server nogui as myserver in /home/minecraft/myserver/:

05start08myserver048java -jar minecraft_server.1.8.jar -server nogui024/home/minecraft/myserver


regex: 04kill\d{2}process

Kill the given process if it is running.




regex: 03cat\d{2}process\d{1}start_line

Return lines of stdout starting at start_line and one item per line.

Pass 0 to get everything since the process started.




This might look confusing. Keep in mind that the start_line is prefixed by a single number:

  • ‘0’ is 1 number so its prefixed by ‘1’ -> ‘10’
  • ‘2723’ has 4 numbers so its prefixed by ‘4’ -> ‘42723’


regex: 07command\d{2}process\d{3}command

Send a command to stdin.

E.g. kick r4lph from the server:

07command08myserver011kick r4lph


regex: 06attach\d{2}process

Attach to the given process.



As soon as the server responds with OK the connection will be line-based until it is closed! Every line you send will be written to the attached process’s stdin.