In this tutorial we will walk you through building a cartesi machine that you publish from scratch. We'll also show what it looks for a user to download the machine and run it. This mirrors a bit For full details on the why and interworkings of Cartesi the tutorial linked above, is immensely helpful. This will focus on using Carti.


npm install -g @createdreamtech/carti
# Probably docker if you want to run the end results

Create a project repo

git clone
cd carti-sample

Setup defaults if you haven't already

carti machine install --global --nobundle --nobuild
carti machine init
cat carti-machine-package.json

Create some custom drives

Here we will be creating a custom flash drive, that will house a calculation

# Pop into docker so we produce these under a consistent environment
docker run -e USER=$(id -u -n) -e UID=$(id -u) -e GID=$(id -g) -e GROUP=$(id -g -n) \
-v $(pwd):/opt/carti -it cartesi/playground /bin/bash
# Our future input flash drive
echo "2^71 + 36^12" > input.raw
# size it up to be on a 4K size interval as required by the cartesi machines
truncate -s 4K input.raw
truncate -s 4K output.raw

Let's start adding drives to our machine

The first thing we need to do once we have the drive is bundle it so we can use it as well as other people

carti bundle -t flashdrive -n calculator-input -v 0.0.1 -d "calculator input" ./input.raw
# outputs bundled: calculator-input as baenrwigmw66wmp2vwjejrmmlw5sbvwpsx3zjtnd7rep4oo6wd3glahtfl4
carti bundle -t flashdrive -n calculator-output -v 0.0.1 -d "calculator output" ./output.raw 
# outputs bundled: calculator-output as baenrwia5pfe7b6dvoys33k7umgsbbixgpympwcfjpqowpaye3bghmrs24m

The result should look like

├── carti-machine-package.json
├── carti_bundles
│   ├── baenrwia5pfe7b6dvoys33k7umgsbbixgpympwcfjpqowpaye3bghmrs24m
│   │   ├── carti-meta.json
│   │   └── output.raw
│   └── baenrwigmw66wmp2vwjejrmmlw5sbvwpsx3zjtnd7rep4oo6wd3glahtfl4
│       ├── carti-meta.json
│       └── input.raw
├── input.raw
└── output.raw

We created a carti_bundles/ directory this functions as a local store for any data that you've bundle up The recommendation is that carti_bundles/ not be uploaded to git.

echo "carti_bundles/" >> .gitignore

What do we have installed?

carti list

We have the following bundles installed:


Let's make these bundles accessible

There are many ways to make a bundle accessible, disk, s3, or other We're going to use other, because it's just a flexible way for us to link data. so let's use github

carti publish uri calculator-input
carti publish uri calculator-output
cat bundles.json

What's package listing file aka. bundles.json ...

So bundles.json provides a way for listing drives and assets that you know about, they can be local to you or not, they are simply bundle metadata that allows a user to download the assets associated with the content-addressed ids. Currently we restrict package listing to git based endpoints, so users can add the listing files and discover packages. Think npm regsitry but distributed across participants.

git add bundles.json 
git commit -m "feat: add listing file to public repo"
git push origin main

Now let's add these drives to a machine!

carti machine add flash --share -m output calculator-output
carti machine add flash -m input calculator-input
cat carti-machine-package.json

You should see this in flash drive entry

    "flash_drive": [
        "cid": "baenrwig2hfjzzeqmozb7sws6tyxmyazvuipjp5hxamtllifsokwh73eucy",
        "start": "0x8000000000000000",
        "label": "root",
        "length": "0x3c00000",
        "shared": false
        "cid": "baenrwigmw66wmp2vwjejrmmlw5sbvwpsx3zjtnd7rep4oo6wd3glahtfl4",
        "start": "0x9000000000000000",
        "label": "input",
        "length": "0x1000",
        "shared": false
        "cid": "baenrwia5pfe7b6dvoys33k7umgsbbixgpympwcfjpqowpaye3bghmrs24m",
        "start": "0xa000000000000000",
        "label": "output",
        "length": "0x1000",
        "shared": false

It's a complete spec: carti-machine-package.json

The machine package.json is a superset of features supported by a lua cartesi machine configuration

When we add drives we are creating a shareable superset of a lua config for running machines. cid's link back to bundles, which are assumed to be stored either locally or globally in carti_bundles/.

Let's create a build dir of all the deps by installing the machine we have so far

carti machine install ./carti-machine-package.json

With install we have created a carti_build/ directory that will serve as mountable or clear demarcation of bundles/drives that are required to run the machine

Let's add a boot command

carti machine add boot "dd status=none if=\$(flashdrive input) | lua -e 'print((string.unpack(\\\"z\\\",\\\"a\\\"))))' | bc | dd status=none of=\$(flashdrive output)"

Build a new cartesi machine config w/ the updates

The following will generate a cartesi machine configuration file as well as easy to use runscript that will allow you to run and store the machine

carti machine build --runscript
cat machine-config.lua

Run the machine

docker run -e USER=$(id -u -n) -e UID=$(id -u) -e GID=$(id -g) -e GROUP=$(id -g -n) \
-v $(pwd):/opt/carti -v $(pwd)/carti_build/bundles:/opt/carti/packages -it cartesi/playground /bin/bash
cd /opt/carti; luapp5.3 run-config.lua machine-config

Check the results

Because our configuration mounts the carti_build directory as the directory for all our drives and stuff, we can see the results of the data output to our output drive via

cat carti_build/bundles/baenrwia5pfe7b6dvoys33k7umgsbbixgpympwcfjpqowpaye3bghmrs24m/output.raw

Let's prep for release

Here we list all the external repo dependencies we might have with machine repo list then we just simply add our own repo to the list and call carti machine repo add to make an entry

carti machine repo add $(echo ",$(carti machine repo list)"

If we're happy and we think it's good let's release the machine and bundles info

echo "carti_build" >> .gitignore
echo "machine-config.lua" >> .gitignore
echo "run-config.lua" >> .gitignore
git add bundles.json 
git add carti-machine-package.json 
git push origin main 

Let's try and do a one shot install and run

cd ..
mkdir test-project
cd test-project
carti machine install --save
# the save command will save the carti-machine-package.json that was fetched 
# so you can then create runscripts etc... with that context. 
# It will overwrite existing carti-machine-package.json .

That about wraps it up

The next step would to see about the larger concepts and details. Concepts