# Elixir SDK

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

> 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/reference/sdk/elixir

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](#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](https://nevia.cloud/docs/get-started/quickstart.md) shows how to install it.

## 1. Install the SDK

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

**mix.exs**

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

**Mix.install**

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

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

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

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

[Use an automation key file](https://nevia.cloud/docs/guides/automation-key-file.md) shows how to
create one. If you belong to more than one workspace, set `NEVIA_WORKSPACE` to
the workspace ID too.

## 3. Create a computer and run a command

Save this as `quickstart.exs`:

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

```bash
elixir quickstart.exs
```

The computer ID and kernel version in the output vary:

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

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

```elixir
{: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

```elixir
Nevia.Client.new(opts \\ [])
```

| Option         | Description                                                             |
| -------------- | ----------------------------------------------------------------------- |
| `:credentials` | Token string, `{:key_file, path}`, `{:key, json}` or a 1-arity function |
| `:workspace`   | Workspace ID (defaults to your only workspace)                          |
| `:base_url`    | API base URL (defaults to production)                                   |
| `:validate`    | Check each request before sending it (default `true`)                   |
| `:req_options` | Extra `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.

| Function                             | Description                                                   |
| ------------------------------------ | ------------------------------------------------------------- |
| `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

| Function                               | Description                                                  |
| -------------------------------------- | ------------------------------------------------------------ |
| `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:

| Function                                  | Description                                                                              |
| ----------------------------------------- | ---------------------------------------------------------------------------------------- |
| `computer.id`, `Computer.state(computer)` | Identity and [lifecycle state](https://nevia.cloud/docs/reference/computer-lifecycle.md) |
| `computer.info`                           | Last 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

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

| Argument            | Description                                               |
| ------------------- | --------------------------------------------------------- |
| `command`           | Shell string (runs under `sh -c`), or a list of arguments |
| `:cwd`              | Working directory on the computer (must exist)            |
| `:env`              | Extra environment variables for this command, as a map    |
| `:stdin`            | Text sent to the command's standard input                 |
| `:timeout_seconds`  | Seconds before the command is stopped                     |
| `:transport`        | `:api` (default) or `:direct` for direct exec             |
| `:max_output_bytes` | Bytes 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](https://nevia.cloud/docs/reference/sdk/limits.md).

| `Nevia.ExecResult` field | Description                                    |
| ------------------------ | ---------------------------------------------- |
| `exit_code`              | Exit code of the command                       |
| `signal`                 | Signal that ended the command (0 when none)    |
| `stdout`, `stderr`       | Output of the command                          |
| `timed_out`              | Whether `:timeout_seconds` stopped the command |
| `truncated`              | Whether 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.

| Function                                   | Description                                                 |
| ------------------------------------------ | ----------------------------------------------------------- |
| `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.

```elixir
case Nevia.Computer.get(client, "01d4cnjk3xg90y576w8y6t4gdwm") do
  {:ok, computer} -> computer
  {:error, %{code: "not_found"}} -> IO.puts("No such computer")
  {:error, error} -> raise error
end
```

| Field         | Description                                                      |
| ------------- | ---------------------------------------------------------------- |
| `status`      | HTTP status (0 when the SDK refused the call before sending it)  |
| `code`        | Error code, such as `"not_found"` or `"invalid_state"`           |
| `message`     | Message for a person to read                                     |
| `details`     | Extra facts about the error, as a map with string keys           |
| `op`          | Name of the operation that failed                                |
| `request_id`  | API request ID to quote when you report a problem                |
| `retry_after` | Seconds to wait before retrying, when the API sent one           |
| `resource`    | What 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.
