# Local Machine

A local Cartesi machine is the one that runs in-process.
It can be created by using the following utility methods:

```ts
// create a new machine from a configuration
function create(config: MachineConfig, runtimeConfig?: MachineRuntimeConfig): CartesiMachine;

// load machine snapshot saved to a directory
function load(dir: string, runtimeConfig?: MachineRuntimeConfig): CartesiMachine;

// create an empty machine, which later must be created or loaded
function empty(): CartesiMachine;
```

The following sections will show step by step how to create and run a very simple local machine.
It uses the Linux kernel [linux.bin](https://github.com/cartesi/machine-linux-image/releases/download/v0.20.0/linux-6.5.13-ctsi-1-v0.20.0.bin) and a pre-built [rootfs.ext2](https://github.com/cartesi/machine-guest-tools/releases/download/v0.17.1/rootfs-tools.ext2) file as the root filesystem.

## Creating a machine

The machine defined below uses `128Mb` of RAM, the Linux kernel file, and a single filesystem as root.
The entrypoint is a simple execution of the classic "Hello world!" message.

```ts twoslash filename="create-hello-world.ts"
import { create } from "@deroll/cm";

// create a basic machine that prints Hello world
const machine = create({
    ram: {
        length: 0x8000000, // 128MB of RAM
        image_filename: "linux.bin",
    },
    flash_drive: [
        {
            image_filename: "rootfs.ext2",
        },
    ],
    dtb: {
        entrypoint: "echo Hello world!", // simply prints to the console
    },
});
```

## Running a machine

The next step of this simple example is to run the machine until it yields or halts.

```ts twoslash filename="run-hello-world.ts"
// @noErrors
import { create } from "@deroll/cm"; // [!code --] // [!code focus]
import { BreakReason, create } from "@deroll/cm"; // [!code ++] // [!code focus]

// create a basic machine that prints Hello world
const machine = create({
    ram: {
        length: 0x8000000, // 128MB of RAM
        image_filename: "linux.bin",
    },
    flash_drive: [
        {
            image_filename: "rootfs.ext2",
        },
    ],
    dtb: {
        entrypoint: "echo Hello world!", // simply prints to the console
    },
});

// run the machine until it yields or halts (default is MAX_MCYCLE) // [!code focus]
const reason = machine.run(); // [!code focus]
switch (reason) { // [!code focus]
    case BreakReason.YieldedManually: // [!code focus]
        console.log("Machine yielded manually"); // [!code focus]
        break; // [!code focus]
    case BreakReason.Halted: // [!code focus]
        console.log("Machine halted"); // [!code focus]
        break; // [!code focus]
    default: // [!code focus]
        console.log(`Machine halted: ${reason}`); // [!code focus]
} // [!code focus]
console.log(reason); // [!code focus]
```

## Calculating the hash

The machine hash can be calculated using the `getRootHash()` method of the machine, like below:

```ts twoslash
import { BreakReason, create } from "@deroll/cm";

// create a basic machine that print Hello world
const machine = create({
    ram: {
        length: 0x8000000, // 128MB of RAM
        image_filename: "linux.bin",
    },
    flash_drive: [
        {
            image_filename: "rootfs.ext2",
        },
    ],
    dtb: {
        entrypoint: "echo Hello world!",
    },
});

// run the machine until it yields or halts (default is MAX_MCYCLE)
const reason = machine.run();
switch (reason) {
    case BreakReason.YieldedManually:
        console.log("Machine yielded manually");
        break;
    case BreakReason.Halted:
        console.log("Machine halted");
        break;
    default:
        console.log(`Machine halted: ${reason}`);
}
console.log(reason);

// calculate machine root hash // [!code focus]
const hash = machine.getRootHash(); // [!code focus]
console.log(hash); // [!code focus]
```

The complete [CartesiMachine](/cm/api/cartesi-machine) API is available in the API section.

## Memory Management

The API automatically handles memory management for machine objects. When a `machine` instance is garbage collected by Node.js, its underlying C resources are automatically cleaned up.

However, you can also explicitly free the resources held by a machine object by calling its `destroy()` method. This is useful if you want to immediately release native resources without waiting for garbage collection.

## Thread Safety

The C API is not thread-safe.
All operations should be performed from the same thread that created the machine object.

:::warning
Double check this information
:::