How the runtime handles secrets, authentication, and isolation boundaries.
Secrets pass through. They never persist.
The runtime receives tokens and environment variables from the agent or startup configuration, forwards them to child processes, and never writes them to disk.
┌──────────────────┐ ┌───────────────────┐ ┌──────────────┐
│ Agent / Config │────>│ Terminal Runtime │────>│ Child Process│
│ TG_BOT_TOKEN=.. │ │ Holds in memory │ │ Sees in env │
│ CURSOR_API_KEY= │ │ Never writes disk│ │ at runtime │
└──────────────────┘ └───────────────────┘ └──────────────┘
Runtime startup — from the runtime’s own environment or .env fileSession creation — per-session vars via session.create paramsCommand execution — per-command vars via exec.run / exec.stream params
Scope Visibility Lifetime
Runtime-level All sessions, all commands Until runtime restarts Session-level All commands in that session Until session destroyed Command-level Only the specific command Until command exits
Never log env var values. Log keys only, never values.Never write env vars to disk. No temp files, no config dumps.Never return env vars in API responses unless explicitly requested (and consider masking).Never embed secrets in the runtime binary.
Mechanism: File system permissions on the socket fileRecommendation: Set socket permissions to 0600 (owner only)
Mechanism: Bearer token authenticationToken source: TRL_AUTH_TOKEN environment variableEvery request: Authorization: Bearer <token>If TRL_AUTH_TOKEN is not set when HTTP is enabled, the runtime should refuse to start .
Aspect How
Environment Each session gets its own env set. Working directory Each session has its own cwd. Process tree Each session’s processes are tracked; session.destroy kills the tree. Output stdout/stderr are per-session, per-command.
Aspect Future Fix
File system L2: chroot or Docker Network L2: network namespaces Resources L2: cgroups; see Resource Control Users L2: per-session user
Threat Mitigation
Agent sends malicious command TRL executes blindly — agent is responsible for safety. TRL provides timeouts and kill switches. Secret exfiltration via output Agent should redact secrets before displaying to users. Unauthorized API access Socket permissions (local) or bearer token (HTTP). Fail secure if misconfigured. Session hijacking Session IDs are random UUIDs. No enumeration. Zombie processes after crash Periodic reaping; clean orphaned processes on startup. Resource exhaustion Max session limits, per-command timeouts, setrlimit; see Resource Control .