Introduction to WSTPServer

WSTPServer is a server program that launches and maintains Wolfram Language kernels for incoming WSTP connections. It listens on a single WSTP endpoint, allowing any number of clients to connect to a known location to obtain a kernel.
It routes all traffic to kernels that it manages, allowing links to WSTPServer to behave as if they were direct links to kernels. Kernels can be configured with specific properties through the use of kernel pools. Because a WSTPServer kernel can be connected to, disconnected from and reconnected to, you can maintain a long-lived session that you can connect to from different programs or machines. At the simplest level, you can think of WSTPServer as a provider of pre-launched, pre-configured Wolfram Language kernels, replacing the more typical procedure of launching a fresh kernel at the moment it is needed.
Launching WSTPServer
WSTPServer is a server program, and it must be running for you to be able to connect to it.
On macOS, run the following in Terminal to launch WSTPServer:
$ /Applications/Mathematica.app/Contents/SystemFiles/Links/WSTPServer/wstpserver

WSTPServer: Logger (0, 2020-09-29 16:50:00): Information:
    Using "/Applications/Mathematica.app/Contents/MacOS/WolframKernel" as a default kernel path

WSTPServer: Logger (0, 2020-09-29 16:50:05): Information:
    Listening for new connections on port 31415

...
On Windows, run the following in cmd.exe to launch WSTPServer:
$ "C:\Program Files\Wolfram Research\Mathematica\12.2\SystemFiles\Links\WSTPServer\wstpserver.exe"

WSTPServer: Logger (0, 2020-09-29 16:50:00): Information:
    Using "C:\Program Files\Wolfram Research\Mathematica\12.2\wolfram.exe" as a default kernel path

WSTPServer: Logger (0, 2020-09-29 16:50:05): Information:
    Listening for new connections on port 31415

...
On Linux, run the following in your terminal to launch WSTPServer:
$ /usr/local/Wolfram/Mathematica/12.2/SystemFiles/Links/WSTPServer/wstpserver

WSTPServer: Logger (0, 2020-09-29 16:50:00): Information:
    Using "/usr/local/Wolfram/Mathematica/12.2/Executables/WolframKernel" as a default kernel path

WSTPServer: Logger (0, 2020-09-29 16:50:05): Information:
    Listening for new connections on port 31415

...
Regarding the preceding, note that only 12.2 or later Wolfram Language layouts contain wstpserver. Adjust the paths accordingly if your product is not Mathematica (e.g. if it is Wolfram Desktop).
If your terminal returns to the command line, WSTPServer has exited due to an issue it cannot recover from, and you will not be able to connect to it. WSTPServer will log to your terminal the reason it exited.
WSTPServer can also be run under service management systems, such as launchd, systemd or the Windows Services Manager.
Persistent Kernels
Wolfram Language kernels are usually limited by their connection to the user: when a connection dies, so does the associated kernel, stopping any work it was doing. However, WSTPServer allows the user to disconnect from a kernel without killing it or stopping its work and to reconnect later to the same kernel.
An advantage to connecting to a kernel through WSTPServer is that you can build up state (e.g. by loading files, making definitions and evaluating expressions) but then leave the kernel alive such that you can reconnect to it later on, even from a different machine. An example is given in the section "Bridging to a Previously Used Kernel."
Another advantage is that WSTPServer can prevent the deaths of kernels involved in interrupted network connections, allowing the work of the kernels to continue. Connections over networks can be fragile, and occasionally they cannot be maintained. To return to a lost kernel, all the user has to do is reconnect to the WSTPServer and direct it to connect to the kernel that was lost.
A final example pertains to a long-running computation. The user can begin a long-running computation in a kernel managed by WSTPServer and then return to the kernel when the computation is expected to be finished, obtaining the result. The user could also connect to other kernels managed by WSTPServer while the initial kernel is busy, providing them with tasks as well.
Every kernel has a corresponding kernel ID that can be used to connect to that kernel. These IDs can be obtained by evaluating WSTPServer`GetKernelID[] in the kernel or using the GetKernelID WSTP command.
The term "bridge" is used often in this document. WSTPServer acts like a middleman, forwarding communications back and forth between a client and a kernel. A bridge is the connection established by WSTPServer between a client and a kernel. "Unbridging" discontinues the connection between a client and a kernel, although a client can then be bridged to a different kernel.
For more information on connecting to specific kernels, see the descriptions of the Wolfram Language function WSTPServer`ConnectKernel and the WSTP command ConnectKernel.
Kernel Pools
Kernel pools are groups of kernels that share a set of user-configured properties, such as initialization code. Most kernels managed by WSTPServer are expected to be members of such pools, and at least one kernel pool must be set as the default pool. Kernels from the default pool are provided to connections that do not request a specific kernel or pool. Configuring multiple kernel pools allows you to have different sets of pre-initialized kernels for different kinds of uses.
For more information on the configuration process for the default pool and kernel pools in general, see the section "Configuration File". For more information on connecting to specific kernels, see the descriptions of the Wolfram Language function WSTPServer`ConnectKernel and the WSTP command ConnectKernel. An example is given in the section "Bridging to a Specially Configured Pool" that describes the use of WSTPServer`ConnectKernel in bridging to a specific kernel pool.
Use with Various Clients
Much of the Wolfram System makes use of WSTP for communication with kernels. Accordingly, WSTPServer is easily integrated with many Wolfram System components.
This section gives a detailed description on the use of WSTPServer with many commonly used components.

