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 machine workspace for bounded tool calls.

​
Install

python -m pip install langchain "nullspace-sdk==1.0.0"
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 Machine


@tool
def run_in_nullspace(command: str) -> str:
    """Run a short shell command in an isolated Nullspace machine."""
    with Machine.create(template="base", timeout=300) as machine:
        result = machine.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 machine tool for isolated execution.",
)

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

​
Tool Design

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