Skip to main content
Use this pattern when a LangChain agent should call Nullspace as a tool for isolated command execution, file work, or preview URL creation. The framework process stays in your application, while Nullspace supplies the sandbox workspace for bounded tool calls.

​
Install

python -m pip install langchain "nullspace-sdk==0.1.9"
export NULLSPACE_API_KEY=ns_live_...
export NULLSPACE_API_URL=https://api.your-nullspace-domain

​
Minimal Tool

from langchain.agents import create_agent
from langchain.tools import tool
from nullspace import Sandbox


@tool
def run_in_nullspace(command: str) -> str:
    """Run a short shell command in an isolated Nullspace sandbox."""
    with Sandbox.create(template="base", timeout=300) as sandbox:
        result = sandbox.commands.run(command, shell=True, timeout=120)
        return result.stdout[-4000:] or result.stderr[-4000:]


agent = create_agent(
    model="openai:<model-name>",
    tools=[run_in_nullspace],
    system_prompt="Use the sandbox tool for isolated execution.",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Check uname -a in a sandbox."}]}
)
print(result)

​
Tool Design

  • Keep tool inputs narrow and typed.
  • Return bounded text; store large artifacts in sandbox files or volumes.
  • For multi-step repo work, create a sandbox once and pass the ID through your application state instead of creating a new sandbox per tool call.
  • Nullspace run IDs are not conversation session IDs. Framework session, thread, checkpoint, or flow state stays app-owned.
  • Use volumes, retained sandboxes, hibernate/auto-resume, or an external database when state must survive sandbox cleanup.

​
Deploying LangGraph

If your LangGraph app should run as the managed process instead of calling Nullspace as a tool, use the LangGraph service guide. That page covers mode = "service", binding to 0.0.0.0, permissions.public_url = true, and framework-owned thread/checkpoint state.