# Cartesi Machine + Node.js

The [Cartesi machine emulator](https://github.com/cartesi/machine-emulator) is a C++ library with a C API. This package binds it to Node.js as a native N-API addon linked against the static libraries of the official emulator distribution (currently [0.20.0](https://github.com/cartesi/machine-emulator/releases/tag/v0.20.0)). Prebuilt platform packages bundle everything — including the `cartesi-jsonrpc-machine` server executable used by [spawn](/cm/api/spawn) — so **no emulator installation is required** for the supported platforms.

It provides a fully typed and ergonomic TypeScript API for the Cartesi Machine C API and the Cartesi Machine JSON-RPC API, which allows you to create, manage, and interact with local or remote Cartesi machines from TypeScript/JavaScript applications.

## Features

* **Self-contained**: prebuilt binaries per platform, no emulator installation needed;
* **Comprehensive**: Complete API, for any use case, including [local](/cm/local) and [remote](/cm/remote) machines;
* **Full Type Safety**: Complete TypeScript definitions for all C API functions and types;
* **High-Level Wrapper**: Easy-to-use [CartesiMachine](/cm/api/cartesi-machine) and [RemoteCartesiMachine](/cm/api/remote-cartesi-machine) interfaces that wraps the C API;
* **Error Handling**: Easy [error handling](/cm/error-handling) with detailed error messages.

## Installation

:::code-group

```bash [pnpm]
pnpm add @deroll/cm
```

```bash [npm]
npm install @deroll/cm
```

```bash [yarn]
yarn add @deroll/cm
```

:::

On Linux (x64, arm64) and macOS (x64, arm64) this installs a prebuilt platform package (`@deroll/cm-<platform>-<arch>`) containing the native addon and the JSON-RPC server executable — no compiler needed.

On other platforms the install script compiles the addon from source, which requires a C++ compiler and an installed cartesi-machine emulator distribution (the `machine-emulator` `.deb` from the [official releases](https://github.com/cartesi/machine-emulator/releases) on Debian/Ubuntu, or `brew install cartesi/tap/cartesi-machine-emulator` on macOS).

Check the [troubleshooting](./troubleshooting) section in case of problems.