The virtual shell (VSH) provides a managed execution environment for running shell commands. It wraps process execution with session state — environment variables, aliases, and command history — and enforces timeouts to prevent runaway processes from blocking the agent.
The VSH maintains the state of a shell session across commands:
Environment variables — The shell session has its own environment. Variables can be set, updated, and unset within the session. Changes persist for the lifetime of the session but do not affect the host environment. The initial environment is populated from the host at session creation, with the option to start with a clean environment instead.
Aliases — Named command aliases expand before execution. Define short forms for long commands that get used repeatedly within a session. Aliases can be listed, added, or removed.
Command history — Every command executed in the session is appended to the session history. The history is searchable (by prefix or substring) and can be replayed. History persists across commands within a session.
Working directory — The shell session tracks a current working directory. cd commands update the tracked directory, and all relative paths in subsequent commands resolve against it.
Every command runs as a subprocess with:
Commands are executed asynchronously. The shell session can run commands concurrently if needed, though the default behavior is sequential.
Every command execution is wrapped in a configurable timeout. If the subprocess does not complete within the timeout window, it is killed and the executor returns a timeout error. This prevents long-running or hung commands from blocking the agent indefinitely.
The default timeout is 30 seconds. When running through the managed service or cloud, the timeout is set by the platform configuration.
For individual commands that need more time, the timeout can be overridden per-call. The minimum supported timeout is 1 second.
When a timeout fires, the subprocess is forcefully terminated. Any partial stdout and stderr captured before the timeout is returned alongside the error, so the caller can see what the command had produced up to the point it was killed.
The executor distinguishes between:
Callers receive the full result including stdout, stderr, and exit code, allowing the agent to interpret command output regardless of success or failure.
The VSH supports two backends, selected by configuration:
Local — Runs commands on the local host through the system's default shell (/bin/sh on Unix, cmd.exe on Windows). Shell builtins, pipelines, and redirection work as expected.
SSH — Runs commands on a remote host over an SSH connection. The remote session inherits the configured environment overrides and uses the same timeout enforcement as local execution. Each command starts a fresh shell invocation on the remote host with the configured environment applied.
Switching between backends requires only a configuration change — no other adjustments are needed.
The VSH does not prevent all side effects by default — commands run with the permissions of the simse process and can affect the host filesystem, network, and other resources. Isolation is achieved through policy, not a container boundary.
For stronger isolation:
vfs://) to redirect file writes away from the real filesystemThe combination of VSH + VFS + VNet provides enough isolation for most agentic workflows without requiring container infrastructure.
The shell backend and timeout are configured at the platform level. The CLI uses the local backend by default. When running through the managed service, the backend (local or SSH) is set by the platform.