Build and boot your code on every chip — in CI.

Overview

Regular CI tells you your code compiled. cilicon tells you it runs on the chip. Each target carries its own toolchain image and its own way of proving the artifact actually runs — fanned out across Modal cloud containers, owning zero hardware.

There are two ways to run it — as a GitHub Action (the primary path) and as a local CLI. Both are the same engine.

# add cilicon as a step in your existing CI
- uses: RyanRana/cilicon@v1
  env:
    MODAL_TOKEN_ID:     ${{ secrets.MODAL_TOKEN_ID }}
    MODAL_TOKEN_SECRET: ${{ secrets.MODAL_TOKEN_SECRET }}

Authenticate Modal

cilicon runs every build and boot in a Modal sandbox, so you need a (free) Modal account and a local token. This is a one-time step.

$ modal token new          # opens a browser, writes a local token

Your first run

With a cilicon.yml in place, build and boot the whole matrix in parallel. A bare cilicon with no subcommand is equivalent to cilicon run.

$ cilicon run

You'll see a live table as each target builds and boots in its own container:

  cilicon · 4 target(s) · fanned across Modal cloud containers

  ┌──────────────────────────────┬────────────────┬─────────────────────────────────┐
  │ TARGET                       │ BUILD          │ ON-TARGET CHECK                 │
  ├──────────────────────────────┼────────────────┼─────────────────────────────────┤
  │ jetson-perception/linux-arm  │ ✓    0s        │ ✓ loads + runs ('perception: e… │
  │ stm32h7/cortex-m             │ ✓    0s        │ ✓ boots, reaches main ('BOOT O… │
  │ esp32/freertos               │ ✓ 1m57s        │ ✓ boots, reaches main ('Hello … │
  │ pi5-loadtest/linux-arm       │ ✓    0s        │ ✗ crash (SIGSEGV), caught pre-… │
  └──────────────────────────────┴────────────────┴─────────────────────────────────┘
  3 / 4 passed · wall-clock 2m50s · vs ~4m20s sequential

The process exits 0 only if every target passed, 1 if any failed, and 2 if --target matched nothing. Failing targets print an expanded block with the failing step and the tail of its output.

CLI commands

The global flag -c / --config sets the config path (default cilicon.yml) and goes before the subcommand, e.g. cilicon -c examples/advanced.yml targets.

cilicon run flags

# produce a CI report and pull binaries back
$ cilicon run --junit out.xml --artifacts ./out
$ cilicon run -t stm32                       # just one target

GitHub Action setup

This is the primary way to use cilicon: a step inside your existing CI that builds and boots every chip in cilicon.yml and publishes a normal PR check.

1. Add a cilicon.yml

Define one target per chip you ship to. Minimal example:

targets:
  - id: firmware/cortex-m
    board: cortex-m            # debian + arm-none-eabi + qemu-system-arm
    build: >
      arm-none-eabi-gcc -mcpu=cortex-m3 -mthumb -nostartfiles
      -nostdlib -ffreestanding -T src/cortex-m.ld
      src/firmware.c -o build/firmware.elf
    artifact: build/firmware.elf
    expect: "BOOT OK"            # the on-target proof string

2. Add the workflow

Create .github/workflows/cilicon.yml in your repo:

name: cilicon
on:
  push: { branches: [main] }
  pull_request:
jobs:
  build-and-boot:
    name: build + boot      # → check: "cilicon / build + boot"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - name: cilicon
        uses: RyanRana/cilicon@v1
        with: { config: cilicon.yml }
        env:
          MODAL_TOKEN_ID:     ${{ secrets.MODAL_TOKEN_ID }}
          MODAL_TOKEN_SECRET: ${{ secrets.MODAL_TOKEN_SECRET }}

3. Set the two Modal secrets

Run modal token new locally (it prints a token id and secret), then add them as repository secrets under Settings → Secrets and variables → Actions:

Action inputs

The two Modal tokens are passed as env:, not inputs.

Gate merges on the check

To require a green build-and-boot before any merge:

1. Go to Settings → Branches → Branch protection rules for your default branch.
2. Enable Require status checks to pass before merging.
3. Add cilicon / build + boot as a required check (the name comes from the workflow's job.name).

Now a PR can't merge unless every target builds, fits, and boots.

What shows up on the PR

• A status check — the JUnit report (one <testcase> per target) published as a check run.
• A Markdown summary — written to $GITHUB_STEP_SUMMARY: each target's pass/fail, build time, on-target check detail, and flash size.
• A fan-out sweep grid — when a target uses a matrix:, a ✅/❌ heatmap of the sweep (a row for one axis, a table for two).
• A failure-logs section — a collapsible block with the tail of any failing step's output.
• Uploaded artifacts — a cilicon-results bundle: the JUnit report, the pulled binaries, and any telemetry file.

The cilicon.yml

A cilicon.yml is a list of targets. A target is intentionally small and uniform across wildly different silicon: it carries its own toolchain (a base image + apt, or a dockerfile) and its own way of proving the artifact actually runs (a validation tier).

Every target needs at least an id and a build. Unknown fields are rejected, and so is an unknown validate tier (unless it's custom). The whole project directory is mounted into every sandbox.

targets:
  - id: stm32h7/cortex-m
    base: debian:bookworm-slim
    apt: [gcc-arm-none-eabi, qemu-system-arm]
    build: arm-none-eabi-gcc ... -o build/firmware.elf
    validate: qemu_system
    machine: lm3s6965evb
    artifact: build/firmware.elf
    expect: "BOOT OK"

Field reference

Identity

Toolchain

Proof-it-runs

Assertions — how cilicon judges "it actually ran"

Size budget — does it fit the silicon?

Test phase & plumbing

The matrix: block

A matrix: expands one target entry into the cartesian product of its values — each combination becomes its own independent target and its own cloud container. Keep {var} in the id to keep ids unique.

- id: node-{arch}
  matrix:
    arch: [arm, aarch64, riscv64]
  base: debian:bookworm-slim
  apt: ["gcc-{arch}-linux-gnu", qemu-user]
  build: "{arch}-linux-gnu-gcc -static -O2 src/perception.c -o build/app-{arch}"
  validate: custom
  run: "stdbuf -oL qemu-{arch} ./build/app-{arch}"
  artifact: build/app-{arch}
  expect: "perception: engine ok"

This produces node-arm, node-aarch64, node-riscv64. Substitution is a plain token replace (not str.format), so shell ${...} and $(( ... )) in your commands survive untouched.

Boards

A board is a one-word alias for a bundle of target fields, applied as defaults (anything you set explicitly on the target wins). Define your own under a top-level boards: — a board can set any target field.

boards:
  my-mcu:                      # then use:  board: my-mcu
    base: my-registry/toolchain:latest
    apt: [gcc-arm-none-eabi, qemu-system-arm]
    validate: qemu_system
    machine: mps2-an385

Your boards extend — and can override by name — a built-in catalog of 100+ starters across families. Run cilicon boards to list them all, grouped by tier:

Validation tiers

A validation tier is how a target proves its artifact actually runs. Tiers are data, not code — adding a chip is one YAML entry, never a cilicon code change. A tier cilicon has never heard of is validate: custom + run:.

GPU catalog

The gpu: field (used by real_gpu and custom) accepts any Modal GPU type. Run cilicon gpus to list them. Smallest → biggest:

T4  L4  A10G  A100  A100-40GB  A100-80GB  L40S  H100  H200  B200

• Add a count with :N, e.g. A100-80GB:2 or H100:2. A spec like T4 means one GPU.
• Unknown names pass through to Modal (so a newly-launched GPU works day one) but won't be flagged as "known" by cilicon gpus.

- id: infer/cuda
  base: nvidia/cuda:12.4.1-devel-ubuntu22.04
  build: nvcc -O2 src/gpu/infer.cu -o build/infer
  validate: real_gpu
  gpu: "H100"
  artifact: build/infer
  expect: "infer: gpu ok"