ReferenceSDK

Elixir SDK

Install the Elixir SDK, run a command on a computer and look up the client, computers, exec, files and errors

The Elixir SDK runs computers from Elixir code. Its functions return {:ok, value} or {:error, %Nevia.Error{}}, and most have a bang variant that returns the value or raises. The SDK is in early access, so names and behaviour can change.

The quick start creates a computer, runs a command on it, writes and reads a file and deletes the computer. The reference after it covers the client, computers, exec, files and errors.

Prerequisites

You need:

  • Elixir 1.18 or later.
  • A Nevia workspace where you have the admin or editor role.
  • The nevia CLI, signed in with nevia login. The Quickstart shows how to install it.

Install the SDK

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 SDK from it to the deps in mix.exs, and run mix deps.get:

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

The quick start below is a script that installs the package itself with Mix.install, so it needs no Mix project. Run it from the folder that holds vendor/.

Authenticate

The SDK uses your nevia login session, so a signed-in machine needs nothing more. A server or CI job uses a service-account key instead:

export NEVIA_KEY_FILE="$HOME/path/to/key.json"

Use an automation key file shows how to create one. If you belong to more than one workspace, set NEVIA_WORKSPACE to the workspace ID too.

Create a computer and run a command

Save this as quickstart.exs:

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

client = Nevia.Client.new()

{:ok, computer} = Nevia.Computer.create(client, image: "docker.io/library/debian:12-slim")
IO.puts("Computer: #{computer.id}")

try do
  {:ok, result} = Nevia.Computer.exec(computer, "uname -sr")
  IO.puts("Exit code: #{result.exit_code}, output: #{String.trim(result.stdout)}")

  :ok = Nevia.Files.write(computer, "/tmp/hello.txt", "Hello from Nevia!\n")
  {:ok, text} = Nevia.Files.read(computer, "/tmp/hello.txt")
  IO.write(text)
after
  :ok = Nevia.Computer.delete(computer)
end

Run it:

elixir quickstart.exs

The computer ID and kernel version in the output vary:

Computer: 01d69b2m9d26k14b244xjwmp9mb
Exit code: 0, output: Linux 6.1.191
Hello from Nevia!

Nevia.Computer.create/2 returns once the computer is ready, so the first command runs at once. A command that exits nonzero still returns {:ok, result}. Check result.exit_code or Nevia.ExecResult.success?/1 to see whether it succeeded.

Clean up

The SDK has no scoped block, so delete the computer yourself. The try and after in the quick start delete it when the code inside raises too. nevia ls confirms the computer is gone.

To keep a computer after the program ends, create it without the try and save its ID:

{:ok, computer} = Nevia.Computer.create(client, image: "docker.io/library/debian:12-slim")
IO.puts(computer.id)

A later program reconnects with Nevia.Computer.get(client, saved_id) and calls Nevia.Computer.delete(computer) when it is done.

Reference

In the tables, Computer and Files stand for Nevia.Computer and Nevia.Files.

Client

Nevia.Client.new(opts \\ [])
OptionDescription
:credentialsToken string, {:key_file, path}, {:key, json} or a 1-arity function
:workspaceWorkspace ID (defaults to your only workspace)
:base_urlAPI base URL (defaults to production)
:validateCheck each request before sending it (default true)
:req_optionsExtra Req options for every request

new/1 raises ArgumentError for an option it doesn't know.

The client looks for credentials in this order:

  1. The :credentials option.
  2. NEVIA_TOKEN.
  3. NEVIA_KEY_FILE, or NEVIA_KEY with the key's JSON.
  4. Your nevia login session.

The workspace is the :workspace option, then NEVIA_WORKSPACE, then the only workspace you belong to.

A client is a plain value that holds no connection, so there is nothing to close. Pass it to every call.

FunctionDescription
Nevia.Client.workspace(client){:ok, id} of the selected workspace
Nevia.Client.workspace(client, id)Client scoped to another workspace, with the same credentials

workspace(client, "") raises a Nevia.Error instead of returning a tuple, because it builds a client and makes no call.

Computers

