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 | Provenance | Actions |
|---|---|---|---|---|
| agents_terminal-0.0.5.tar.gz | 15.1 kB | Without provenance | Details for agents_terminal-0.0.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agents_terminal-0.0.5-py3-none-any.whl | Python 3 | none | any | Details for agents_terminal-0.0.5-py3-none-any.whl |
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}
|
Security for agents-terminal 0.0.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
