Getting started

Install a release binary (or the ik .NET tool), put it on your PATH, then run the REPL, scripts, and projects. You do not need to clone the repository or prefix commands with dotnet run --project IronKernel for day-to-day use.

1. Install

Prefer the NuGet global tool (ik) when you already have the .NET 10 SDK. Use a self-contained release binary when you want a single executable with no SDK. Both expose the same CLI; only the command name differs.

Option A — `ik` from NuGet.org (recommended)

IronKernel.Tool is a .NET global tool with command name ik. IronKernel.Sdk is the MSBuild SDK used by .ikproj files (<Project Sdk="IronKernel.Sdk/…">); restore pulls it automatically when a project references it.

Requires the .NET 10 SDK. Check with dotnet --list-sdks — you need a 10.0.x line. Install from dotnet.microsoft.com/download if needed.

Install the global tool

dotnet tool install -g IronKernel.Tool

# Ensure global tools are on PATH (often already set by the SDK installer):
export PATH="$PATH:$HOME/.dotnet/tools"

ik --version

Upgrade later with:

dotnet tool update -g IronKernel.Tool

The tool stores kernel.ikr / promises.ikr next to its assembly under the .NET tool store, so you do not keep a separate stdlib folder.

If install fails with Settings file 'DotnetToolSettings.xml' was not found in the package, the package itself is fine — that message is a known .NET SDK quirk when the active SDK is older than the tool’s target framework (net10.0). Install or select a .NET 10 SDK, then retry. Confirm with dotnet --version (should report 10.x) and that no older global.json in the current directory is pinning an earlier SDK.

Option B — Release binary (no SDK required)

GitHub Releases ship self-contained archives named ironkernel-<rid>.tar.gz. Choose the RID for your machine:

linux-x64 — Linux x86_64
win-x64 — Windows x64
osx-arm64 — macOS Apple Silicon
osx-x64 — macOS Intel

Inside the archive you get IronKernel (or IronKernel.exe on Windows), plus kernel.ikr and promises.ikr. Those three files must stay in the same directory — the runtime loads the standard library from beside the executable.

macOS Apple Silicon · example for v0.3.1

curl -L -o ironkernel.tar.gz \
  https://github.com/ironkernel-lang/IronKernel/releases/download/v0.3.1/ironkernel-osx-arm64.tar.gz
tar -xzf ironkernel.tar.gz
mkdir -p "$HOME/.local/opt"
mv ironkernel-osx-arm64 "$HOME/.local/opt/ironkernel"
export PATH="$HOME/.local/opt/ironkernel:$PATH"
# Add the export to ~/.zshrc or ~/.bashrc so it persists.

Linux x64 · same idea

curl -L -o ironkernel.tar.gz \
  https://github.com/ironkernel-lang/IronKernel/releases/download/v0.3.1/ironkernel-linux-x64.tar.gz
tar -xzf ironkernel.tar.gz
mkdir -p "$HOME/.local/opt"
mv ironkernel-linux-x64 "$HOME/.local/opt/ironkernel"
export PATH="$HOME/.local/opt/ironkernel:$PATH"

Windows x64 (PowerShell)

# Download ironkernel-win-x64.tar.gz from the releases page, then:
tar -xzf ironkernel-win-x64.tar.gz
# Move the folder somewhere stable, e.g. %LOCALAPPDATA%\IronKernel
# Add that folder to your user PATH. The command name is IronKernel.exe.

After PATH is set, the command is IronKernel (IronKernel.exe on Windows).

Which command do I type?

Global tool (Option A) → ik
Release archive on PATH (Option B) → IronKernel

They accept the same arguments. The rest of this page shows ik; if you installed Option B, substitute IronKernel everywhere (for example IronKernel run hello.ikr).

2. Verify the install

ik --version
# or: IronKernel --version

You should see a version string such as 0.3.1-net10. If the shell says “command not found”, your PATH does not include the install directory (or ~/.dotnet/tools for the global tool).

3. Start the REPL

ik
# or: IronKernel

Enter (+ 20 22) and type quit to leave. The interactive line editor needs a real terminal; use script mode in automation and CI.

4. Run a script

Create a file and pass it to the CLI (no repository clone required):

cat > hello.ikr <<'EOF'
(define write
  (lambda (x) (. System.Console WriteLine x)))
(write "Hello,world!")
EOF

ik hello.ikr
# Explicit form (same thing):
ik run hello.ikr one two

Hello,world!

Extra arguments after the script path are available as the Kernel list args. Script paths resolve from your current directory; the standard library is loaded from beside the installed runtime.

5. Compile and run an IKC package

ik compile hello.ikr -o hello.ikc
ik run hello.ikc

An .ikc file is an IronKernel source package, not a CLR assembly. Packaging validates and compiles without executing; execution happens only when you run the package.

6. Create a project with `ik`

.ikproj projects are managed by the same CLI. Prefer the ik tool name in docs and scripts; with a release binary the equivalent is IronKernel new …, IronKernel run, and so on.

