Getting Started

Getting Started

Three minutes from a fresh shell to a running program.

1. Make sure you have the .NET SDK

Cadenza requires .NET SDK 10.0.300 or newer (file-based apps + custom #:sdk support). See Installation for OS-specific steps.

dotnet --version
# 10.0.300 or newer

2. Pick how you'll create the file

Option A — dotnet new (recommended)

Install the templates once:

dotnet new install Cadenza.Templates

Scaffold a starter:

dotnet new cadenza-web -n hello -o ./hello
cd hello

You get a hello.cs pinned to the latest Cadenza.Web with a working route.

Option B — write it yourself

Save as app.cs:

#!/usr/bin/env dotnet run
#:sdk Cadenza.Web@1.0.15

Get("/", () => "Hello, Cadenza");
await Run();

That's the entire program.

3. Run it

dotnet run app.cs

(Or just dotnet run if you used the template — it picks up the single .cs in the folder.)

The first invocation restores the SDK; subsequent runs start in under a second.

Now listening on: http://localhost:5000

4. Pick the SDK that matches your program

You want…	Use	Bare entry point
A CLI tool or shell-replacement script	#:sdk Cadenza@1.0.15	top-level code
A background service / daemon	#:sdk Cadenza.Worker@1.0.15	await Run(async ct => …)
An HTTP service / Minimal API	#:sdk Cadenza.Web@1.0.15	Get(...); await Run();
An MCP server for Claude / Cursor	#:sdk Cadenza.Mcp@1.0.15	Tool(...); await Run();
A local AI agent / OpenAI-compatible server	#:sdk Cadenza.Agent@1.0.15	SystemPrompt(...); UseOllama(...); await Run();

Each has its own page with a working example: Cadenza Console · Cadenza Worker · Cadenza Web · Cadenza Mcp · Cadenza Agent.

5. Ship it

# Self-contained single binary, ~30–40 MB
dotnet publish app.cs -r linux-x64 -c Release

# Or straight to a container image, no Dockerfile
dotnet publish app.cs --os linux --arch x64 /t:PublishContainer

See Deployment Single Binary and Deployment Container for the full story (AOT, trimming, base images, registries).

Where to go next

• Get full IntelliSense → Editor Setup
• Learn the bare-name API → Tier 1 API
• See what #:sdk / #:include / #:property actually do → Directives
• Browse all 18 working samples → Samples
• Hit a snag → Troubleshooting