morph.toml Reference

morph.toml is the project manifest read by the CLI (ProjectConfig.cpp). Unknown top-level sections are ignored for forward compatibility except where the parser explicitly errors on bad keys inside a known section.

This page is about the project-level file generated by morph new.

If you are contributing to the compiler/framework itself, note that packages under morphs/<Package>/ also have a file named morph.toml, but it is a different schema: package identity, token requests, runtime bundles, provider import/export, and [include] globs that load nested feature.toml and block.toml fragments. Start there instead:

• Plugin-governed pipeline
• morph.toml (framework)

---

Minimal generated shape

morph new emits (approximately) the following sections—use this as the ground truth for new projects:

[project]
name = "my_project"
version = "0.1.0"

[package]
kind = "application"
description = "…"
repository = "https://github.com/your-org/my_project"
license = "MIT"
source_dir = "src"

[build]
main = "src/Main.mx"
build_dir = "build"
optimize = "aggressive"
emit_ir = "optimized"
target_cpu = "native"
tensor_profile = "balanced"
tensor_autotune = true
tensor_kernel_cache = "build/.morph_cache/tensor/"

[web]
canvas_id = "morph-canvas"
wgsl_cache = true
dev_server_port = 8080
enable_shared_array = true
initial_memory_mb = 64
maximum_memory_mb = 512
wasm_simd = true

[morph]
host_route = "host.llvm"
nn_route = "nn.graph"

[dependencies]
# foo = { github = "owner/repo", version = "^1.0.0" }

[vcon], [vcon.permissions], [vcon.resources], [native], [native.<Provider>], etc. are optional and only needed when you use those features.

---

Sections (what the parser accepts)

[project]

Key	Meaning
name	Project name (required).
version	Version string.

Description and repository live under [package], not [project].

[package]

Key	Meaning
kind	application or library.
description, repository, license	Metadata.
source_dir	Root for sources (default layout uses src).

[build]

Key	Meaning
main / entry	Entry .mx file.
build_dir / out_dir	Build root (default build).
optimize / opt_level	O0, O1, O2, O3, Oz, or aggressive (see parseOptimizeLevel).
emit_ir / ir_mode	none, optimized, or both.
target_cpu / cpu	native or generic.
tensor_profile	balanced, gemm_parity, or ai_fused.
tensor_autotune	true / false.
tensor_kernel_cache	Cache directory path string.
vcon	Legacy boolean mapped to VCON enablement (see parser).

There is no basic optimization level or minimal / performance tensor profile in the parser—those names will fail validation.

[dependencies]

Inline-table GitHub deps are canonical:

foo = { github = "owner/repo", version = "^1.2.0" }

Optional fields inside the table include tag and commit. A legacy shorthand name = "version" form is still accepted.

[web]

Keys: canvas_id, wgsl_cache, dev_server_port, enable_shared_array, initial_memory_mb, maximum_memory_mb, wasm_simd (all validated in ProjectConfig.cpp).

[morph]

Routing / backend selection:

Key	Meaning
host_route	Host pipeline route id.
nn_route	Neural-network route id.
host_backend	Optional host backend id.
gpu_route, shader_route	Optional GPU/shader routes.

[vcon] and nested tables

[vcon] supports enabled, output, include_debug_map, hot_reload, runtime ids/paths, signing, pack options, etc. Additional nested sections include [vcon.permissions], [vcon.resources], [vcon.pack], [vcon.pack.resources], and native bridging tables such as [vcon.native] / [vcon.native.<Provider>]. See ProjectConfig.cpp Section::Vcon* cases for the exact key list.

[native] / [native.<Provider>]

Native provider manifests, artifacts, and build metadata for host interop. Errors if unknown keys appear inside a provider section.

---

Optimization levels

Value	Role
O0 … O3, Oz	LLVM-style discrete levels.
aggressive	Full aggressive pipeline (maps to BuildOptimizeLevel::Aggressive).

---

emit_ir modes

Value	Role
none	Do not emit LLVM IR files.
optimized	Emit optimized IR (per project policy).
both	Emit both raw and optimized where applicable.

---

Tensor profiles

Value	Role
balanced	Default balanced kernels.
gemm_parity	GEMM-oriented tuning.
ai_fused	Fused AI-oriented tuning.

---

Next Steps

• .morphsettings — Editor/compiler rule file
• Learn morph.toml in the framework chapter — Package vs feature manifests in the wider morph graph