# Alloy

> Give an Alloy agent a Nevia computer as its tools, so its shell and file tools 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/alloy

The Alloy adapter gives an [Alloy](https://hexdocs.pm/alloy) agent tools on a
Nevia computer. The agent's `bash` and file tools run on the computer, not on
your machine. The adapter is built on the
[Elixir SDK](https://nevia.cloud/docs/reference/sdk/elixir.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 program
and deletes the computer. The adapter follows Alloy's
[tool contract](https://hexdocs.pm/alloy/Alloy.Tool.html), so
[Alloy's docs](https://hexdocs.pm/alloy/Alloy.html) cover the agent loop,
providers and options. This page covers only what is particular to Nevia.

## Prerequisites

You need:

* Elixir 1.19 or later on your machine.
* Alloy 0.13 or later. The adapter pulls it in.
* 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 from it to the `deps` in `mix.exs`, and run `mix
deps.get`:

**mix.exs**

```elixir
defp deps do
  [
    {:nevia_alloy, path: "vendor/nevia-sdk-0.1.0/elixir/adapter-elixir-alloy"}
  ]
end
```

**Mix.install**

```elixir
Mix.install([{:nevia_alloy, path: "vendor/nevia-sdk-0.1.0/elixir/adapter-elixir-alloy"}])
```

The adapter brings the SDK from the bundle with it. The quick start is a
script that installs the package with `Mix.install`, so it needs no Mix
project. Run it from the folder that holds `vendor/`.

## 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
[Elixir SDK](https://nevia.cloud/docs/reference/sdk/elixir.md#client).

## 3. Give an agent a computer

Save this as `agent.exs`:

```elixir
Mix.install([{:nevia_alloy, path: "vendor/nevia-sdk-0.1.0/elixir/adapter-elixir-alloy"}])

task = """
Write hello.js that prints process.version, then run it with node.
Answer with its output only.
"""

{:ok, result} =
  Nevia.Alloy.run(task,
    create: [image: "docker.io/library/node:24-slim"],
    provider:
      {Alloy.Provider.Anthropic,
       api_key: System.fetch_env!("ANTHROPIC_API_KEY"), model: "claude-sonnet-5-5"},
    max_turns: 10
  )

IO.puts(result.text)
```

Run it:

```bash
elixir agent.exs
```

The agent writes `/workspace/hello.js` with `write_file`, runs
`node hello.js` with `bash` and answers with the output. The Node.js version
varies:

```text
v24.22.2
```

`Nevia.Alloy.run/2` creates the computer before the agent's first turn and
waits until it is ready.

## 4. Clean up

`Nevia.Alloy.run/2` deletes the computer when the run ends, also when the agent
fails. `nevia ls` confirms the computer is gone.

To keep the computer between runs, pass `keep: true` to `run/2`. The computer is named
`alloy-` and eight hex characters unless you pass `create: [name: "..."]`. A
later run attaches to it with `computer: id_or_computer`, which wakes it if it
is asleep and never deletes it. Delete it yourself with
`Nevia.Computer.delete/2` when you are done.

## How the adapter maps to a computer

`Nevia.Alloy.run/2` is `Alloy.run/2` with a computer. It takes Alloy's options
and adds `client`, `computer`, `create`, `cwd`, `keep` and `include`.

The agent gets `bash`, `read_file`, `write_file` and `list_files`, which work
like Alloy's own tools. `exec_command` runs a foreground command with bounded output
and `expose_port` gives a port on the computer a public HTTPS URL.
`sleep_computer`, `create_database` and `branch_computer` cost money or change
the agent's computer, so they are off until you turn them on with `include`.

To manage the computer yourself, call `Alloy.run/2` and pass
`Nevia.Alloy.tools(include: ...)` as `tools` and
`Nevia.Alloy.context(computer)` as `context`. Each tool finds the computer in
the agent's context, so one tool list serves any number of agents. To run
Alloy's own `Alloy.Tool.Core.Bash` on a computer, set its `bash_executor` in
the context to `Nevia.Alloy.bash_executor(computer)`.

Relative paths resolve against `cwd`, which defaults to `/workspace`. Absolute
paths can leave it. `run/2` creates `cwd` when it is missing.

Commands run in the foreground and keep the last 64 KiB of each output stream.
`bash` joins stdout and stderr, stops a command after its `timeout` (60
seconds by default, 10 minutes at most) and ends truncated output with
`(output truncated)`. `exec_command` takes `timeout_seconds` and sets
`truncated` in its answer. Alloy also cuts a tool result at its
`max_result_chars`.

## Limitations

These add to the SDK's [Limits and workarounds](https://nevia.cloud/docs/reference/sdk/limits.md).

* **No background commands.** A command must end before the tool answers. One
  that backgrounds itself with `&` can hold the call open. The adapter tells
  the agent to redirect long output to a file instead.
* **No edit tool.** The agent rewrites a file whole or edits it with `sed` in
  `bash`.
* **File tools read in pages.** `read_file` returns 2000 lines at a time and
  refuses binary files. `list_files` goes 5 levels deep and shows at most 1000
  entries.
* **A non-root image user may not be able to create `/workspace`.** Pass a
  `cwd` the user can write to.
* **A timeout or cancel may not stop the command.** `bash` returns an error
  with the output so far, but the command can keep running on the computer.
* **`create_database` leaves the database behind.** It stores the connection
  string as a workspace secret. Deleting the computer doesn't delete the
  database.
* **`branch_computer` copies `/data` only.** Running processes and the rest of
  the root filesystem are not in the branch.
