ReferenceSDK

TypeScript SDK

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

The TypeScript SDK runs computers from Node.js code. One Nevia client holds the credentials and the workspace, and every method returns a promise. 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:

  • Node.js 22.23.4 or later on 22, or 24.22.1 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 install the SDK from it:

npm init -y
npm pkg set type=module
npm install ./vendor/nevia-sdk-0.1.0/typescript/nevia-sdk-0.1.0.tgz
npm install --save-dev tsx

The quick start runs with tsx. type=module lets the example use top-level await.

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

import { Nevia } from '@nevia/sdk'

const nevia = new Nevia()
const computer = await nevia.computers.create({ image: 'docker.io/library/node:24-slim' })

try {
  console.log(`Computer: ${computer.id}`)

  const result = await computer.exec('node --version')
  console.log(`Exit code: ${result.exitCode}, output: ${result.stdout.trim()}`)

  await computer.files.write('/tmp/hello.txt', 'Hello from Nevia!\n')
  process.stdout.write(await computer.files.readText('/tmp/hello.txt'))
} finally {
  await computer.delete()
}

Run it:

npx tsx quickstart.ts

The computer ID and Node.js version in the output vary:

Computer: 01d69b2m9d26k14b244xjwmp9mb
Exit code: 0, output: v24.22.2
Hello from Nevia!

computers.create() returns once the computer is ready, so the first command runs at once. A command that exits nonzero still returns a result. Check result.exitCode and result.signal to see whether it succeeded.

Clean up

The finally block deletes the computer when the code above it finishes, also when that code throws. nevia ls confirms the computer is gone.

To keep a computer after the program ends, skip the delete() call and save its ID:

const computer = await nevia.computers.create({ image: 'docker.io/library/node:24-slim' })
console.log(computer.id)

A later program reconnects with nevia.computer(savedId) and calls computer.delete() when it is done.

Reference

Client

new Nevia(options?: {
  baseUrl?: string
  credentials?: string | (() => Promise<string>) | { keyFile: string } | { key: string | object }
  workspace?: string
  fetch?: typeof fetch
  validate?: boolean
})
OptionDescription
credentialsToken, token provider, { keyFile } path or { key } JSON
workspaceWorkspace ID (defaults to your only workspace)
baseUrlAPI base URL (defaults to production)
fetchfetch implementation for every request
validateCheck each request before sending it (default true)

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.

The client holds no connections, so there is nothing to close. Computers keep running until you delete them.

MemberDescription
nevia.computersCreate, get, find and list computers
nevia.computer(id)Handle to an existing computer, without a request
nevia.workspace()Promise of the selected workspace ID
nevia.workspace(id)Client scoped to another workspace, on the same connections

Computers

MethodDescription
computers.create(options)Create a computer and wait until it is ready
computers.get(id)Get a computer by ID
computers.find(name)First computer whose name is exactly name, or null
computers.list(filter?)Async iterator over every computer in the workspace

computers.list() is an async generator, so read it with for await (const computer of nevia.computers.list()).

create() optionDescription
imageImage to run, such as docker.io/library/node:24-slim
nameName of the computer (generated when omitted)
envEnvironment variables stored on the computer
protectedRefuse deletion until unprotected
waitWait until the computer is ready (default true)
signalAbortSignal that cancels the call

create() returns the computer. If the computer fails to become ready, or the wait times out or is aborted, create() throws a NeviaError and leaves the computer behind. The error's resource property holds it, so call error.resource.delete() to clean up.

On a computer:

MemberDescription
id, stateID and lifecycle state
infoFull record as a ComputerInfo, with name among its fields
filesFile methods, listed under Files
refresh()Fetch the latest record
sleep()Sleep the computer and wait until it is sleeping
wake()Wake the computer and wait until it is ready
branch(options?)Create a branch of the computer and return it
delete(options?)Delete the computer (succeeds if it is already gone)

branch() takes name, wait and signal. A branch is a new computer, and the SDK never deletes it for you, so call delete() on the branch when you are done.

Exec

computer.exec(command: string | readonly string[], options?: ExecOptions): Promise<ExecResult>

exec() runs a command to completion and returns an ExecResult.

ArgumentDescription
commandShell string (runs under sh -c), or an array of arguments
cwdWorking directory on the computer
envExtra environment variables for this command
stdinText sent to the command's standard input
timeoutSecondsSeconds before the command is stopped
transport'api' (default) or 'direct' for direct exec
maxOutputBytesBytes kept from the end of each stream with direct exec
signalAbortSignal that cancels the call

When timeoutSeconds passes, the computer stops the command's process group and exec() returns the output so far with timedOut: 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.

ExecResult fieldDescription
exitCodeExit code of the command
signalSignal that ended the command (0 when none)
stdout, stderrOutput of the command
timedOutWhether timeoutSeconds stopped the command
truncatedWhether direct exec dropped output

A command succeeded when exitCode and signal are 0 and timedOut is false.

Files

computer.files reads and writes files on the computer. Every path is a path on the computer. Each method takes an optional last argument with a signal.

MethodDescription
read(path)File content as Uint8Array, or null when there is no file
readText(path)File content as a UTF-8 string, or null when there is no file
write(path, data)Write a whole file from string or Uint8Array, creating parent directories
remove(path, options?)Remove a file, or a directory tree with recursive

write() replaces the file in one step, so a reader never sees it half written. remove() takes recursive and force, and throws a NeviaError with the code command_failed when the removal fails. readText() throws when the file is not valid UTF-8.

Errors

The SDK throws every SDK and API error as a NeviaError. A command that exits nonzero is a result, not an error.

import { Nevia, isNeviaError } from '@nevia/sdk'

const nevia = new Nevia()

try {
  await nevia.computers.get('01d4cnjk3xg90y576w8y6t4gdwm')
} catch (error) {
  if (!isNeviaError(error, 'not_found')) throw error
  console.log('No such computer')
}
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 an object
opName of the API operation that failed
requestIdAPI request ID to quote when you report a problem (null if none)
retryAfterSeconds to wait before retrying (null if the API sent none)

New codes can appear, so treat a code you don't recognise as a generic failure. isNeviaError(error, code?) checks the type and, when you pass one, the code in one call.

On this page