# SDK overview

> The Nevia SDKs for TypeScript, Python, Rust and Elixir, how they authenticate and the concepts they share

> 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

The Nevia SDKs create and run computers and databases from TypeScript, Python,
Rust and Elixir code. Every SDK reaches the same API with the same nouns, so a
program in one language reads like the same program in another. The SDKs are
in early access, so names and behaviour can change.

| Language   | Package      | Page                                                                   |
| ---------- | ------------ | ---------------------------------------------------------------------- |
| TypeScript | `@nevia/sdk` | [TypeScript SDK](https://nevia.cloud/docs/reference/sdk/typescript.md) |
| Python     | `nevia`      | [Python SDK](https://nevia.cloud/docs/reference/sdk/python.md)         |
| Rust       | `nevia`      | [Rust SDK](https://nevia.cloud/docs/reference/sdk/rust.md)             |
| Elixir     | `nevia`      | [Elixir SDK](https://nevia.cloud/docs/reference/sdk/elixir.md)         |

Each SDK page has a quick start and a reference of the client, computers,
exec, files and errors.

Adapters fit a computer into an agent framework's own tools. They are built on
these SDKs and each has its own page: [LangGraph](https://nevia.cloud/docs/agent-frameworks/langgraph.md),
[Pydantic AI](https://nevia.cloud/docs/agent-frameworks/pydantic-ai.md), [Agno](https://nevia.cloud/docs/agent-frameworks/agno.md),
[Mastra](https://nevia.cloud/docs/agent-frameworks/mastra.md), [Eve](https://nevia.cloud/docs/agent-frameworks/eve.md),
[Flue](https://nevia.cloud/docs/agent-frameworks/flue.md), [Rig](https://nevia.cloud/docs/agent-frameworks/rig.md) and
[Alloy](https://nevia.cloud/docs/agent-frameworks/alloy.md).

## Get the SDKs

> **Invited testers only**
>
> The SDKs are in early access for invited testers. If your workspace is
> invited, download them as one bundle with your `nevia login` session. To ask
> for access, see [Request access to Nevia](https://nevia.cloud/docs/get-started/request-access.md).

From your project's root:

```bash
curl -fsSL --oauth2-bearer "$(nevia auth access-token)" https://sdk.nevia.cloud/0.1.0.tar.gz | tar -xz
```

It unpacks to `vendor/nevia-sdk-0.1.0/`, with a folder per language. Each SDK
and adapter page installs from there. To update, download the next version
the same way, with its number in place of `0.1.0` in the URL, and change
`0.1.0` in your install paths.

## Authentication

Every SDK looks for credentials in the same order:

1. A token or key file passed to the client.
2. `NEVIA_TOKEN`.
3. `NEVIA_KEY_FILE`, the path to a service-account key, or `NEVIA_KEY` with
   the key's JSON.
4. Your `nevia login` session.

On your own machine, `nevia login` is enough. A server or CI job uses a
service-account key. [Use an automation key file](https://nevia.cloud/docs/guides/automation-key-file.md)
shows how to create one.

The workspace is the one passed to the client, then `NEVIA_WORKSPACE`, then
the only workspace you belong to. If you belong to more than one, set it.

## Concepts

The SDKs use the same nouns as the API, the CLI and the console.

| Term           | Meaning                                                                                                    |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| Workspace      | The boundary that owns computers, databases, secrets and variables (a user can belong to many)             |
| Computer       | A microVM running your OCI image, with a persistent disk and a stable URL                                  |
| Image          | The OCI image a computer runs                                                                              |
| Database       | A managed Postgres database                                                                                |
| Secret         | A write-only workspace value that a computer's environment can reference                                   |
| Variable       | A plain-text workspace value that a computer's environment can reference and any workspace viewer can read |
| Branch         | A new computer or database copied from an existing one, and the action that creates it                     |
| Checkpoint     | A point-in-time capture of a computer                                                                      |
| Sleep and wake | Stopping a resource while keeping its state, and starting it again                                         |
| Operation      | Asynchronous work a request starts, such as a create or a sleep                                            |

Creating, sleeping, waking and branching start an operation. The SDKs wait for
it to finish before they return, so the resource is ready to use. The
[computer lifecycle states](https://nevia.cloud/docs/reference/computer-lifecycle.md) page lists the
states a computer moves through.

A command that runs on a computer and exits nonzero returns a result with its
exit code. The SDKs raise or return an error only when the API or the SDK
itself refuses a call. Every SDK error carries a `code`, such as `not_found`
or `invalid_state`.
