TraconSkillScriptOptions

Namespace Tracon · Assembly Tracon.Core.dll

Defines options that control server-side skill script execution.

public sealed class TraconSkillScriptOptions

Inheritance

object ← TraconSkillScriptOptions

Inherited Members

object.GetType(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()

Remarks

Tracon does not provide operating-system isolation..NET cannot portably disable network access, isolate the file system, apply CPU or memory quotas, or drop privileges. The host environment must provide this. Run Tracon with script execution enabled in a container, under an unprivileged user, and with restricted network access.

TraconSkillScriptOptions.PlatformIsolationAcknowledged is the explicit acknowledgment that this limit was read. TraconSkillScriptOptions.Enabled cannot be enabled without it, and the application fails during startup.

An approved script runs where the registered ISkillScriptExecutor runs it. The built-in executor starts a local process; a custom one can run the script in a container or a remote runner. The gates, the audit trail, the concurrency limits, the timeout, and the output limit in these options apply to every executor. The acknowledgment is required with a custom executor too: Tracon cannot verify the isolation an executor provides.

Constructors

TraconSkillScriptOptions()

public TraconSkillScriptOptions()

Properties

AllowStoredScripts

Gets or sets whether scripts stored in the database can run. Defaults to false.

public bool AllowStoredScripts { get; set; }

Property Value

bool

Remarks

When enabled, anyone who can write skills (the Admin role, or an API key with AgentsAdmin) can store code that runs on the server. The same flag covers the scripts of a skill registered in code with AddSkill.

Such a script runs only under a grant pinned to its exact content: a security administrator reads the content, grants its hash, and a later change stops the script until it is granted again. The interpreter allow-list (TraconSkillScriptOptions.Interpreters) is a further gate.

In a multi-tenant host, granting a stored script also needs platform authority: the script runs under the server’s own operating-system identity and can read what that identity reads, including other tenants’ secrets. A tenant’s administrator therefore cannot grant one alone.

Enabled

Gets or sets whether script execution is enabled. Defaults to false.

public bool Enabled { get; set; }

Property Value

bool

EnvironmentAllowList

Gets the allow list of environment variables passed to the script process.

public IList<string> EnvironmentAllowList { get; }

Property Value

IList<string>

Remarks

The built-in executor reads this list. A custom ISkillScriptExecutor receives no environment value from Tracon and sets the script’s environment itself.

Variables outside the list are not inherited from Tracon’s environment. This is not isolation: the script runs as the same operating-system user and can read whatever that user can read. On Linux that includes the environment Tracon started with, through /proc/<pid>/environ.

A connection string or API key in an environment variable is therefore readable by a script. Keep secrets out of the process environment while scripts run, or run the scripts under a separate, unprivileged user.

Interpreters

Gets the extension-to-interpreter-path allow list. Example: ["py"] = "/usr/bin/python3".

public IDictionary<string, string> Interpreters { get; }

Property Value

IDictionary<string, string>

Remarks

No script runs while the list is empty. Extensions are written without a leading dot and in lowercase. The built-in executor starts the value as the interpreter’s path; a custom ISkillScriptExecutor receives it as SkillScriptExecutionRequest.Interpreter and can read it as a runtime name instead.

MaxArgumentBytes

Gets or sets the largest byte count for JSON arguments supplied to a script.

public int MaxArgumentBytes { get; set; }

Property Value

int

MaxConcurrentPerTenant

Gets or sets the largest concurrent script count per tenant.

public int MaxConcurrentPerTenant { get; set; }

Property Value

int

MaxConcurrentTotal

Gets or sets the largest total concurrent script count.

public int MaxConcurrentTotal { get; set; }

Property Value

int

MaxOutputBytes

Gets or sets the largest byte count kept from each output stream of a script.

public int MaxOutputBytes { get; set; }

Property Value

int

Remarks

stdout and stderr are capped separately, each at this count, so one run can return up to twice this many bytes in total. Output past the cap is truncated and the result says so. Tracon applies the cap to whatever the ISkillScriptExecutor returns, so an executor cannot return more.

MaxScriptContentLength

Gets or sets the largest byte count for the content of one script.

public int MaxScriptContentLength { get; set; }

Property Value

int

Remarks

One limit for every script. A stored script larger than this is refused when it is saved. A script file under TraconSkillScriptOptions.SkillRoots larger than this, or empty, or not a regular file (a FIFO or a device), is refused before it runs, and the refusal is written to the audit trail.

MaxScriptsPerSkill

Gets or sets the largest script count that a skill can carry.

public int MaxScriptsPerSkill { get; set; }

Property Value

int

PlatformIsolationAcknowledged

Gets or sets whether the consumer acknowledges that Tracon does not provide operating-system isolation.

public bool PlatformIsolationAcknowledged { get; set; }

Property Value

bool

SearchDepth

Gets or sets the largest directory depth traversed under skill roots.

public int SearchDepth { get; set; }

Property Value

int

SkillRoots

Gets the roots used to search skill directories on disk.

public IList<string> SkillRoots { get; }

Property Value

IList<string>

Remarks

Roots are supplied in code only. Configuration never binds them: a root widens what the server reads and runs, like TraconSkillScriptOptions.Interpreters and TraconSkillScriptOptions.AllowStoredScripts. The UI cannot change them either. The person who writes script content deploys the application.

A script read from disk is not pinned to its content: its grant names the skill and the script only. Keep the roots read-only for the operating-system user Tracon runs as; anyone who can write to them changes what runs under an existing grant.

Timeout

Gets or sets the longest duration for one script to run.

public TimeSpan Timeout { get; set; }

Property Value

TimeSpan

Remarks

Must be from one millisecond to about 49.7 days minus five seconds while TraconSkillScriptOptions.Enabled is on; any other value fails at startup.

The value travels to the ISkillScriptExecutor, which stops the script at this time. Tracon waits five seconds longer; an executor that has not returned by then is no longer waited for, its slot in the concurrency limit is released, and the run is recorded as timed out. The executor may still be running the script.