> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# LangChain

> Expose Nullspace machine operations as LangChain tools.

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

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
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

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
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](./langgraph) service guide. That page
covers `mode = "service"`, binding to `0.0.0.0`, `permissions.public_url =
true`, and framework-owned thread/checkpoint state.

## Related

* [Agents overview](./overview)
* [Agent Deployments](./deployments)
* [LangGraph](./langgraph)
* [Commands](../commands/overview)
* [Filesystem](../filesystem)