Use with WolframScript

WolframScript is a command-line script interpreter for the Wolfram Language that can run Wolfram Language code, functions and deployed APIs. WolframScript can also connect to WSTPServer and interact with its kernels.
In the following example, WolframScript evaluates code in a WSTPServer kernel:
$ wolframscript -wstpserver -code "StringReverse[\"hello\"]"
olleh
WolframScript allows for the convenient reconnection to WSTPServer kernels. In order to accomplish this safely, it is recommended that connections to specific kernels be tracked in profiles on the filesystem that the user must manage. WolframScript records in the profile file the ID of the kernel being used in order to allow reconnection to that kernel.
To use a profile file that lets you reconnect to a WSTPServer kernel, use the -startprofile option:
You can use -continueprofile to reconnect to the same kernel and retrieve the value of x.
You can also use -wstpserver to connect to a particular WSTPServer. In this example, we connect to the WSTPServer running on our local machine listening on the port 31416.
When using WolframScript without WSTPServer, you get a fresh kernel for every computation. Using WSTPServer with -startprofile and -continueprofile allows you to maintain a session with the same kernel across multiple WolframScript computations.
The section "DETAILS" of the program page "WolframScript" describes the profile system in greater detail, as well as the options -wstpserver, -startprofile and -continueprofile. The section "OPTIONS" provides a useful high-level overview of WolframScript's command-line options.

Use with the Notebook Interface

