Configuration
The proxy reads its settings from two files in the proxy directory:
- Windows service settings (
service_config.toml): the service name, the environment variables of the service, and the HTTP server used by the push transport mode. - Proxy settings (
conf.toml): global limits and the execution profiles.
Both files are written in TOML. Annotated examples ship with the proxy as
service_config.toml.sample and conf.toml.sample. The examples below show the recommended setup with the
pull transport mode, where the proxy opens all connections itself.
Installations set up before the TOML files were introduced may keep their conf.json and service_config.json,
which hold the same settings in JSON. The proxy reads the JSON file when no TOML file with the same name exists.
Windows service settings
service_config.toml configures the Windows service:
| Key | Default | Description |
|---|---|---|
name | techwork-automator-proxy-service | Windows service name |
description | automator Proxy service | Windows service description |
https_proxy | — | URL of the company HTTP proxy for outbound connections (see Connect using HTTP proxy) |
env | — | Additional environment variables for the service, as NAME = "value" lines in an [env] table |
With the pull transport mode, the automator never connects to the proxy, so a minimal configuration suffices:
name = "techwork-automator-proxy-service"
description = "automator Proxy service"
Push transport mode only
Profiles using the push transport mode accept incoming requests. The following settings configure the HTTP server for them and are not needed otherwise:
| Key | Default | Description |
|---|---|---|
port | — | Port the server listens on. Without it, the proxy accepts no incoming connections |
route_prefix | execute | URL prefix for the API routes |
ssl_key_path | — | Path to SSL private key file (enables HTTPS) |
ssl_cert_path | — | Path to SSL certificate file (enables HTTPS) |
Set port, and both ssl_key_path and ssl_cert_path so the endpoint is served over HTTPS.
When the proxy is started directly instead of as a service, the environment variables PORT and ROUTE_PREFIX
override the port and the URL prefix.
Proxy settings
conf.toml holds the global settings and the execution profiles. The global settings are top-level keys, each
profile is a [[profile]] section, and each script of a script-mode profile is a [[profile.script]] section.
The file is read once at startup; restart the proxy after changing it. When it cannot be loaded, the proxy does not
start and logs an error naming the line of a syntax error, the offending section, or an unknown key.
Global settings
| Key | Default | Description |
|---|---|---|
shell | — | Shell type: powershell (runs powershell.exe), unix (/bin/bash), or cmd (cmd.exe) |
shell_path | based on shell | Custom shell executable path (overrides the default for shell) |
init_cmd | — | Command prefix prepended to every command (e.g. powershell.exe -c) |
env_vars | ["PATH"] | List of environment variable names to pass to executed commands |
logfile | log/execproxy.log | Path to the log file |
max_call_stack_count | 10000 | Maximum number of queued requests before the throttle rejects with overflow |
throttle_calls_per_sec | 100 | Number of requests executed per second |
The shell settings apply to every profile: the proxy runs on one machine, so all profiles execute through the same shell with the same environment.
Profiles
Each [[profile]] section defines an execution target. Each profile matches one Proxy account on the automator
platform:
| Key | Required | Default | Description |
|---|---|---|---|
name | Yes | — | Unique profile identifier |
mode | Yes | — | Execution mode: exec or script |
token | Yes | — | Authentication token (must match the Proxy account's token) |
key | Yes | — | Encryption key (must match the Proxy account's key). Script mode requires exactly 64 hexadecimal characters (256 bits); generate one with node bin/secret |
active | No | true | Whether the profile is enabled |
automator_url | No | — | The Automator URL shown on the Proxy account form. When set, the profile uses the pull transport mode; when omitted, it listens for pushes at /execute/<name>. |
working_dir | No | — | Working directory for the child process. Relative paths resolve against the proxy directory, so scripts means the scripts folder inside the proxy installation |
Scripts
A script-mode profile lists the scripts a package may run as [[profile.script]] sections. A script section belongs
to the nearest [[profile]] section above it. Profiles in exec mode cannot have script sections.
| Key | Required | Description |
|---|---|---|
name | Yes | The script name a package passes to executeOnProxy. Unique within the profile |
file | Yes | Path to the script file; relative paths resolve against working_dir |
params | No | Array of allowed parameter names, including their - or -- prefix |
Example profile
A script-mode profile using the pull transport mode, allowing packages to run a single PowerShell script
(createUser.ps1) with two parameters:
shell = "powershell"
[[profile]]
name = "execute_ps_script"
mode = "script"
token = "<your-token>"
key = "<your-secret-key>"
automator_url = "<the Automator URL copied from the account>"
working_dir = "scripts"
[[profile.script]]
name = "createUser"
file = "createUser.ps1"
params = ["-Name", "-Department"]