ik new app hello
cd hello
ik run
ik test
ik add Acme.IronKernel.Http 1.2.0
ik add Npgsql 9.0.0 --clr
ik restore
ik tree
ik build
ik pack

Projects reuse NuGet for IronKernel source packages and CLR libraries. Load order is stdlib → restored packages → project sources (sorted) → IronKernelMain last. Commit packages.lock.json and use ik restore --locked in CI.

For a multi-file HTTP example from the repository, see Examples/lantern/ (ik run from that directory, or ik run path/to/lantern.ikproj).

7. VS Code extension

The extension provides syntax highlighting (operatives vs applicatives), snippets, diagnostics, Run/Build commands, and a playground backed by the real CLI — not a second evaluator in JavaScript.

Install the extension

The extension is not on the Marketplace yet. Build a VSIX from the repository (or grab the ironkernel-vscode artifact from the VS Code extension GitHub Actions workflow), then install it in VS Code:

git clone https://github.com/ironkernel-lang/IronKernel
cd IronKernel/editors/vscode
npm install
npm run package
# In VS Code: Extensions → ⋯ → Install from VSIX… → select the .vsix

How the extension finds IronKernel

Run, Compile, Run Project, Build Project, and the playground all shell out to the real runtime. Resolution order:

ironkernel.executablePath — if set, must be an absolute path to the IronKernel binary or the ik shim (for example /Users/you/.local/opt/ironkernel/IronKernel or /Users/you/.dotnet/tools/ik). The extension runs that file directly and uses its directory as the working directory so adjacent kernel.ikr / promises.ikr resolve for release installs.
Workspace .NET project — if the open workspace contains IronKernel/IronKernel.fsproj (override with ironkernel.projectPath), the extension uses dotnet run --project … --. This is for people developing IronKernel itself, not for app authors.
PATH — otherwise it invokes IronKernel (IronKernel.exe on Windows). Putting the release directory on your PATH (Option A) is enough for this step.

Important: step 3 looks for the name IronKernel, not ik. If you installed Option A (global tool only), set ironkernel.executablePath to the absolute path of the ik shim (usually ~/.dotnet/tools/ik), or put a release binary directory on PATH.

settings.json · pin the ik tool or a release binary

{
  "ironkernel.executablePath": "/Users/you/.dotnet/tools/ik",
  "ironkernel.profile": "unrestricted",
  "ironkernel.runArgs": []
}

.ikproj files are associated with XML so VS Code highlights them as MSBuild projects.

Other useful settings:

ironkernel.ikprojPath — pin which .ikproj Run/Build Project uses (otherwise the extension discovers the nearest project).
ironkernel.profile — minimal, safe, or unrestricted (default).
ironkernel.runArgs — extra args for Run Current File / Run Project.

Playground and run commands require a trusted workspace because IronKernel can call into .NET. Right-click a .ikproj in the explorer for Run Project / Build Project.

8. Read errors at the source

Diagnostics identify the file and range, then underline the failing form.

demo.ikr:2:1: Getting an unbound variable: 'missing'
(missing 42)
^^^^^^^^^^^^

Startup, script, compile, package, and project failures go to stderr with a non-zero exit code, so the CLI works in build tools and the VS Code Problems view.

9. Choose host authority

Capability profiles decide which host operations enter the root environment. minimal has no host access, safe exposes reviewed generated CLR wrappers, and unrestricted preserves raw reflection and I/O (default).

ik --profile safe hello.ikr

10. Handle effects and await tasks

Unforgeable prompt tags let handlers intercept only their own operations. A handler can abort the captured computation or resume it once; resumption reinstalls the same handler for later operations.

(define request (make-prompt-tag))
(prompt request
  (lambda (value k) (resume k (+ value 1)))
  (+ 1 (perform request 40)))
; ⇒ 42

(await-task (task-delay 25 "ready"))

Async host access is available only in the unrestricted profile. Task callbacks enqueue outcomes; they never run the evaluator directly.

11. Add contracts without changing semantics

(define double (lambda (x) (+ x x)))
(contract double applicative (number) number pure #t)

(define raw (vau operands _ operands))
(contract raw operative (any) any pure #t)

User contracts remain runtime assertions. Only compiler-certified pure primitives are partially evaluated, and every folded call retains an exact guarded fallback.

12. Building from source (optional)

Clone the repository when you are developing IronKernel itself or want the example tree. Day-to-day language use should use ik or a release binary from §1.

git clone https://github.com/ironkernel-lang/IronKernel
cd IronKernel
dotnet build
dotnet test
dotnet run --project IronKernel -- Examples/hello.ikr

To exercise a local tool package before publishing:

dotnet pack IronKernel/IronKernel.fsproj -c Release -o packages
dotnet tool install -g IronKernel.Tool --add-source ./packages --version 0.3.0

Where next?

Understand Kernel Follow the language guide Browse examples Releases