# Server Definitions Server maintenance is an administrative function and is not available to standard users. ## Basic Settings For each server instance that is deployed, you must create a server definition entry in the administration console so that it is visible to the users. The following shows an example of the information required to create a server:

space.vars.X_Agent_Name_Single Server

The server name and description are arbitrary and can be anything you like. The license key should be a valid key provided by your supplier *(refer Server Licensing section).* The host name and port number are given during the installation of the server instance into the application server. See the **“Installation and Configuration”** section for more information. The server encryption key is optional. If you specify a key, it must match the **EncryptionKey** defined in the `magic.properties` file on the target server. It is important to note that you will always see a value in this field, even if you have chosen to make the field blank. This is to avoid accidentally exposing whether a console connection is encrypted or not. To disable encryption, simply blank out the field. The actual server type is designated here. There are 6 options as described below:
Server type
ProductionThis is the standard production server accepting any input
Multi-ProtocolThis is the server for managing protocols other than HTTP
TestThis is a test server that takes test data as input
DatabaseThis is a database server. This server type is used in configurations.
TemplateThis is a server template that other servers can inherit advanced setting from
Production with ForwarderThis is a production server with a built in forwarding proxy
From an installation perspective, there is no difference between a test server and a production server. They run the same code. However, by defining here which type a server is, you can limit which type of execution it can undertake. If you designate the server as a database server, it will not show up in the tree of Composable Agentic Platform servers, but you can select it during configuration of databases *(configuration, flight recorders and case managers).* A template server is defined only to allow advanced settings to be inherited from a nominated server. Like a database server, it also does not show up in the tree of Composable Agentic Platform servers. See **Advanced Server Configuration** below for more information. The optional Amazon Instance ID is used to automatically manage proxy instances that are located behind one or more Amazon Web Services (AWS) Elastic Load Balancers. If the ID is provided and Amazon credentials are set in the advanced settings (or inherited), then the server will automatically be deregistered and re-registered with the load balancers during deployment. The **Concurrent thread limit** controls how much work a space.vars.X\_Agent\_Name\_Single will process in parallel. Setting it to `1` forces sequential processing (every request handled one after another, useful for debugging). Setting it above `1` enables parallel processing using virtual threads. The field only has an effect for specific agent type / input adapter combinations — see the table in the **Threading and Concurrency Guide** below. ### Threading and Concurrency Guide Under the hood, Composable Agentic Platform uses **Java virtual threads** to run work in parallel. Virtual threads are lightweight — created on demand, a few kilobytes each, and managed entirely inside the JVM rather than by the operating system. There is no fixed thread pool to size up front. When a piece of work arrives, a virtual thread is created; when the work finishes, the thread is discarded. Thousands can exist simultaneously without memory pressure. This is a change from earlier versions, where concurrency was managed by a fixed-size OS thread pool sized at startup from a two-dimensional `Max Threads per CPU × Number of CPUs` formula. The formula and the two separate fields are gone. In their place is a single `Concurrent thread limit` that is only shown for the agent type / input adapter combinations listed below. For every other combination the field is hidden because it would have no effect — inbound HTTP concurrency is managed by the embedded Jetty server, Multi-Protocol agents manage concurrency per protocol inside their own dispatch path, and Template / Production with Forwarder / Multi-Protocol agent types hide the field entirely. #### Where the setting applies
Agent typeInput adapterHow to use
ProductionStressTestInputAdapterCaps the number of concurrent load-generation workers. Setting it to 50 means: fire up to 50 simultaneous virtual-thread requests at the target. The cap is intentional — it prevents a misconfigured test from fan-out-bombing an upstream that isn't sized for it.
ProductionDirectory file-batch adapters: CSVDirectoryInputAdapter, XMLDirectoryInputAdapter, XLSDirectoryInputAdapter, IdentifierDirectoryInputAdapter, MultilineCSVDirectoryInputAdapter= 1 forces sequential row-by-row processing (useful for debugging and for rulesets that require strict ordering). > 1 enables parallel row processing on virtual threads — rows are dispatched up to the configured concurrency limit.
TestSingle-file adapters: CSVFileInputAdapter, XMLFileInputAdapter, XLSFileInputAdapter, IdentifierFileInputAdapter, MultilineCSVFileInputAdapter, TestDataFileInputAdapter= 1 forces sequential row-by-row processing. > 1 enables parallel row processing on virtual threads.
{% hint style="info" %} The default of `1` means sequential processing. Leave it at `1` for development, debugging, and simple deployments. Raise it only when you have a workload that genuinely benefits from parallelism — typically file-batch processing of large input files, or stress-test load generation. {% endhint %} #### Why there are no longer "recommended values" tables In earlier versions, choosing the right thread count was a careful sizing exercise: every OS thread cost about 1 MB of stack memory, so the numbers had to be matched to the host's physical CPUs and available RAM. Under virtual threads that constraint is gone. A thread costs a few kilobytes and can block without tying up OS resources. You can set the value to `10`, `100`, or `1000` and the JVM will scale accordingly. In practice the number only matters in two cases: * **Stress-test rulesets** (using `StressTestInputAdapter`) — where you are explicitly choosing how much concurrent load to apply to a target system. The value should reflect what the target can handle, not what the test machine can produce. * **File-batch rulesets** (using CSV / XML / XLS or directory adapters) — where a very large value may exhaust downstream resources (database connections, external API rate limits) faster than a smaller value would. Match the setting to the bottleneck downstream of the agent, not to the agent itself. For rulesets using HTTP adapters and for forwarding proxies the setting has no effect at all. #### Container and cloud deployments In Docker and AWS ECS Fargate the `Concurrent thread limit` setting still follows the rules above — it is not a container-sizing dial. Container capacity is determined by the vCPU and memory allocation you configure in the ECS task definition, not by this setting. {% hint style="info" %} For cloud deployments, scaling horizontally (more container instances behind a load balancer) is almost always more effective than tuning this setting up. Use the **Desired Count** in your ECS task definition to add capacity. {% endhint %} The console depth is used to control the memory set aside on the server for the console. The depth refers to the number of lines of text kept before they are discarded. If you nominate a server to inherit advanced settings from, then the "Advanced" tab will disappear, and all of the settings will be derived from the nominated parent/template server. ## Advanced Server Configuration In addition to the basics of setting up a server, there are some advanced settings that determine how the server operates. The following shows the advanced settings:

Rules Server

The advanced settings determine parameters such as the Web Proxy the space.vars.X\_Agent\_Name\_Single must traverse to obtain internet access, the name of an SMTP server the space.vars.X\_Agent\_Name\_Single can use to send emails and the details of the email message to send, and the recipients of the notification email message sent when the space.vars.X\_Agent\_Name\_Single fails. It is also possible to modify the server encryption algorithm. Please do not enter anything in this field unless specifically instructed to do so by our support team. To avoid keying these parameters repeatedly for many servers, you can set up a Template server and inherit the settings from the Template server definition. ### **Setting the server web proxy** The rules in the space.vars.X\_Agent\_Name\_Single that use web access (such as the HTTP invocation rule) will obtain the proxy settings from the server definition. Please see the section on server definitions for more details. It is important to note that some rules using web access may still require direct access to the internet. This is typically dependent upon how the vendor API for the particular function is implemented. ### **Elastic Load Balancing – Amazon Web Services (AWS)** The console supports the ability to dynamically add and remove a selected server from one or more AWS Elastic Load Balancers during deployment. This approach serves to reduce the load contention on a very busy server if deploying whilst live. To make this work, you will need to specify an Amazon Instance ID in the basic settings, and either directly specify the region, load balancer name and credentials in the advanced settings or on the inherited template server settings. ### **Setting up logging** Logging by default will go to System out. However, some environments have configurations where it is convenient to have the space.vars.X\_Agent\_Name\_Single log information and errors to other places. #### **Apache Commons Logging Configuration** Apache Commons Logging is an open source logging feature that allows for logging to a variety of locations.

Logging

By default, Apache Commons Logging will auto-detect the correct log mechanism to use (Log4J, Avalon LogKit, JDK). However, it is possible to provide specific log factory parameters if required. #### **File out logging Configuration** File out logging provides the ability to log to a custom file name in a specific directory.

Configuratiopn

The configuration consists of a template file name (which may include a relative or absolute path) and optionally the number of days to retain log files. The template file name itself will be pre-pended with a time stamp in the form "**CCYY\_MM\_DD**." For example: "`logs\tests.log,60`" will result in files being saved in the folder logs with log files named `CCYY_MM_DD.tests.log` and the files will be retained for 60 days. {% hint style="danger" %} IMPORTANT: If you have more than one space.vars.X\_Agent\_Name\_Single installed on the same server, they may NOT write to the same log file. {% endhint %} #### **System out logging Configuration** System out logging will go to the standard System out configuration of the JDK or Application Server. No specific configuration is required. ## Forwarding Server Configuration If you nominate a server as a Production with Forwarder, then you will have one additional (Forwarding) tab to configure:

space.vars.X_Agent_Name_Single Server

