Runtime and security
An extension runs on the selected Terminay Server, never in the Desktop or browser client. Treat a third-party extension as trusted server-side Node.js code.
Where code runs
| Boundary | What it means |
|---|---|
| Extension process | Each enabled extension has its own child process, private framed IPC channel, minimal inherited environment, and immutable package-slot working directory. |
| Clients | Desktop and browser clients render host-owned, declarative settings surfaces. They never download or execute extension code. |
| Remote environments | Use the terminal-scoped observation broker. Local Node filesystem or process APIs cannot identify a remote terminal or journal. |
Process isolation contains crashes and keeps extension IPC separate. It is not an operating-system sandbox: custom code can use public Node APIs with the selected server account’s authority. Review and install it accordingly.
Use the public boundary
The host provides typed registrations, scoped brokers, cancellation, deadlines, and bounded observation facts. It does not expose raw PTYs, client transports, Electron, host bridges, private Terminay packages, or direct mutation of the agent-status store.
| Need | Use |
|---|---|
| Read an agent journal | terminal.observation.files, which issues terminal-scoped opaque file handles. |
| Inspect a terminal process | terminal.observation.processes for bounded descendants, open-file facts, and declared environment names. |
| Use credentials | context.secrets.withValue() or the scoped SSH-agent broker—not environment variables or stored plaintext. |
| Call another provider | A manifest-declared dependency and context.dependencies.call(). |
Handle secrets transiently
Secret values stay in the Terminay Server vault. The broker checks ownership, gives your
callback a transient Uint8Array, then zeroizes its copy. Never return, cache,
log, or put those bytes in status data.
async function createEnvironment(request, context) {
return context.secrets.withValue(
{ profileId: request.profileId!, fieldId: 'token', purpose: 'create' },
async (token) => {
// Use the bytes only for this operation. Do not log or retain them.
return createRemoteEnvironment(token);
},
);
}The same rule applies to dependency vault callbacks. A target dependency handler receives only its vault broker—not the caller’s profiles, secrets, filesystem, or SSH agent.
Lifecycle behaviour
- Calls have cancellation, deadlines, idempotency keys for retries, and optional revision checks.
- A crash marks that extension unavailable; it does not take down Terminay or other providers.
- On shutdown, Terminay stops new work, cancels bounded work, calls
deactivate(), then terminates an unresponsive child.