docs(tutorials): added cartesi.toml configuration guide by Nonnyjoe · Pull Request #319 · cartesi/docs

Nonnyjoe · 2026-04-26T20:16:12Z

This PR adds a tutorial for understanding and utilising the cartesi.toml file

jplgarcia · 2026-04-28T15:06:55Z

                "tutorials/cli-account-abstraction-feauture",
-                "tutorials/utilizing-the-cli-test-tokens"
+                "tutorials/utilizing-the-cli-test-tokens",
+                "tutorials/understanding-the-cartesi.toml-configuration-file"


Great guide. I catch myself thinking if a more semantic and less direct name for the tutorial makes sense. "Additional configurations" or something along these lines. Thoughts @lynoferraz @riseandshaheen ?

I always vote for direct and elucidative names.
The most basic form would be "cartesi.toml configuration file".

Very good and guide, we already needed that long ago.

Thinking this from a dev journey pov. cartesi.toml within sidebar titles is too implementation specific. Maybe we call it "Build configuration" or "Project configuration".

Also, the placement seems a little odd to me. Shouldn't it reside under either Development -> Build or, References -> Build/Project Configuration ?

For a reference, check Foundry uses a minimal info within Build section and the rest is under a separate Configuration. @Nonnyjoe

Also, the placement seems a little odd to me. Shouldn't it reside under either Development -> Build or, References -> Build/Project Configuration ?

