Give a LangGraph or deepagents agent a Nevia computer as its sandbox backend, so its file tools and commands run on the computer
The LangGraph adapter gives a LangGraph
agent a sandbox backend on a Nevia computer. The agent's ls, read_file,
write_file, edit_file, glob, grep and execute tools run on the
computer, not on your machine. The adapter is built on the
Python SDK and is in early access, so names and
behaviour can change.
The quick start gives an agent a computer, asks it to write and run a program and deletes the computer. The adapter follows the deepagents sandbox backend contract, so the deepagents docs cover the tools and options. This page covers only what is particular to Nevia.
Prerequisites
You need:
- Python 3.11 or later.
deepagents0.7.langgraph1.2 or later.- An API key for the model provider. The quick start uses Anthropic, so it
needs
ANTHROPIC_API_KEY. - The
neviaCLI, signed in withnevia login, to download the SDK bundle. The Quickstart shows how to install it. - A Nevia key file for a service account with the editor role. Use an automation key file shows how a workspace admin issues one.
Install the adapter
Invited testers only
The SDKs are in early access for invited testers. To ask for access, see Request access to Nevia.
From your project's root, download the SDK bundle. It unpacks to
vendor/nevia-sdk-0.1.0/:
curl -fsSL --oauth2-bearer "$(nevia auth access-token)" https://sdk.nevia.cloud/0.1.0.tar.gz | tar -xzThen install the adapter, with the SDK beside it, from the bundle:
uv add "nevia-langgraph[anthropic] @ ./vendor/nevia-sdk-0.1.0/python/nevia_langgraph-0.1.0-py3-none-any.whl" \
./vendor/nevia-sdk-0.1.0/python/nevia-0.1.0-py3-none-any.whlName the SDK's file next to the adapter's, so both come from the bundle and nothing is looked up on a public registry.
The anthropic extra adds langchain-anthropic, so the quick start can name
an Anthropic model. The adapter installs deepagents with it.
Authenticate
Point the adapter at the key file and set the model provider's key:
export NEVIA_KEY_FILE="$HOME/path/to/key.json"
export ANTHROPIC_API_KEY="sk-ant-..."Without NEVIA_KEY_FILE, the adapter falls back to your nevia login
session. It finds credentials in the same order as the
Python SDK.
Give an agent a computer
Save this as agent.py:
from deepagents import create_deep_agent
from nevia_langgraph import NeviaSandbox
backend = NeviaSandbox(name='quickstart', image='docker.io/library/python:3.13-slim')
agent = create_deep_agent(model='anthropic:claude-sonnet-5-5', backend=backend)
try:
result = agent.invoke(
{
'messages': [
{
'role': 'user',
'content': 'Write hello.py that prints the Python version, then run it. Answer with its output only.',
}
]
}
)
print(result['messages'][-1].text)
finally:
backend.destroy()Run it:
python agent.pyThe agent writes /workspace/hello.py with write_file, runs python hello.py
with execute and answers with the output. The Python version varies:
Python 3.13.18The first tool call creates the computer and waits until it is ready.
Clean up
The finally block deletes the computer when the agent is done, even when the
call throws. nevia ls confirms the computer is gone.
To keep the computer between runs, skip destroy(). The sandbox name names
the computer, so a later program that builds NeviaSandbox with the same
name finds the same computer, files included. Call destroy() from that
program when you are done. To reach a computer by its ID instead, pass
computer=.
How the sandbox maps to a computer
NeviaSandbox is a deepagents sandbox backend, so create_deep_agent() gives
the agent deepagents' own tools. For a plain LangGraph agent, pass
FilesystemMiddleware(backend=backend) from deepagents.middleware to
create_agent(). The adapter adds the options image, env for environment
variables stored on the computer, working_dir, timeout, max_output_bytes
and capture_offload.
Two sandboxes with the same name share one computer, even across processes.
Without name or computer, each sandbox creates a computer with a generated
name. image and env apply only when the adapter creates the computer.
Commands and relative paths start in /workspace, which the adapter creates.
Pass working_dir to change it.
stop() sleeps the computer and the next call wakes it with its files intact.
A sleeping computer's disk still counts toward storage until destroy()
deletes it. close() closes the sandbox's HTTP client and leaves the computer
as it is.
Commands run in the foreground with direct exec, in bash when the image has it.
A command stops after 30 minutes unless you pass another timeout. Each output
stream keeps its last 64 KiB, and max_output_bytes sets another cap. A
truncated answer says so. The image needs no Python of its own.
Every method has an async form with an a prefix, such as aexecute and
adestroy, so agent.ainvoke() works too. The async forms run the sync method
in a worker thread.
Limitations
These add to the SDK's Limits and workarounds.
- No background commands. A command must end before the tool answers. Redirect long output to a file and read parts of it.
- Large results go to a file.
capture_offloadis on by default, so deepagents saves a large result in/large_tool_resultson the computer and returns a preview. If the image user can't write there, passcapture_offload=False. - Timeouts top out at 3600 seconds. A larger
timeoutmakesexecuteanswerError: Nevia could not run the commandwithtimeout_seconds is above 3600in the message.timeout=0removes the command timeout, but the session still ends after one hour. - Cancelling doesn't stop the command. Cancelling
aexecutereturns at once and frees its thread, but the command can keep running on the computer. - The sandbox takes a sync client.
nevia=accepts aNeviaand raisesTypeErrorfor anAsyncNevia.