It is extremely important to take care configuring these settings as an incorrect configuration can result in the creation of an open proxy. The protected hosts and schemes refer to a list of hosts and their access scheme. This is a definitive list of requests that will be allowed to go through the proxy. For example, it could be configured as: * * This will ensure that only http requests can go to the mysite.myhost.com site and that only SSL requests can go to mysecuresite.myhost.com. The request redirection option allows you full control over where incoming requests are redirected. This replaces the host file manipulation of earlier versions and also allows for port redirection and same server co-existence. Essentially, incoming requests for any given host can be redirected to any other host and/or port. The redirection is a list of hosts and schemes, followed by the ">" and the target host and port. For example, to redirect the site mysite.myhost.com to port 8080 on the same server, you would create an entry that reads: [http://mysite.myhost.com>http://mysite.myhost.com:8080](https://docs.tomorrowx.com/cap/product-reference/administration-functions/http:/mysite.myhost.com>http:/mysite.myhost.com:8080) {% hint style="warning" %} Write each redirection entry as `from>to` with **no spaces around the `>`**. The console tokenises the field on whitespace and commas, so `from > to` is treated as three separate tokens and rejected. Separate multiple entries with a comma or a newline. {% endhint %} Composable Agentic Platform can be configured to be an SSL terminator by redirecting the protocol from https to http. The allowed client IP addresses let you to control where requests coming to the forwarding proxy are allowed to originate from. This is predominantly useful in ensuring that a Proxy Server set up for testing does not become an open proxy for the entire corporation to use to bypass internet controls. The default setting is to only allow access from the loopback address of 127.0.0.1 The browser proxy port allows you to set up a proper browser level proxy that can be configured in Chrome, Edge, Firefox, Safari, or any modern web browser — or pushed to managed endpoints via MDM, Group Policy, or a PAC/WPAD file. This type of proxy correctly manages how the browser connects to the forwarding proxy for the purpose of SSL connections. It is especially useful for configuring the browser for testing new rules against sites that do not have Composable Agentic Platform installed *(refer to section Zero Installation Rules Testing).* The maximum size for cached objects sets a per-entry size ceiling (in KB) for the forwarding proxy's built-in response cache. Responses larger than this are served straight through without being stored. Setting the value to `0` disables the cache entirely. The cache only stores safe, idempotent traffic (successful `GET` requests with no per-user state) and respects standard `Cache-Control` headers on both the request and the response. Capture-mode requests — those handled by rulesets that read or modify the response body — always bypass the cache. The total cache size is managed automatically; only the per-entry ceiling is exposed here. The maximum client connections to one host caps the number of TCP sockets the proxy keeps open to any single upstream host. Under HTTP/1.1 upstreams this effectively caps concurrent requests one-for-one. Under HTTP/2 upstreams — which is now the default when the upstream supports it — a single socket can carry many simultaneous requests via HTTP/2 multiplexing, so this value caps socket resources rather than request concurrency. The default (250) is suitable for almost all deployments; only adjust it if you have a specific need to limit socket usage to a particular host. Close client connections to host, when enabled, adds a `Connection: close` header to every outbound request so the upstream host tears down the TCP connection after replying. Leave this off for normal operation — keep-alive is more efficient. Turn it on only if you need to isolate per-request state or are working with a backend that mishandles persistent connections. Clean cookie path, when enabled, strips the `Domain=` and `Path=` attributes from every cookie the backend sets before the browser sees it. This is most commonly needed in reverse-proxy deployments, where the hostname the browser sees and the hostname the backend thinks it's serving are different — without this option the browser will reject cookies it considers cross-origin. Leave on unless you have a specific reason to preserve the upstream cookie scoping. Trace enables detailed per-request logging in the server output: every request through the proxy produces an inbound line, an outbound line, and a response line with status and content type. This is a diagnostic setting — useful when investigating ruleset behaviour, confirming hostmap redirection, or troubleshooting upstream connectivity. Turn it off for normal production operation to avoid log volume. Upstream connection failures (DNS, TCP refusal, TLS handshake, read timeout, rewrite loop) are always logged as `ERROR:` lines regardless of this setting. Use web proxy allows you to force the proxy to connect to other hosts using the same web proxy as the space.vars.X\_Agent\_Name\_Single. This is predominantly useful if you are doing a "reverse protection" (that is: using the space.vars.X\_Agent\_Name\_Single to manage sites external to the local network, such as social networking or other data sensitive sites). ## Server Licensing Composable Agentic Platform is a licensed product and the terms of your license is contained in a license key that you obtain from your supplier. The license key is rather long so we suggest you copy and paste it directly into the server definition when you receive it, and do not attempt to type it. Once a valid license key is in place, the server will show the correct license terms on the server status screen as shown below:

Server Information

Although an invalid license key doesn’t prevent the server from being used, it will display **`INVALID`** if the license is invalid or missing.

Server Information

If you have a license that has expired, you will see a bold red **`EXPIRED`** notification, but the product will not stop running. It is your responsibility as the customer to ensure that you adhere to the license terms of your purchase. You may also be asked to provide your license key when obtaining product support. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tomorrowx.com/cap/product-reference/administration-functions/server-definitions.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.