Shell & Python Tools

opentine provides two tools for code execution: run for shell commands and execute for Python code. Both include safety mechanisms to prevent unintended side effects.

run

Execute a shell command and return its output. Commands are sandboxed by default, and you can restrict which commands are allowed with an allowlist.

run_example.py
1from opentine.tools.shell import run
2
3# Run a shell command (sandboxed by default)
4output = run("ls -la src/")
5print(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) — List of allowed command names. If set, only commands whose base name matches an entry in the list will execute. All others are rejected.
  • sandbox (bool, default True) — Whether to sandbox the command execution.

Returns

The combined stdout and stderr output as a string.

Timeout

run_timeout.py
# Set a custom timeout (default is 30 seconds)
output = run("python train_model.py", timeout=120)

Command Allowlist

Use the allowlist parameter to restrict which commands an agent can run. This is the primary safety mechanism — only explicitly approved commands will execute.

run_allowlist.py
1# Restrict to specific commands with an allowlist
2output = run(
3    "git status",
4    allowlist=["git", "npm", "python"],
5)
6
7# Commands not in the allowlist are rejected
8# run("rm -rf /", allowlist=["git"])  # Blocked: "rm" not in allowlist

Disabling the Sandbox

For trusted environments, you can disable sandboxing. Use with caution.

run_nosandbox.py
# Disable sandboxing for trusted commands
output = run("docker ps", sandbox=False)

execute

Execute Python code in an isolated subprocess. Environment variables are scrubbed so that API keys and secrets are not accessible to the executed code.

execute_example.py
1from opentine.tools.python import execute
2
3# Execute Python code in an isolated subprocess
4result = execute("""
5import json
6
7data = {"name": "opentine", "version": "0.1.0"}
8print(json.dumps(data, indent=2))
9""")
10print(result)
11# {
12#   "name": "opentine",
13#   "version": "0.1.0"
14# }

Parameters

  • code (str) — The Python code to execute.
  • timeout (int, default 30) — Maximum execution time in seconds.

Returns

The combined stdout and stderr output as a string.

Timeout

execute_timeout.py
1# Set a custom timeout for long-running code
2result = execute("""
3import time
4for i in range(5):
5    print(f"Step {i + 1}")
6    time.sleep(1)
7""", timeout=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
1# Environment variables are scrubbed in the subprocess
2# API keys and secrets are NOT available to executed code
3result = execute("""
4import os
5api_key = os.environ.get("ANTHROPIC_API_KEY")
6print(f"Key: {api_key}")  # Key: None
7""")

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.models.anthropic import Anthropic
3from opentine.tools.shell import run
4from opentine.tools.python import execute
5from opentine.tools.fs import read, write, ls
6
7agent = Agent(
8    model=Anthropic("claude-sonnet-4-20250514"),
9    tools=[run, execute, read, write, ls],
10    system="You are a coding assistant. Run tests, execute code, and fix issues.",
11)
12
13run_result = agent.run_sync("Run the test suite and fix any failing tests")

Next Steps