Having this under the Development section would have been a good idea, but following one of our previous discussions we agreed that the development section would follow the CLI patter in terms of (create, build, run, send) adding this seems to break away from that flow (which i don't mind though).

Having a new section in the sidebar for this similar to what Foundry has is also a good option, asides this i believe the next best location is the Tutorial section.
Also for a tutorial, it's important that users understand what they'll be learning about just based off the title of the tutorial, "Additional configurations" or "cartesi.toml configuration file" may sound too vague.

lynoferraz · 2026-04-28T19:06:50Z

+- **Machine settings**: How the machine boots, how much RAM it has, what program it runs, and how it behaves.
+- **Drives**: The file systems attached to your machine, including your application code and any additional data.
+
+The best part? Almost everything has sensible defaults. You can start with a nearly empty file and only add configuration as your needs grow.


Maybe we should point that the cartesi.toml is used only when building the application (cartesi build/shell), and it is not required. Also, we should note that it will consider some defaults if not provided, like:

it looks for a config.toml file unless you use: -c/--config

if not provided, it will try to build the app using a Dockerfile in the same directory. The Dockerfile itself has several default considerations, such as the entrypoint will be the file's CMD, it will set all the ENVs...
The defaults will be described down the topics, but maybe it is better just to point that it is not necessary. Also, note that the templates don't necessarily have a cartesi.toml file, which may cause confusion.

lynoferraz · 2026-04-28T19:08:28Z

+Here is what the defaults look like behind the scenes:
+
+```toml
+sdk = "cartesi/sdk:0.12.0"


This is likely to change on each version. I wonder what would the best way to represent this here

sdk = "cartesi/sdk:latest"

or

sdk = "cartesi/sdk:<version>"

Yeahh... <version> makes more sense

lynoferraz · 2026-04-28T19:13:24Z

+The format is `cartesi/sdk:<version>`. When you omit this field entirely, the CLI uses its own built in default version.
+
+**When to change this:** When there's a new SDK version and you want to adopt it, or when you need to stay on a specific version for compatibility.
+


Should we note that this is actually the docker image version containing the fallback programs and node?
It is somewhat tied to the cartesi cli version, but not necessarily.

lynoferraz · 2026-04-28T19:19:40Z

+
+**`ram_length`** sets how much RAM your Cartesi Machine has. The default is `128Mi` (128 mebibytes). You can use human readable sizes like `"64Mi"`, `"256Mi"`, or `"1Gi"`.
+
+How much RAM do you need? It depends on your application. A lightweight app that processes small inputs might be fine with 64Mi. A machine learning model or an application that handles large data structures might need 256Mi or more. Start with the default and increase it if your application runs out of memory.


I don't like the question here. It is a change of tone. I prefer a more direct sentence like the other topics. Also, the advice to increase the memory if the application runs out of memory is not good. He would have to design a stress test or do a long running test to detect that.
Maybe we should just drop this comment

lynoferraz · 2026-04-28T19:23:40Z

+
+The `max_mcycle` field sets the maximum number of machine cycles the Cartesi Machine is allowed to execute. This acts as a computational budget. Once the machine reaches this limit, it stops.
+
+A value of `0` means no limit, and the machine runs until your application exits on its own. Setting a specific number is useful when you want to guarantee that computation stays within a certain bound, which can be important for on chain verification where predictable execution costs matter.


Not true. 0 is zero. It is useful to store an image from flash drives before it reaches the manual yield cause by finish. Also, note that this is riscv64 machine cycles
From the cartesi-machine cli:
--max-mcycle=
stop at a given mcycle (default: 2305843009213693952).

lynoferraz · 2026-04-29T02:08:38Z

+**`format`** determines the file system type. Choose `"ext2"` when your application needs to read and write to the drive, or `"sqfs"` for a compressed read only image. Not all builders support this option (the empty builder uses `"ext2"` or `"raw"`, and the none builder infers the format from the file extension).
+
+**`extra_size`** adds free space beyond the actual content size. Useful for drives where you expect your application to write additional files at runtime. Specified as a string like `"100Mb"` or `"50Mi"`.
+


Really common options are builder, mount, shared, and user

lynoferraz · 2026-04-29T02:13:45Z

+ram_length = "128Mi"
+use_docker_env = true
+use_docker_workdir = true
+no_rollup = false


You could use the Dockerfile ENTRYPOINT and CMD to define the entrypoint, but I feel it is missing here in the .toml

lynoferraz · 2026-04-29T02:15:02Z

+
+[machine]
+# Run the Python application when the machine starts
+entrypoint = "/opt/app/main.py"


We should maintain a consistency of the image in the whole file.
Is it a python app with a data flash drive.
I don't like that there are different entrypoints. we could just stick to
entrypoint = "/usr/local/bin/python3 /mnt/app/main.py"

lynoferraz · 2026-04-29T02:17:44Z

+| `filename`              | `[drives.*]` | String           | —                      | Path to tar or existing image file                              |
+| `mount`                 | `[drives.*]` | String           | `/mnt/<name>`          | Where the drive is mounted in the machine                       |
+
+## Common Patterns and Tips


It feels unnecessary this section unless we have similar in all other doc. It feels more like a blog conclusion.

You mean the ## Common Patterns and Tips section?
If yes then we can take that out actually, being a tutorial i wanted that to serve as a conclusion so it's not heavily needed

lynoferraz · 2026-04-29T02:17:59Z

+
+**Pin your SDK version.** Always set the `sdk` field explicitly in your `cartesi.toml`. This ensures that your builds are reproducible and that a new SDK release does not unexpectedly change your machine's behavior.
+
+**Keep `no_rollup = false` for production.** Rollup mode is what connects your Cartesi Machine to the blockchain. Only disable it during development or for standalone tools that do not need blockchain interaction.


Remove this no_rollup

docs(tutorials): added cartesi.toml configuration guide

d33ae29

Nonnyjoe requested review from jplgarcia, lynoferraz and riseandshaheen April 26, 2026 20:16

jplgarcia reviewed Apr 28, 2026

View reviewed changes

lynoferraz reviewed Apr 29, 2026

View reviewed changes

		The format is `cartesi/sdk:<version>`. When you omit this field entirely, the CLI uses its own built in default version.

		When to change this: When there's a new SDK version and you want to adopt it, or when you need to stay on a specific version for compatibility.


		`ram_length` sets how much RAM your Cartesi Machine has. The default is `128Mi` (128 mebibytes). You can use human readable sizes like `"64Mi"`, `"256Mi"`, or `"1Gi"`.

		How much RAM do you need? It depends on your application. A lightweight app that processes small inputs might be fine with 64Mi. A machine learning model or an application that handles large data structures might need 256Mi or more. Start with the default and increase it if your application runs out of memory.


		The `max_mcycle` field sets the maximum number of machine cycles the Cartesi Machine is allowed to execute. This acts as a computational budget. Once the machine reaches this limit, it stops.

		A value of `0` means no limit, and the machine runs until your application exits on its own. Setting a specific number is useful when you want to guarantee that computation stays within a certain bound, which can be important for on chain verification where predictable execution costs matter.

		`format` determines the file system type. Choose `"ext2"` when your application needs to read and write to the drive, or `"sqfs"` for a compressed read only image. Not all builders support this option (the empty builder uses `"ext2"` or `"raw"`, and the none builder infers the format from the file extension).

		`extra_size` adds free space beyond the actual content size. Useful for drives where you expect your application to write additional files at runtime. Specified as a string like `"100Mb"` or `"50Mi"`.


		Pin your SDK version. Always set the `sdk` field explicitly in your `cartesi.toml`. This ensures that your builds are reproducible and that a new SDK release does not unexpectedly change your machine's behavior.

		Keep `no_rollup = false` for production. Rollup mode is what connects your Cartesi Machine to the blockchain. Only disable it during development or for standalone tools that do not need blockchain interaction.

Conversation

Nonnyjoe commented Apr 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lynoferraz Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Nonnyjoe Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lynoferraz Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lynoferraz Apr 28, 2026 •

edited

Loading

Nonnyjoe Apr 29, 2026 •

edited

Loading

lynoferraz Apr 29, 2026 •

edited

Loading