Shell & Python Tools

opentine provides two tools for code execution: run for shell commands and execute for Python code. Both are policy-gated: calls are rejected until you pass an explicit enabled policy.

run

Execute a shell command and return its output. The command is parsed to an argv array, runs with shell=False, and is disabled unless a ShellPolicy enables it.

run_example.py
1from opentine.tools.shell import run
2from opentine.core import ShellPolicy
3
4# Shell execution is disabled unless the policy enables it.
5policy = ShellPolicy(enabled=True, executables=("ls",))
6output = run("ls -la src/", policy=policy)
7print(output)

Parameters

  • command (str) — The shell command to execute.
  • timeout (int, default 30) — Maximum execution time in seconds. The command is killed if it exceeds this limit.
  • allowlist (list[str] | None, default None) — Legacy helper for executable filtering when the sandbox escape hatch is used. Prefer ShellPolicy.executables.
  • sandbox (bool, default True) — Legacy compatibility flag. With the default True, shell execution remains disabled unless policy is passed.
  • policy (ShellPolicy | None, default None) — Explicit policy controlling enablement, executable allowlist, cwd root, environment inheritance, timeout, and output cap.

Returns

The combined stdout and stderr output as a string.

Timeout

run_timeout.py
from opentine.core import ShellPolicy
from opentine.tools.shell import run

policy = ShellPolicy(
    enabled=True,
    executables=("python",),
    timeout_seconds=120,
)
output = run("python train_model.py", policy=policy)

Executable Allowlist

Use ShellPolicy.executables to restrict which commands an agent can run. Only explicitly approved executables will execute.

run_allowlist.py
1from opentine.core import ShellPolicy
2from opentine.tools.shell import run
3
4# Restrict execution to specific commands.
5policy = ShellPolicy(enabled=True, executables=("git", "npm", "python"))
6output = run("git status", policy=policy)
7
8# Commands outside the executable list are rejected.
9# run("rm -rf /", policy=policy)  # Error: 'rm' not in allowlist

Working Directory Root

Use ShellPolicy.cwd_root to require the current working directory to stay under a trusted project root.

run_cwd_root.py
from opentine.core import ShellPolicy
from opentine.tools.shell import run

# Limit shell execution to a project root and approved executables.
policy = ShellPolicy(
    enabled=True,
    executables=("git", "pytest"),
    cwd_root="/opt/project",
)
output = run("git status", policy=policy)

execute

Execute Python code in an isolated subprocess. It is disabled unless a PythonPolicy enables it, and environment variables are scrubbed unless explicitly inherited or allowlisted.

execute_example.py
1from opentine.tools.python import execute
2from opentine.core import PythonPolicy
3
4# Python execution is disabled unless the policy enables it.
5result = execute("""
6import json
7
8data = {"name": "opentine", "version": "0.1.0"}
9print(json.dumps(data, indent=2))
10""", policy=PythonPolicy(enabled=True))
11print(result)
12# {
13#   "name": "opentine",
14#   "version": "0.1.0"
15# }

Parameters

  • code (str) — The Python code to execute.
  • timeout (int, default 30) — Legacy timeout helper used when no explicit policy is supplied.
  • policy (PythonPolicy | None, default None) — Explicit policy controlling enablement, environment handling, timeout, output cap, and isolation backend metadata.

Returns

The combined stdout and stderr output as a string.

Timeout

execute_timeout.py
1from opentine.core import PythonPolicy
2from opentine.tools.python import execute
3
4# Set a custom timeout for long-running code.
5result = execute("""
6import time
7for i in range(5):
8    print(f"Step {i + 1}")
9    time.sleep(1)
10""", policy=PythonPolicy(enabled=True, timeout_seconds=60))

Environment Scrubbing

The subprocess runs with a scrubbed environment. API keys and other sensitive environment variables are not passed through. This prevents agents from accidentally leaking credentials via executed code.

execute_safety.py
1from opentine.core import PythonPolicy
2from opentine.tools.python import execute
3
4# Environment variables are scrubbed in the subprocess.
5# API keys and secrets are NOT available unless explicitly allowlisted.
6result = execute("""
7import os
8api_key = os.environ.get("ANTHROPIC_API_KEY")
9print(f"Key: {api_key}")  # Key: None
10""", policy=PythonPolicy(enabled=True))

Using with an Agent

Combine shell and Python execution with file system tools for a capable coding agent.

coding_agent.py
1from opentine import Agent
2from opentine.core import PythonPolicy, ShellPolicy
3from opentine.models.anthropic import Anthropic
4from opentine.tools.fs import read, write, ls
5from opentine.tools.shell import run as _run
6from opentine.tools.python import execute as _execute
7
8def shell(command: str) -> str:
9    """Run an approved shell command."""
10    return _run(
11        command,
12        policy=ShellPolicy(enabled=True, executables=("git", "python", "pytest")),
13    )
14
15def python(code: str) -> str:
16    """Execute Python code in an isolated subprocess."""
17    return _execute(code, policy=PythonPolicy(enabled=True))
18
19agent = Agent(
20    model=Anthropic("claude-sonnet-4-20250514"),
21    tools=[shell, python, read, write, ls],
22    system="You are a coding assistant. Run tests, execute code, and fix issues.",
23)
24
25run_result = agent.run_sync("Run the test suite and fix any failing tests")

Next Steps