Give an Alloy agent a Nevia computer as its tools, so its shell and file tools run on the computer
The Alloy adapter gives an 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 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, so Alloy's docs 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
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 from it to the deps in mix.exs, and run mix deps.get:
defp deps do
[
{:nevia_alloy, path: "vendor/nevia-sdk-0.1.0/elixir/adapter-elixir-alloy"}
]
endThe 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/.
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
Elixir SDK.
Give an agent a computer
Save this as agent.exs:
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:
elixir agent.exsThe agent writes /workspace/hello.js with write_file, runs
node hello.js with bash and answers with the output. The Node.js version
varies:
v24.22.2Nevia.Alloy.run/2 creates the computer before the agent's first turn and
waits until it is ready.
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.
- 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
sedinbash. - File tools read in pages.
read_filereturns 2000 lines at a time and refuses binary files.list_filesgoes 5 levels deep and shows at most 1000 entries. - A non-root image user may not be able to create
/workspace. Pass acwdthe user can write to. - A timeout or cancel may not stop the command.
bashreturns an error with the output so far, but the command can keep running on the computer. create_databaseleaves the database behind. It stores the connection string as a workspace secret. Deleting the computer doesn't delete the database.branch_computercopies/dataonly. Running processes and the rest of the root filesystem are not in the branch.