Agent frameworks

Alloy

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 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 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"}
  ]
end

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

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

v24.22.2

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

On this page