agents-terminal
Policy-bound jailed terminal for agent execution.
argv in, stripped env out. No MCP server.
Quickstart
pip install agents-terminal
There is no init. The harness calls agents-terminal run. Nothing is written into IDE configs.
Source checkouts can also be installed and managed with vand.
What it does
Agents do not get a shell string. run takes an argv vector after --, so the host shell never parses the command.
The child inherits an allowlist, not the parent environment. Default names: PATH, HOME, USER, SHELL, TEMP / TMP, locale (LANG, LC_ALL, TERM), Windows roots (SYSTEMROOT, WINDIR), git author/committer, GITHUB_TOKEN, GH_TOKEN. Anything else is dropped unless you extend the list.
On timeout the process tree is killed (job object / process group). Working directory defaults to AGENTS_WORKSPACE_DIR or ~/.agents/workspace, created if missing.
Drivers
| Driver | When | Backend |
|---|---|---|
subprocess |
Windows / macOS stand-in, and the fallback | Allowlisted env, directory confinement, process-tree timeout |
openshell |
Linux / Docker / OpenShell on PATH |
openshell sandbox create |
auto (default) |
Starting point | openshell when that binary is on PATH (or inside WSL on Windows), else subprocess |
Set AGENTS_TERMINAL_DRIVER=openshell|subprocess|auto.
Environment
| Variable | Description |
|---|---|
AGENTS_TERMINAL_DRIVER |
auto (default), subprocess, or openshell |
AGENTS_WORKSPACE_DIR |
Working directory (default ~/.agents/workspace) |
AGENTS_TERMINAL_POLICY |
Path to a JSON policy file (driver, env_allow, timeout_sec, cwd, …) |
AGENTS_TERMINAL_ENV_ALLOW |
Extra names, comma-separated, appended to the default allowlist. Alias: AGENTS_TERMINAL_EXTRA_ENV |
AGENTS_TERMINAL_ENV_PASSTHROUGH |
1 / true / yes copies the full parent environment and skips the allowlist |
CLI
One command. No MCP. Machine-readable catalog: python -m agents_terminal --help-json.
| Command | Purpose |
|---|---|
agents-terminal run -- <argv…> |
Run that argv under the policy. No shell |
No subcommand prints help. Exit code is the child's exit code.
agents-terminal run -- echo hello
ABI
Contract in abi/:
Tests
python -m unittest discover -s tests -v
License
MIT. See LICENSE.
Release files for agents-terminal 0.0.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| agents_terminal-0.0.5.tar.gz | 15.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| agents_terminal-0.0.5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 29.0 kB
Release files / agents_terminal-0.0.5.tar.gz
| Download URL | agents_terminal-0.0.5.tar.gz |
|---|---|
| Size | 15.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
92a68c33e09b3927b4d9b17ac354ed8bc41ca7642171f136906c20d259c821b6
|
|
BLAKE2b-256 checksum How to use checksums |
86f9e9166d0438b196bce5f9de86a8440dec743e29cd57be9597379faceca646
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / agents_terminal-0.0.5-py3-none-any.whl
| Download URL | agents_terminal-0.0.5-py3-none-any.whl |
|---|---|
| Size | 13.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
247b0b899b39a50d18c22e5ecbda8664e9d113190ccb51ac46c85a39eb14e556
|
|
BLAKE2b-256 checksum How to use checksums |
385e2dbac3e3cd9253cd86d096ab1b22a5416b4c9b75e5cf52cb3df2824dd52a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
