Build from source

For a first run, use a release download. Build from source when you want the current checkout or need to change Yano X. For released host versions, the build resolves the matching Yano distribution automatically. Unpublished host versions require exact local or staged inputs.

Two different build tracks

This page is the user track: build the distribution, run it, move on. If you are changing Yano X itself — or changing Yano and Yano X together — read Developing Yano X instead. Mixing the two is the most common source of confusion, because the contributor track needs Maven Local and several -P flags that released builds do not.

Prerequisites

Requirement	Notes
Java 25	Required. Check with java -version.
Git	To clone the repository.
~2 GB disk	The base Yano JVM ZIP alone is around 280 MB, plus Gradle caches.
bash, curl, jq, python3, openssl	Used by the cluster launcher and the tutorials.
Docker Desktop	Only for the full evidence/connector demo.

Gradle itself does not need to be installed — the repository ships a wrapper.

Build

git clone https://github.com/bloxbean/yano-x.git
cd yano-x
./gradlew clean build -PskipSigning=true

For a checkout pinned to a released host version, no -PyanoVersion, -PuseMavenLocal, or -PyanoJvmDist override is needed. If the version table below says Local build required, first publish that exact Yano version and build its ordinary JVM ZIP, following Developing Yano X. Then supply the matching inputs explicitly:

./gradlew clean build -PskipSigning=true \
  -PyanoVersion=<exact-locally-published-yano-version> \
  -PyanoJvmDist=/absolute/path/to/yano-<same-version>.zip \
  -PuseMavenLocal=true

Host version and distribution inputs

gradle.properties pins the exact Yano host line Yano X is built against:

Value	Current
Yano X version	0.1.0-pre4-SNAPSHOT
Yano host version	0.1.0-pre18
Maven group	org.yanoproject.x
Java	25
Base Yano JVM ZIP	yano-0.1.0-pre18.zip

When yanoVersion identifies a published release, the distribution tasks resolve and cache the matching ordinary Yano JVM ZIP from the corresponding bloxbean/yano GitHub release automatically. The URL convention is:

https://github.com/bloxbean/yano/releases/download/v<version>/yano-<version>.zip

For a published release, -PyanoJvmDist optionally overrides that asset. For snapshot or locally staged builds, it is required: the Maven artifacts and ZIP must carry the same exact build identity. A snapshot version is not a downloadable GitHub release.

-PskipSigning=true skips artifact signing, which is only relevant when publishing.

What you get

One reproducible archive, distribution/jvm/build/distributions/yano-x-jvm-<version>.zip: the standard Yano JVM distribution, the default and optional Yano X plugin layout, the command-line and deployment tools, App-Chain Studio, the local showcase, and identity manifests for both projects. This is what you run.

It includes the repository LICENSE and a normalized CycloneDX 1.6 SBOM under sbom/, and preserves the host’s license as LICENSE.yano and its SBOM as sbom/yano.cdx.json.

Inside the JVM archive, everything sits under a single yano-x-jvm-<version>/ directory (a -SNAPSHOT suffix is stripped from that directory name, so a 0.1.0-SNAPSHOT build unpacks to yano-x-jvm-0.1.0/):

yano-x-jvm-<version>/
├── yano.sh                       # the public CLI and node launcher
├── yano.jar
├── config/                       # chain definitions and network genesis
│   └── schema/                   # blueprint, catalog, and lock schemas
├── plugins/                      # the default, conflict-free bundle selection
├── tools/
│   ├── lib/                      # jars shared by the Yano X command-line tools
│   ├── yano-plugins/             # plugin catalog validator (from the Yano host)
│   ├── yano-appchain/            # the offline engine behind `yano.sh appchain`
│   └── yano-deploy/ …            # deployment CLI and product CLIs
├── studio/                       # App-Chain Studio, the blueprint builder
├── skills/configure-yano-appchain/   # the first-party AI agent skill
├── appchain-cluster/             # the single-host cluster launcher scripts
├── examples/
│   ├── showcase/                 # the local multi-node showcase
│   └── evidence/                 # the evidence demo harness and runner
├── docs/                         # the repository documentation set
├── sbom/
└── LICENSE, LICENSE.yano

Two of those are easy to miss: studio/ is the same blueprint builder hosted on this site, and skills/configure-yano-appchain/ is a version-matched agent skill — see Using Yano X with AI agents.

Unpack and check

unzip distribution/jvm/build/distributions/yano-x-jvm-*.zip -d ~/yano-x
cd ~/yano-x/yano-x-jvm-*

./yano.sh appchain help
./yano.sh appchain recipes
./yano.sh appchain capabilities

recipes and capabilities print what this exact build can do. They are the authoritative answer for your version — the recipe catalog and capability catalog on this site are generated from the same source files, but the binary in your hands always wins.

To run one local member on a private devnet, use the bundled cluster launcher:

./yano.sh appchain cluster start 1
./yano.sh appchain cluster status

cluster stop keeps the data and cluster clean deletes it. The first tutorial runs three members the same way, and the local showcase quickstart runs from examples/showcase/ inside the same archive.

The default plugin selection

plugins/ is an activatable selection, not an indiscriminate copy. All runtime bundles are published and versioned independently; the default distribution activates every one that can coexist.

Building against a different Yano version

If you need a Yano line other than the pinned one — a newer pre-release, a commit snapshot, or a staged build — pass it explicitly:

# A different released Yano version: the ZIP still resolves from its release.
./gradlew clean build -PyanoVersion=<released-yano-version> -PskipSigning=true

# A Yano commit snapshot, e.g. 0.1.0-pre18-3c73341-SNAPSHOT: the jars resolve
# from repo.bloxbean.org/maven/snapshots and the ZIP from the matching
# repo.bloxbean.org/dist/snapshots/yano/<version>/ (version without -SNAPSHOT).
./gradlew clean build -PyanoVersion=<yano-snapshot-version> -PskipSigning=true

# A staged Maven repository plus an exact ZIP.
./gradlew clean build \
  -PyanoVersion=<staged-yano-version> \
  -PyanoRepository=/absolute/path/to/yano-staging \
  -PyanoJvmDist=/absolute/path/to/yano-<build-identity>.zip \
  -PskipSigning=true

The Maven version and the JVM ZIP identity must match exactly. verifyYanoInputs rejects a base ZIP whose root directory, JAR implementation version, or distribution manifest disagrees with yanoVersion, and a snapshot ZIP whose SHA-256 differs from its published manifest.json. Snapshots never fall back to a GitHub release asset, and locally built or staged versions must supply yanoJvmDist.

Troubleshooting

Symptom	Cause and fix
Unsupported class file major version or a Java-version error	Yano X requires Java 25. Point JAVA_HOME at a 25 JDK.
The build tries to reach Maven Local and fails	mavenLocal() is disabled unless -PuseMavenLocal=true. That flag belongs to the contributor track; you should not need it.
A missing release asset for yanoVersion	You are on a staged or locally built Yano version. Supply -PyanoJvmDist with the exact matching ZIP.
Could not find org.yanoproject-snapshot:yano	Yano publishes snapshot jars and the snapshot ZIP in separate workflows; the ZIP for that commit is not published yet. Wait for it, or pick a commit listed in repo.bloxbean.org/dist/snapshots/yano/latest.json.
verifyJvmOnlyBuild fails	Something introduced a native-image build or distribution task. Yano X is JVM-only by decision.
A native distribution is rejected by appchain doctor	Yano X plugins target the JVM host. Use the yano-x-jvm archive.

For the full matrix of build tasks and verification gates, see Build and test and Build distributions.