Agent frameworks

Rig

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-agent and rig-tools).
  • An API key for the model provider. The quick start uses Anthropic, so it needs ANTHROPIC_API_KEY.
  • The nevia CLI, signed in with nevia 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 -xz

Then 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-rig

Rig'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 run

The agent writes hello.sh with the write tool, runs sh hello.sh with shell and answers with the output:

Hello from Linux

The 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.

  • shell needs experimental_processes(true). On a plain client shell answers 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 shell answers "nevia-rig-bridge was not found". Put it on PATH or beside your program, or name it with the NEVIA_RIG_BRIDGE environment variable or the bridge option.
  • 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 sh and coreutils. The file tools use wc, head, tail, sed, find, mktemp and base64. stat never 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 list of 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.

On this page