Get running in five commands

Build IronKernel, run a real program, then package it. Scripts, packages, and the REPL all start with the standard library loaded.

1. Install

Choose the .NET SDK for development or a self-contained release for immediate use.

git clone https://github.com/ironkernel-lang/IronKernel
cd IronKernel
dotnet build
dotnet test

tar -xzf ironkernel-linux-x64.tar.gz
cd ironkernel-linux-x64
./IronKernel --version

Release archives include kernel.scm and promises.scm. Keep them beside the executable.

2. Start the REPL

dotnet run --project IronKernel
# Release binary:
./IronKernel

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

3. Run a script

dotnet run --project IronKernel -- Examples/hello.scm
dotnet run --project IronKernel -- run Examples/hello.scm one two

Arguments are available as the Kernel list args. Script paths are resolved from your current directory; standard-library files are found there or beside the runtime.

4. Validate and package

dotnet run --project IronKernel -- compile Examples/hello.scm -o hello.ikc
dotnet run --project IronKernel -- run hello.ikc

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

5. Read errors at the source

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

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

Startup, script, compile, and package failures go to stderr and return a non-zero exit code, making the CLI suitable for build tools and editor integrations.

6. 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 for compatibility.

dotnet run --project IronKernel -- \
  --profile safe Examples/safe-clr.scm

Safe bindings make direct typed calls—such as Console.write-line and String.concat—generated from a checked manifest. Copying an unrestricted interop value into a safe environment does not copy its authority.

7. Explore in VS Code

The repository includes an extension with syntax highlighting, snippets, source diagnostics, run and package commands, and a local playground powered by the real IronKernel CLI.

cd editors/vscode
npm install
npm run package
# Install the generated VSIX from VS Code

Playground execution requires a trusted workspace because IronKernel can invoke .NET APIs. Extension setup and settings →

Where next?