# Rig

> Give a Rig agent a Nevia computer as its workspace, so its file tools and shell run on the computer

> Nevia is in early access for selected teams. The CLI installs with `curl -fsSL https://get.nevia.cloud | sh`, and the MCP server is at https://api.nevia.cloud/mcp. A person signs in once in the browser.
> Setup, sign-in and requesting access: [SKILL.md](https://nevia.cloud/SKILL.md). When Nevia fits and when it doesn't: [why.md](https://nevia.cloud/why.md).

> For the complete documentation index, see [llms.txt](https://nevia.cloud/llms.txt). This page's HTML version: https://nevia.cloud/docs/agent-frameworks/rig

The Rig adapter gives a [Rig](https://rig.rs) 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](https://nevia.cloud/docs/reference/sdk/rust.md) 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](https://docs.rs/rig-tools/0.46.0/rig_tools/) 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](https://nevia.cloud/docs/get-started/quickstart.md) shows how to install it.
* A Nevia key file for a service account with the **editor** role.
  [Use an automation key file](https://nevia.cloud/docs/guides/automation-key-file.md) shows how a
  workspace admin issues one.

## 1. Install the adapter

> **Invited testers only**
>
> The SDKs are in early access for invited testers. To ask for access, see
> [Request access to Nevia](https://nevia.cloud/docs/get-started/request-access.md).

From your project's root, download the SDK bundle. It unpacks to
`vendor/nevia-sdk-0.1.0/`:

```bash
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**

```bash
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
```

**Cargo.toml**

```toml
[dependencies]
nevia = { path = "vendor/nevia-sdk-0.1.0/rust/sdk-rust" }
nevia-rig = { path = "vendor/nevia-sdk-0.1.0/rust/adapter-rust-rig" }
rig-agent = "=0.46.0"
rig-core = { version = "=0.46.0", features = ["reqwest", "rustls"] }
rig-reqwest = "=0.46.0"
rig-tools = "=0.46.0"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```

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.

## 2. Authenticate

Point the adapter at the key file and set the model provider's key:

```bash
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](https://nevia.cloud/docs/reference/sdk/rust.md#client).

## 3. Give an agent a computer

Save this as `src/main.rs`:

```rust
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:

```bash
cargo run
```

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

```text
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.

## 4. 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](https://nevia.cloud/docs/reference/sdk/limits.md).

* **`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.
