Give a Rig agent a Nevia computer as its workspace, so its file tools and shell run on the computer
The Rig adapter gives a Rig agent a workspace on a Nevia
computer. The agent's read, write, edit, search, list, delete,
move and shell tools from rig-tools run on the computer, not on your
machine. The adapter is built on the Rust 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 script
and deletes the computer. The adapter follows Rig's Workspace contract, so
Rig's tools docs cover the
tools and options. This page covers only what is particular to Nevia.
Prerequisites
You need:
- Rust 1.97.1 or later, with the 2024 edition.
- Rig 0.46 (
rig-core,rig-agentandrig-tools). - 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 add the adapter and the SDK from it:
cargo add --path vendor/nevia-sdk-0.1.0/rust/sdk-rust
cargo add --path vendor/nevia-sdk-0.1.0/rust/adapter-rust-rig
cargo add rig-agent@=0.46.0 rig-tools@=0.46.0 rig-reqwest@=0.46.0
cargo add rig-core@=0.46.0 --features reqwest,rustls
cargo add tokio --features macros,rt-multi-thread
cargo install --path vendor/nevia-sdk-0.1.0/rust/adapter-rust-rigRig's shell tool runs commands through nevia-rig-bridge, a program that
ships with the adapter. The cargo install line puts it on your PATH, where
the adapter finds it. If your Cargo.toml has a [workspace] table, add
exclude = ["vendor"] to 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
Rust SDK.
Give an agent a computer
Save this as src/main.rs:
use std::sync::Arc;
use nevia::{Client, Nevia};
use nevia_rig::NeviaWorkspace;
use rig_agent::AgentBuilder;
use rig_core::providers::anthropic;
use rig_tools::workspace::Workspace;
use rig_tools::{Read, Shell, Write};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let nevia = Nevia::new(Client::builder().experimental_processes(true).build()?);
let computer = nevia
.computers()
.create()
.image("docker.io/library/debian:12-slim")
.await?;
let result = ask(NeviaWorkspace::new(computer.clone())?).await;
computer.delete().await?;
println!("{}", result?);
Ok(())
}
async fn ask(workspace: NeviaWorkspace) -> Result<String, Box<dyn std::error::Error>> {
let workspace: Arc<dyn Workspace> = Arc::new(workspace);
let model = anthropic::wire::AnthropicConfig::from_env()?
.connect(rig_reqwest::shared())
.completion(anthropic::CLAUDE_SONNET_5_5);
let agent = AgentBuilder::new(model)
.preamble("You write and run code on a Linux computer. Be brief.")
.tool(Read {
workspace: workspace.clone(),
..Read::default()
})
.tool(Write {
workspace: workspace.clone(),
..Write::default()
})
.tool(Shell {
workspace,
..Shell::default()
})
.build();
let response = agent
.prompt("Write hello.sh that prints a greeting with the kernel name from uname -s, then run it. Answer with its output only.")
.max_turns(5)
.await?;
Ok(response.output().to_string())
}Run it:
cargo runThe agent writes hello.sh with the write tool, runs sh hello.sh with
shell and answers with the output:
Hello from LinuxThe client turns on experimental_processes(true) because shell runs
commands as processes, which the SDK keeps behind that option for now. The
computer exists before the agent starts, and the first tool call wakes it if it
is asleep.
Clean up
main() unwraps the agent's result only after computer.delete(), so the
computer is deleted also when the agent call fails.
nevia ls confirms the computer is gone.
To keep the computer between runs, skip delete() and give the computer a
name(...) when you create it. A later program finds it with
nevia.computers().find(name) and wraps it in a new NeviaWorkspace, files
included. Call computer.delete() from that
program when you are done.
How the workspace maps to a computer
NeviaWorkspace::new(computer) returns a Rig Workspace, so the agent uses
Rig's own tools. NeviaWorkspace::builder(computer) adds bridge to
name the nevia-rig-bridge program and runtime for the tokio runtime the
workspace drives the SDK on.
The adapter works on a computer you create, so create() sets its name and
image. Two workspaces on the same computer share its disk. Dropping the
workspace leaves the computer running.
Relative paths resolve under ~, the home directory of the image's user.
Absolute paths reach anywhere on the computer. Rig's tools take a base for
another root.
A shell command runs as a Nevia process through the bridge. A timeout, an
interrupted call or a dropped process stops the command on the computer too.
Each file tool call runs one sh script on the computer.
Limitations
These add to the SDK's Limits and workarounds.
shellneedsexperimental_processes(true). On a plain clientshellanswers every call with an unsupported error and only the file tools work. The option is outside the SDK's stability promise.- The bridge must be on this machine. Without the bridge
shellanswers "nevia-rig-bridge was not found". Put it onPATHor beside your program, or name it with theNEVIA_RIG_BRIDGEenvironment variable or thebridgeoption. - The workspace is synchronous. Each call blocks on its own tokio runtime
or the one you pass to
runtime. - No streaming stdin. A command reads its whole input before it starts.
- The image needs
shand coreutils. The file tools usewc,head,tail,sed,find,mktempandbase64.statnever reports a modification time. - Large files take several calls. Reads move in 256 KiB chunks and writes
in 512 KiB chunks. The API cuts a call at about 50 seconds, which a very large
file or a
listof a huge tree can exceed. - An interrupted write isn't repeated. If the connection drops during a write, the error says whether the file holds what was sent and asks for a read before the next attempt.