FunctionDescription
Computer.create(client, opts)Create a computer and wait until it is ready
Computer.get(client, id)Get a computer by ID
Computer.find(client, name)First computer whose name is exactly name, or {:ok, nil}
Computer.list(client, filters \\ [])Lazy stream over every computer in the workspace
Computer.new(client, id)Handle to an existing computer, without a request

create/2 takes :image, :name, :env, :ports, :protected and :from_checkpoint. wait: false returns before the computer is ready, and idempotency_key: makes a repeated call create one computer. If the computer fails to become ready, or the wait times out, create/2 returns an error whose resource field holds the computer, so you can delete it. list/2 raises a Nevia.Error when a page can't be read. The other functions have bang variants where the table below notes it.

On a computer:

FunctionDescription
computer.id, Computer.state(computer)Identity and lifecycle state
computer.infoLast record from the API, as a map with string keys
Computer.refresh(computer)Fetch the latest record
Computer.sleep(computer)Sleep the computer and wait until it is sleeping
Computer.wake(computer)Wake the computer and wait until it is ready
Computer.branch(computer, opts \\ [])Create a branch of the computer and return it
Computer.delete(computer, opts \\ [])Delete the computer (succeeds if it is already gone)

create, get, sleep, wake, branch and delete have bang variants. A branch is a new computer, so delete it yourself when you are done. delete/2 waits unless you pass wait: false.

Exec

Nevia.Computer.exec(computer, command, opts \\ [])

exec/3 runs a command to completion and returns {:ok, %Nevia.ExecResult{}}. exec!/3 returns the result or raises.

ArgumentDescription
commandShell string (runs under sh -c), or a list of arguments
:cwdWorking directory on the computer (must exist)
:envExtra environment variables for this command, as a map
:stdinText sent to the command's standard input
:timeout_secondsSeconds before the command is stopped
:transport:api (default) or :direct for direct exec
:max_output_bytesBytes kept from the end of each stream with direct exec

When :timeout_seconds passes, the SDK stops the command's process group and returns the output so far with timed_out: true.

Exec runs through the API by default, which ends a request after about 50 seconds. Direct exec sends the command straight to the computer instead, so it suits longer commands. It keeps the last 64 KiB of each output stream and sets truncated: true when it drops output. See Limits and workarounds.

Nevia.ExecResult fieldDescription
exit_codeExit code of the command
signalSignal that ended the command (0 when none)
stdout, stderrOutput of the command
timed_outWhether :timeout_seconds stopped the command
truncatedWhether direct exec dropped output

Nevia.ExecResult.success?/1 returns true when exit_code and signal are 0 and the command did not time out.

Files

Nevia.Files reads and writes files on a computer. Every path is a path on the computer, and each function takes the computer first.

FunctionDescription
Files.read(computer, path){:ok, binary} with the file content
Files.write(computer, path, data)Write a whole file from iodata, creating parent directories
Files.list(computer, path, opts \\ [])Entries in a directory, sorted by name
Files.remove(computer, path, opts \\ [])Remove a file, or a directory tree with recursive: true

Each has a bang variant. write/3 replaces the file in one step, so a reader never sees it half written. list/3 returns maps with name, type (:file or :directory), size and link, and depth: n descends n levels, with names relative to path. remove/3 takes recursive: true, and force: true ignores a missing path. read/2 on a path that isn't a regular file, and list/3 on a missing directory, return a not_found error. Other failures return command_failed.

Errors

Every SDK and API error is a Nevia.Error, which is also an exception. A command that exits nonzero is a result, not an error.

case Nevia.Computer.get(client, "01d4cnjk3xg90y576w8y6t4gdwm") do
  {:ok, computer} -> computer
  {:error, %{code: "not_found"}} -> IO.puts("No such computer")
  {:error, error} -> raise error
end
FieldDescription
statusHTTP status (0 when the SDK refused the call before sending it)
codeError code, such as "not_found" or "invalid_state"
messageMessage for a person to read
detailsExtra facts about the error, as a map with string keys
opName of the operation that failed
request_idAPI request ID to quote when you report a problem
retry_afterSeconds to wait before retrying, when the API sent one
resourceWhat the call had created before it failed, so you can delete it

New codes can appear, so treat a code you don't recognise as a generic failure.

On this page