The following instructions describe how to connect the notebook front end to WSTPServer and how to interact with its kernels:
1. Start the front end on your local machine. On the toolbar, navigate to Evaluation Kernel Configuration Options....
2. Add a new kernel and configure it. In the dialog, click Add, and a Kernel Configuration dialog appears.
3. Enter an appropriate name for your kernel, such as WSTPServerKernel.
4. Select the Advanced Options switch. In the text field called "Arguments to MLOpen," enter the following, where "port" and "host" (optional) should be replaced by the port and host, respectively, that WSTPServer is listening on:
5. Click OK and open a new notebook.
6. On the toolbar, navigate to Evaluation Notebook's Kernel and choose the name of the kernel that you just created.
7. Inside the notebook, verify that evaluating commands (e.g. 2+2, WSTPServer`GetKernelID[]) in the kernel managed by WSTPServer yields the expected results.
Some examples relating to the use of the notebook interface with WSTPServer are given in the section "Appendix: Example Scenarios."

Use for Parallel Computing

The Wolfram Language provides a powerful and unique environment for parallel computing. Typically, much of the functionality can be used with a minimum of effort and without paying too much detail to the low-level internals of the parallel system.
WSTPServer can manage a pool of parallel kernels for use by the parallel computing functionality. The parallel computing functionality requires additional configuration in order to connect to the WSTPServer parallel kernels. An example is given in the section "Making Use of the Parallel Computing Functionality" that describes this process when using the front end.
The WSTPServer-related section of "Launching and Connecting" describes the interface with the parallel computing functionality in greater detail and also provides a lower-level method for connecting to WSTPServer parallel kernels.

Use with the WSTP C Binding

All of the preceding clients make use of WSTP to a great extent, but they hide many of its lower-level details. WSTP provides a C binding for developers who want to use the full power of WSTP directly.
It is easy to connect to WSTPServer from your own WSTP programs. WSTP connections to WSTPServer are almost identical to connections to normal kernels. Typically, WSTPServer will send an InputNamePacket to the client when the client connects. WSTPServer will then forward any communications from the client to the kernel, and any communications from the kernel to the client. From the client's perspective, it appears to be a direct link to the kernel.
A significant exception to this description is that WSTPServer allows a class of commands to be sent over the WSTP connection in WSCommandPacket packets. These commands are intercepted by WSTPServer and are not forwarded to the kernel. Descriptions of these commands are given in the section "Command Language."
The following sample program connects to WSTPServer and performs a computation. It is a completely standard WSTP program except for the way in which the link is opened. Note the "-linkmode connect -linkname 31415 -linkprotocol TCPIP -linkoptions 4" specification in the call to WSOpenString.
/************************************
    include directives
*************************************/

#include "stdio.h" /* printf */

#include "wstp.h" /* WSENV, WSLINK, WSInitialize, WSOpenArgcArgv, ... */

/************************************
    define directives
*************************************/

#define WSTP_ENVIRONMENT_ERROR 1
#define WSTP_OPEN_ERROR 2
#define WSTP_ACTIVATION_ERROR 3
#define WSTP_INPUTNAMEPACKET_ERROR 4
#define WSTP_GENERAL_ERROR 5

/************************************
    connecting to a link server
*************************************/

/* entry point */
int main(int argc, char **argv)
{
    WSENV env;
    WSLINK link;

    int error;

    /* initialize a WSTP environment */
    env = WSInitialize(NULL);
    if(env == NULL)
    {
        (void) printf("%s\n", "Could not initialize a WSTP environment");
        return WSTP_ENVIRONMENT_ERROR;
    }

    /* open a link to a WSTPServer listening on port 31415 on the local machine */
    link = WSOpenString(env, "-linkmode connect -linkname 31415 -linkprotocol TCPIP -linkoptions 4", &error);
    if(link == NULL || error)
    {
        (void) printf("%s\n", "Could not open a link to WSTPServer");
        return WSTP_OPEN_ERROR;
    }

    /* activate the link to WSTPServer */
    error = WSActivate(link);
    if(!error)
    {
        (void) printf("%s\n", "Could not activate the link to WSTPServer");
        return WSTP_ACTIVATION_ERROR;
    }

    /* receive InputNamePacket packet */
    if(WSNextPacket(link) != INPUTNAMEPKT)
    {
        (void) printf("%s\n", "Could not receive InputNamePacket packet");
        return WSTP_INPUTNAMEPACKET_ERROR;
    }
    (void) WSNewPacket(link);

    /* send over the link:
        EvaluatePacket[2 + 2] */
    if(
        !(
            WSPutFunction(link, "EvaluatePacket", 1) &&
                WSPutFunction(link, "Plus", 2) &&
                    WSPutInteger(link, 2) &&
                        WSPutInteger(link, 2) &&
                            WSFlush(link)
        )
    )
    {
        (void) printf("%s\n", "General WSTP error occurred");
        return WSTP_GENERAL_ERROR;
    }

    /* read off packets until ReturnPacket */
    while(
        (WSNextPacket(link) != RETURNPKT) &&
            (WSError(link) == WSEOK)
    ) { }
    if(WSError(link) != WSEOK)
    {
        (void) printf("%s\n", "General WSTP error occurred");
        return WSTP_GENERAL_ERROR;
    }

    /* clean up */
    (void) WSClose(link);
    (void) WSDeinitialize(env);

    return 0;
}
Configuration File
The behavior of WSTPServer is primarily controlled through the wstpserver.conf configuration file.
Configuration files are searched for first in the current working directory and then in the application data directory. If no valid configuration file is present, a configuration file with default content is created in the application data directory.

Key-Value Pairs

WSTPServer recognizes the following root keys in the configuration file:
AllowStealingKernels
true
whether a client can use a kernel ID to bridge to a kernel already bridged to another client
AllowSilentKernelReplacement
false
whether when a bridged kernel dies, a new kernel should be silently started to replace the dead kernel without closing the client link
EnableAutomaticKernelConnection
true
whether a kernel from the default pool should be bridged immediately with a client link upon connection, as opposed to bridging a kernel only when the first non-WSCommandPacket expression is sent over the client link
Pools
required
list of pools for WSTPServer to use
SendInputNamePacketUponKernelConnection
true
whether an InputNamePacket should be sent for bridging events that occur after the client connects
At least one named kernel pool is required in Pools, but the key-value pairs it can contain are optional, and they have default values.
With AllowStealingKernels set to true, you can switch from one computer to another and keep the same kernel session without first unbridging from the kernel on the original computer.
With AllowSilentKernelReplacement set to true, kernels that WSTPServer itself closed (e.g. because of a KeepAlive flag set to false) will not be replaced. If AllowSilentKernelReplacement is false, when a bridged kernel dies, the client link bridged to the kernel will be closed.
WSTPServer recognizes the following keys for the kernel pools inside Pools:
Default
automatic
whether to use this pool as the default for new clients
InitializationCode
""
initialization code to run for the kernels in the pool
InitializationFile
""
initialization file to run for the kernels in the pool
KernelPath
automatic
path to the Wolfram Language kernel executable that the kernels in the pool will run
KernelOptions
""
additional command-line options to the Wolfram Language kernel executable that the kernels in the pool will run
KeepAlive
true
whether to keep kernels alive indefinitely or to close them when they become unbridged
MaximumKernelNumber
automatic
the maximum number of running kernels the pool can contain
MinimumKernelNumber
2
the minimum number of running kernels the pool will always contain
ParallelKernelDefault
automatic
whether to use this pool as the default for parallel computing
ParallelKernels
false
whether the kernels of the pool should be configured for parallel computing
ReservePreviouslyConnectedKernels
true
whether previously bridged kernels can only be bridged again with clients that request them by their IDs
The automatic value for Default is true for the first kernel pool object.
The automatic value for ParallelKernelDefault is true for the first pool object with ParallelKernels set to true.
The automatic value for KernelPath is an auto-discovered string, but this auto-discovery may fail; if so, KernelPath becomes required.
The automatic value for MaximumKernelNumber is the value of MinimumKernelNumber if this value is greater than 0; otherwise, the value is 2.
WSTPServer will pre-launch a number of kernels equivalent to the value of MinimumKernelNumber when it starts up. These kernels can be warmed up with the configuration file keys InitializationCode or InitializationFile.
With KeepAlive set to true, kernels will not be closed when a client disconnects, allowing them to be connected to again by the same client or a different client. Clients must be careful to use the Wolfram Language function WSTPServer`DisconnectKernel or the WSTP command DisconnectKernel instead of Quit or Exit, which will cause the kernel to exit.
If ReservePreviouslyConnectedKernels is false, preference is given to previously bridged kernels, if they exist, in order of when they were unbridged.
Command Language
WSTPServer can be controlled dynamically through the use of commands. Commands are sent directly over a WSTP connection to WSTPServer in a special wrapper called WSCommandPacket; results of these commands are sent back in ReturnPacket packets. WSCommandPacket functionality is intended for developers writing their own WSTP programs for use with WSTPServer. A WSCommandPacket example is given in the section "Use with the WSTP C Binding."
The structure of command packets should be the following:
    
WSCommandPacket[command[arguments]]
The structure of return packets to command packets will be the following:
    
ReturnPacket[returnvalue]
ReturnPacket["{\"status\":\"PacketMalformed\"}"] will be returned if the command packet sent was not correctly structured.
The possible commands expected in a command packet are the following:
CloseKernel
close the specified kernel
ConnectKernel
bridge the current connection with the specified kernel
ConnectParallelKernel
bridge the current connection with the first available kernel in the parallel kernel default pool
DisconnectKernel
unbridge the current connection with its bridged kernel
GetKernelBusyStatus
tell whether the kernel bridged to the current connection is busy with an evaluation
GetKernelID
get the ID of the kernel bridged to the current connection
GetNumberOfAvailableParallelKernels
get the number of available kernels in the parallel kernel default pool
GetPoolName
get the name of the pool of the kernel bridged to the current connection
GetServerInformation
get information about all pools and all kernels
SetAllowSilentKernelReplacement
set whether to allow or disallow the silent replacement of the kernel bridged to the current connection if that kernel dies
SetKeepAlive
set whether to close the kernel bridged to the current connection when the current connection dies or the bridge ends
SetReserveKernel
set whether the current kernel, when unbridged, can only be bridged to clients that request it by ID
StartKernel
start a kernel (outside of any pools), and return its ID
The following subsections describe all of the WSTP commands given in further detail.

WSTP Command: CloseKernel

WSCommandPacket[CloseKernel["id"]] closes the kernel with the ID id.
On success, ReturnPacket["{\"status\":\"ExecutionSuccess\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.

WSTP Command: ConnectKernel

WSCommandPacket[ConnectKernel[]] bridges the current connection with an available kernel from the default pool. If the kernel is still busy with an evaluation from a previously bridged client, the function will wait for a short default timeout period before failing.
WSCommandPacket[ConnectKernel["kernelSpecifier"]] bridges the current connection with the kernel with the ID kernelSpecifier if kernelSpecifier is a kernel ID, or with an available kernel from the kernel pool with the name kernelSpecifier if kernelSpecifier is a kernel pool name. If kernelSpecifier is a kernel ID, any existing bridge with the specified kernel is terminated. If the kernel is still busy with an evaluation from a previously bridged client, the function will wait for a short default timeout period before failing.
WSCommandPacket[ConnectKernel["kernelSpecifier", timeout]] bridges the current connection with the kernel with the ID kernelSpecifier if kernelSpecifier is a kernel ID, or with an available kernel from the kernel pool with the name kernelSpecifier if kernelSpecifier is a kernel pool name. If kernelSpecifier is a kernel ID, any existing bridge with the specified kernel is terminated. If the kernel is still busy with an evaluation from a previously bridged client, the function will wait for timeout seconds before failing.
On success, ReturnPacket["{\"status\":\"ExecutionSuccess\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.

WSTP Command: ConnectParallelKernel

WSCommandPacket[ConnectParallelKernel[]] bridges the current connection with an available kernel from the parallel kernel default pool. If the kernel is still busy with an evaluation from a previously bridged client, the function will wait for a short default timeout period before failing.
WSCommandPacket[ConnectParallelKernel[timeout]] bridges the current connection with an available kernel from the parallel kernel default pool. If the kernel is still busy with an evaluation from a previously bridged client, the function will wait for timeout seconds before failing.
On success, ReturnPacket["{\"status\":\"ExecutionSuccess\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.

WSTP Command: DisconnectKernel

WSCommandPacket[DisconnectKernel[]] unbridges the current connection with its bridged kernel.
DisconnectKernel fails if the current connection is not bridged.
On success, ReturnPacket["{\"status\":\"ExecutionSuccess\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.

WSTP Command: GetKernelBusyStatus

WSCommandPacket[GetKernelBusyStatus[]] tells whether the kernel bridged to the current connection is busy with an evaluation. This function will fail if the current connection is not bridged.
WSCommandPacket[GetKernelBusyStatus["id"]] tells whether the kernel with the ID id is busy with an evaluation.
On success, ReturnPacket["{\"result\":\"True\"}"] or ReturnPacket["{\"result\":\"False\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.

WSTP Command: GetKernelID

WSCommandPacket[GetKernelID[]] gets the ID of the kernel bridged to the current connection.
GetKernelID fails if the current connection is not bridged.
On success, ReturnPacket["{\"result\":\"id\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.

WSTP Command: GetNumberOfAvailableParallelKernels

WSCommandPacket[GetNumberOfAvailableParallelKernels[]] gets the number of available kernels in the parallel kernel default pool.
On success, ReturnPacket["{\"result\":\"num\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned. The value of num is the number of available kernels in the parallel kernel default pool.

WSTP Command: GetPoolName

WSCommandPacket[GetPoolName[]] gets the name of the pool of the kernel bridged to the current connection.
GetPoolName fails if the current connection is not bridged, or if the kernel is not part of a pool.
On success, ReturnPacket["{\"result\":\"name\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.

WSTP Command: GetServerInformation

WSCommandPacket[GetServerInformation[]] gets information about all pools and all kernels.
On success, ReturnPacket["json"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned. On success, json will match the JSON schema following:
{
    "result":
        {
            # An object containing configured pools and their properties
            "Pools":
                {
                    string: # The name of a particular pool
                        # An object containing the properties of a particular pool and their values
                        {
                            "InitializationCode":string,
                            "InitializationFile":string,
                            "MaximumKernelNumber":number,
                            "MinimumKernelNumber":number,
                            "KeepAlive":Boolean,
                            "EntryPool":Boolean,
                            "KernelPath":string,
                            "PreferFreshKernel":Boolean,
                            "ReservePreviouslyConnectedKernels":Boolean,
                            "ParallelKernels":Boolean,
                            "ParallelKernelEntryPool":Boolean
                        },
                        ...
                }
            }
        }
}
An example is given in the section "Monitoring WSTPServer" that describes the use of the similar Wolfram Language function WSTPServer`GetServerInformation in monitoring WSTPServer.

WSTP Command: SetAllowSilentKernelReplacement

WSCommandPacket[SetAllowSilentKernelReplacement[setting]] allows or disallows the silent restart of the kernel bridged to the current connection if the kernel dies. The value of setting should be either True or False.
SetAllowSilentKernelReplacement fails if the current connection is not bridged. SetAllowSilentKernelReplacement overrides the AllowSilentKernelReplacement configuration file key with respect to the current bridge.
On success, ReturnPacket["{\"status\":\"ExecutionSuccess\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.

WSTP Command: SetKeepAlive

WSCommandPacket[SetKeepAlive[setting]] instructs WSTPServer whether to close the kernel bridged to the current connection when the current connection dies or the bridge ends. The value of setting should be either True or False.
SetKeepAlive fails if the current connection is not bridged. SetKeepAlive overrides the KeepAlive configuration file key with respect to the current bridge.
On success, ReturnPacket["{\"status\":\"ExecutionSuccess\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.

WSTP Command: SetReserveKernel

WSCommandPacket[SetReserveKernel[setting]] sets whether the current kernel, when unbridged, can only be bridged to clients that request it by ID. The value of setting should be either True or False.
SetReserveKernel fails if the current connection is not bridged or if the kernel is not part of a pool. The effect of SetReserveKernel on the kernel persists through bridge events. SetReserveKernel overrides the ReservePreviouslyConnectedKernels configuration file key with respect to a bridge.
On success, ReturnPacket["{\"status\":\"ExecutionSuccess\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.

WSTP Command: StartKernel

WSCommandPacket[StartKernel[]] starts a kernel (outside of any pools) and returns its ID.
WSCommandPacket[StartKernel["commandLine"]] starts a kernel (outside of any pools) with commandLine and returns its ID.
On success, ReturnPacket["{\"result\":\"id\"}"] is returned; on failure, ReturnPacket["{\"status\":\"ExecutionError\"}"] is returned.
Wolfram Language Functions
The previous section described a low-level method to control WSTPServer using WSCommandPacket packets. There is also an analogous set of Wolfram Language functions that allows WSTPServer kernels themselves to access and control WSTPServer.
The Wolfram Language commands are the following:
WSTPServer`CloseKernel
close the specified kernel
WSTPServer`ConnectKernel
bridge the current connection with the specified kernel
WSTPServer`DisconnectKernel
unbridge the current connection with its bridged kernel
WSTPServer`GetKernelID
get the ID of the kernel bridged to the current connection
WSTPServer`GetPoolName
get the name of the pool of the kernel bridged to the current connection
WSTPServer`GetServerInformation
get information about all pools and all kernels
WSTPServer`SetAllowSilentKernelReplacement
set whether to allow or disallow the silent replacement of the kernel bridged to the current connection if that kernel dies
WSTPServer`SetKeepAlive
set whether to close the kernel bridged to the current connection when the current connection dies or the bridge ends
WSTPServer`SetReserveKernel
set whether the current kernel, when unbridged, can only be bridged to clients that request it by ID
WSTPServer`StartKernel
start a kernel (outside of any pools) and return its ID
The following subsections describe all of the Wolfram Language functions given in further detail.

Wolfram Language Function: WSTPServer`CloseKernel

WSTPServer`CloseKernel["id"] closes the kernel with the ID id.
On success, a success object is returned; on failure, a failure object is returned.

Wolfram Language Function: WSTPServer`ConnectKernel

WSTPServer`ConnectKernel[] bridges the current connection with an available kernel from the default pool. If the kernel is still busy with an evaluation from a previously bridged client, the function will wait for a short default timeout period before failing.
WSTPServer`ConnectKernel["kernelSpecifier"] bridges the current connection with the kernel with the ID kernelSpecifier if kernelSpecifier is a kernel ID, or with an available kernel from the kernel pool with the name kernelSpecifier if kernelSpecifier is a kernel pool name. If kernelSpecifier is a kernel ID, any existing bridge with the specified kernel is terminated. If the kernel is still busy with an evaluation from a previously bridged client, the function will wait for a short default timeout period before failing.
WSTPServer`ConnectKernel["kernelSpecifier", timeout] bridges the current connection with the kernel with the ID kernelSpecifier if kernelSpecifier is a kernel ID, or with an available kernel from the kernel pool with the name kernelSpecifier if kernelSpecifier is a kernel pool name. If kernelSpecifier is a kernel ID, any existing bridge with the specified kernel is terminated. If the kernel is still busy with an evaluation from a previously bridged client, the function will wait for timeout seconds before failing.
On success, a success object is returned; on failure, a failure object is returned.

Wolfram Language Function: WSTPServer`DisconnectKernel

WSTPServer`DisconnectKernel[] unbridges the current connection with its bridged kernel.
WSTPServer`DisconnectKernel fails if the current connection is not bridged.
On success, a success object is returned; on failure, a failure object is returned.

Wolfram Language Function: WSTPServer`GetKernelID

WSTPServer`GetKernelID[] gets the ID of the kernel bridged to the current connection.
WSTPServer`GetKernelID fails if the current connection is not bridged.
On success, "id" is returned; on failure, a failure object is returned.

Wolfram Language Function: WSTPServer`GetPoolName

WSTPServer`GetPoolName[] gets the name of the pool of the kernel bridged to the current connection.
WSTPServer`GetPoolName fails if the current connection is not bridged, or if the kernel is not part of a pool.
On success, "name" is returned; on failure, a failure object is returned.

Wolfram Language Function: WSTPServer`GetServerInformation

WSTPServer`GetServerInformation[] gets information about all pools and all kernels.
On success, an Association similar to the JSON schema given in the section "Monitoring WSTPServer" is returned; on failure, a failure object is returned.
An example is given in the section "Monitoring WSTPServer" that describes the use of the similar Wolfram Language function WSTPServer`GetServerInformation in monitoring WSTPServer.

Wolfram Language Function: WSTPServer`SetAllowSilentKernelReplacement

WSTPServer`SetAllowSilentKernelReplacement[setting] allows or disallows the silent restart of the kernel bridged to the current connection if the kernel dies. The value of setting should be either True or False.
WSTPServer`SetAllowSilentKernelReplacement fails if the current connection is not bridged. WSTPServer`SetAllowSilentKernelReplacement overrides the AllowSilentKernelReplacement configuration file key with respect to the current bridge.
On success, a success object is returned; on failure, a failure object is returned.

Wolfram Language Function: WSTPServer`SetKeepAlive

WSTPServer`SetKeepAlive[setting] sets whether the current kernel, when unbridged, can only be bridged to clients that request it by ID. The value of setting should be either True or False.
WSTPServer`SetKeepAlive fails if the current connection is not bridged or if the kernel is not part of a pool. The effect of WSTPServer`SetKeepAlive on the kernel persists through bridge events. WSTPServer`SetKeepAlive overrides the KeepAlive configuration file key with respect to a bridge.
On success, a success object is returned; on failure, a failure object is returned.

Wolfram Language Function: WSTPServer`SetReserveKernel

WSTPServer`SetReserveKernel[setting] sets, following the Boolean value setting, whether the current kernel, when unbridged, can only be bridged to clients that request it by ID.
WSTPServer`SetReserveKernel fails if the current connection is not bridged or if the kernel bridged to the current connection is not part of a pool. The effect of WSTPServer`SetReserveKernel on the kernel persists through future bridge events. WSTPServer`SetReserveKernel overrides the ReservePreviouslyConnectedKernels key from the configuration file for a kernel.
On success, a success object is returned; on failure, a failure object is returned.

Wolfram Language Function: WSTPServer`StartKernel

WSTPServer`StartKernel[] starts a kernel (outside of any pools), and returns its ID
WSTPServer`StartKernel["commandLine"] starts a kernel (outside of any pools) with commandLine and returns its ID.
On success, "id" is returned; on failure, a failure object is returned.
Appendix: Command-Line Options
The command-line options for WSTPServer are the following:
-h, --help
print help text
-l, --log-level n
specify the level of verbosity of messages
-f, --log-file [file]
write messages to a specified file
-a, --advertise [service]
if present, advertise the link server as the specified service
-p, --port port
listen on the specified port
-i, --interface interface
listen on the specified interface
-c, --configuration-file file
use the specificied configuration file
The three levels of verbosity of --log-level and -l are the following:
error, 1
report server startup/shutdown errors and print a successful startup message
debug, 2
report everything from level 1 and all debug messages
trace, 3
report everything from level 2 and all handled WSTP traffic
If --log-level or -l is not used, the default logging verbosity is set to error.
If --log-file or -f is not used, or is used without specifying a file, messages will be written to stdout.
If
--advertise [service]
or
-a [service]
is used, WSTPServer will try to advertise itself as WSTPServer-Instance or
WSTPServer-Instance-service
, depending on whether service was specified. WSTPServer will log the service name it is advertising at.
If --advertise or -a is not used, the link server will not be advertised.
If --port or -p is not used, the link server will listen on the port 31415.
If --interface or -i is not used, the link server will listen on the default network interface. Set the interface to localhost to make WSTPServer not visible on the local network.
If --configuration-file or -c is not used, the link server will use the default configuration file search behavior and usage.
Appendix: Example Scenarios

Making Use of Parallel Computing Functionality

WSTPServer can manage a pool of parallel kernels for use by the Wolfram Language parallel computing functionality.
The following instructions demonstrate how to make use of parallel computing functionality with WSTPServer using the front end:
1. Make sure to configure parallel kernels using the wstpserver.conf configuration file.
# wstpserver.conf: place in the current working directory
{
    "Pools":
        {
            "IProvideParallelKernels":
                {
                    "Parallel":true,
                    "MinimumKernelNumber":4
                }
        }
}
2. Inside a notebook, evaluate Needs["WSTPServerTools`"].
3. Add WSTPServer parallel kernels to the parallel computing functionality with AppendToConfiguredKernels["port@hostname", num]. The first argument describes the port and hostname (optional) of the WSTPServer to connect to. The second argument describes the number of WSTPServer parallel kernels to make use of.
4. Run some code that can make use of the parallel computing functionality (e.g. ParallelSum[EulerPhi[i], {i, 10^6}]).
5. Optionally, check that the configured WSTPServer parallel kernels were successfully connected to in step 3 with Kernels[].

Bridging to a Specially Configured Pool

WSTPServer allows for the configuration of pools for specific purposes (e.g. through the use of a shared initialization file). Use of the command language will be required to make use of such a pool if it is not the default pool. The Wolfram Language function WSTPServer`ConnectKernel and the WSTP command ConnectKernel can be used to bridge to the pool.
The following instructions demonstrate how to bridge to a specially configured pool using WolframScript:
1. Make sure to configure a pool using the wstpserver.conf configuration file.
# wstpserver.conf: place in the current working directory
{
    "Pools":
        {
            "IDefineX":
                {
                    "InitializationCode":"x=4"
                }
        }
}
2. Using the console, run wolframscript -wstpserver -startprofile. If WSTPServer cannot be discovered, use the -wstpserver wstpserverbase option.
3. Inside the WolframScript REPL, optionally verify the pool of the currently bridged kernel with WSTPServer`GetPoolName[]. Note that x evaluates to 4 as expected given the initialization code for the pool.
$ wolframscript -wstpserver -kernelpool AlternativeThree

In[1]:= WSTPServer`GetPoolName[]

Out[1]= IDefineX

In[2]:= x

Out[2]= 4

In[3]:=

Bridging to a Previously Used Kernel

It can be useful to return to a previously used kernel after building up state. Typically this will require WSTPServer to be configured to keep kernels alive indefinitely using the configuration file key KeepAlive. The Wolfram Language function WSTPServer`ConnectKernel or the WSTP command ConnectKernel will be required.
The following instructions demonstrate how to build up state in a kernel and then return to that kernel using WolframScript:
1. Make sure to configure kernels that can stay alive indefinitely using the wstpserver.conf configuration file.
# wstpserver.conf: place in the current working directory
{
    "Pools":
        {
            "IBuildUpState":
                {
                    "KeepAlive":true
                }
        }
}
2. Using the console, run wolframscript -wstpserver -startprofile. If WSTPServer cannot be discovered, use the -wstpserver wstpserverbase option.
3. Inside the WolframScript REPL, obtain the ID of the current kernel ID with WSTPServer`GetKernelID[]. The result is important: it will allow you to return to the current kernel later.
$ wolframscript -wstpserver -startprofile              

In[1]:= WSTPServer`GetKernelID[]

Out[1]= a806-2645-9651

In[2]:=
4. Make definitions and build up state.
5. Safely unbridge and disconnect from WSTPServer with WSTPServer`DisconnectKernel[].
In[10]:= WSTPServer`DisconnectKernel[]                                                                                                                         
$
6. To return to the kernel obtained in step 2, run wolframscript -wstpserver -continueprofile.
7. Optionally, verify the ID of the currently bridged kernel with WSTPServer`GetKernelID[].
$ wolframscript -wstpserver -continueprofile              

In[11]:= WSTPServer`GetKernelID[]

Out[11]= a806-2645-9651

In[12]:=

Using the WolframScript Profile Systems

WolframScript allows for the convenient reconnection to WSTPServer kernels. It is recommended that connections to specific kernels be tracked in profile files that the user must manage. WolframScript records in the profile file the ID of the kernel being used in order to allow reconnection to that kernel.
The section "DETAILS" of the program page "WolframScript" describes the profile system in greater detail, as well as the options -wstpserver, -startprofile and -continueprofile. The section "OPTIONS" provides a useful high-level overview of WolframScript's command-line options.
The following instructions demonstrate how to bridge to a kernel with specific properties using WolframScript:
1. Make sure to configure a kernel with the desired properties using the wstpserver.conf configuration file.
# wstpserver.conf: place in the current working directory
{
    "Pools":
        {
                "IHaveSpecificProperties":
                {
                    "KeepAlive":true,
                    "ReservePreviouslyConnectedKernels":false
                }
        }
}
2. Create a profile file that contains the desired properties of the WSTPServer kernel.
# sampleprofile
KEEPALIVE=TRUE # I want a kernel with "KeepAlive" set to true
RESERVE=TRUE # I want a kernel with "ReservePreviouslyConnectedKernels" set to false
3. Using the console, run wolframscript -wstpserver -startprofile sampleprofile. If WSTPServer cannot be discovered, use the -wstpserver wstpserverbase option.
$ wolframscript -wstpserver -startprofile sampleprofile             

In[1]:=
4. Inside the WolframScript REPL, make definitions and build up state.
In[1]:= x = 2 + 2

Out[1]:= 4
5. Safely unbridge and disconnect from WSTPServer with WSTPServer`DisconnectKernel[].
In[10]:= WSTPServer`DisconnectKernel[]                                                                                                                         
$
6. To return to the kernel obtained in step 3, run wolframscript -wstpserver -continueprofile sampleprofile.
$ wolframscript -wstpserver -continueprofile sampleprofile         

In[11]:= x

Out[11]:= 4

Keep a Kernel Alive after Disconnecting from WSTPServer Contrary to Configuration

Typically, keeping a kernel alive after disconnecting from WSTPServer would require WSTPServer to be configured with the configuration file key KeepAlive set to true, but the Wolfram Language function WSTPServer`SetKeepAlive and the WSTP command SetKeepAlive can keep the currently bridged kernel alive indefinitely.
The following instructions demonstrate how keep the kernel alive even after unbridging with WSTPServer`SetKeepAlive and then return to that kernel using WolframScript:
1. Create a notebook using a WSTPServer kernel configuration.
2. Inside the notebook, obtain the ID of the current kernel ID with WSTPServer`GetKernelID[]. The result is important: it will allow you to return to the current kernel later.
3. Safely unbridge and disconnect from WSTPServer with WSTPServer`DisconnectKernel[].
4. Return to the kernel by running wolframscript -wstpserver -continueprofile. If WSTPServer cannot be discovered, use the -wstpserver port@host option.
5. Inside the WolframScript REPL, optionally verify the ID of the currently bridged kernel with WSTPServer`GetKernelID[].
$ wolframscript -wstpserver -continueprofile              

In[11]:= WSTPServer`GetKernelID[]

Out[11]= 825c-6cbd-129b

In[12]:=

Reserving a Kernel That Is Doing Important Work

It can be useful to only allow the current kernel, when unbridged, to be bridged to clients that request it by its ID. This will make it such that the current kernel will be available to users who need that kernel specifically, and it will protect the current kernel's session from users who do not need that specific kernel. This is the default behavior if the configuration file key ReservePreviouslyConnectedKernels is set to true.
The Wolfram Language function WSTPServer`SetReserveKernel or the WSTP command SetReserveKernel allows the current kernel to be reserved regardless of the value of ReservePreviouslyConnectedKernels. The following instructions demonstrate how to successfully reserve and safely unbridge from a kernel using WSTPServer`SetReserveKernel and the front end:
1. Create a notebook using a WSTPServer kernel configuration.
2. Inside the notebook, reserve the kernel with WSTPServer`SetReserveKernel[True].
3. Safely unbridge and disconnect from WSTPServer with WSTPServer`DisconnectKernel[].

Monitoring WSTPServer

WSTPServer is a server program, so it can be useful to check its current state and get diagnostic information. The Wolfram Language function WSTPServer`GetServerInformation or the WSTP command GetServerInformation is provided for this purpose.
The following instructions demonstrate how to get information about the current state of WSTPServer using the front end:
1. Create a notebook using a WSTPServer kernel configuration.
2. Inside the notebook, get information about the current state of WSTPServer with WSTPServer`GetServerInformation[].