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.4
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.4.tar.gz | 13.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| agents_terminal-0.0.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 26.6 kB
Release files / agents_terminal-0.0.4.tar.gz
| Download URL | agents_terminal-0.0.4.tar.gz |
|---|---|
| Size | 13.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a850ea08d49fd9ce5323960f35e2278713a9331d5f5ea469594c5fed77e1807d
|
|
BLAKE2b-256 checksum How to use checksums |
0047e96a3a5acdcee7a9324d9375f28c4fecd0131a2c3d306d0cebff6386ff03
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.6
|
Release files / agents_terminal-0.0.4-py3-none-any.whl
| Download URL | agents_terminal-0.0.4-py3-none-any.whl |
|---|---|
| Size | 13.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cf45f6fa896fe05e1d264e2733fb5734778264cad2ed7e845d746e1384585c56
|
|
BLAKE2b-256 checksum How to use checksums |
3507090351063ffb7438ea22d454a4545677e25725d63e930a1fe745ff00d409
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.6
|
