spawn

Spawns a new remote Cartesi machine server process, binding it to a specified address. Returns a RemoteCartesiMachine instance that can be used to interact with the remote server. This is the main entry point for starting a new remote machine server from your application.

The server executable (cartesi-jsonrpc-machine) ships with the package, so no emulator installation is needed. Set the CARTESI_JSONRPC_MACHINE environment variable to use a different executable, or see troubleshooting for the full resolution order.

Function Signature

spawn(address?: string, timeout?: number): RemoteCartesiMachine

• address (optional): The address (host:port) to bind the new remote machine server, where host must be 127.0.0.1. Port can be 0 to request an ephemeral port. Defaults to "127.0.0.1:0".
• timeout (optional): Maximum time in milliseconds to wait for the remote server to spawn before giving up and returning an error. Use -1 for no timeout.

Example

import { spawn } from "@cartesi/machine";
 
// Spawn a new remote machine server with default address (127.0.0.1:0)
const remoteMachine = await spawn();
 
// You can now use remoteMachine as a RemoteCartesiMachine
const version = remoteMachine.getServerVersion();
console.log("Remote server version:", version);
 
// Don't forget to shutdown the server when done
remoteMachine.shutdown();