X

A lightweight, Erlang-inspired virtual machine for concurrent, fault-tolerant applications in Crystal.

This project combines a clean stack-based bytecode interpreter with actor-model concurrency, lightweight processes, message passing, supervision trees, and built-in fault tolerance - all implemented in pure Crystal.

Inspired by Erlang's BEAM, but designed to be simple, hackable, and embeddable.

Features

• Stack-based VM - 120+ instructions across stack, arithmetic, logic, control flow, process, and message operations
• Actor-model concurrency - Lightweight processes with isolated stacks, mailboxes, and preemptive scheduling via reductions
• Fault tolerance - Process linking, monitoring, exit trapping, and supervision trees (one-for-one, one-for-all, rest-for-one)
• XASM assembler - Human-readable assembly language with modules, imports, exports, subroutines, and block-based control flow
• Multi-module system - .require with automatic file resolution, .import/.export for cross-module calls
• Hot code reloading - .dynamic modules can be reloaded at runtime without restarting processes
• Elixir-style standard library - IO, String, Integer, Float, Array, Map, Type modules with 80+ built-in functions
• Interactive debugger - Step, continue, breakpoints, stack/locals inspection, process filtering
• Lambdas and closures - First-class functions with captured variables
• Exception handling - try/catch/throw with stack unwinding
• Pure Crystal - No external dependencies beyond standard library

Quick Start

Installation

git clone https://github.com/konjac-lang/x.git
cd x
shards install

Hello World

Create hello.xasm:

.module Hello

.import IO.printLine/1

.process main
  push "Hello, World!"
  call IO.printLine/1

  push :normal
  exit
.end

Run it:

shards run -- hello.xasm

Build the binary

shards build --release
./bin/x hello.xasm

The XASM Language

XASM is a human-readable assembly language for the X VM. Every line is a verb - there are no implicit operations.

Modules and Directives

Every .xasm file starts with a module declaration:

.module MyApp.Main

; Import functions from other modules or standard library
.import IO.printLine/1
.import String.concatenate/2

; Require other modules (auto-resolved from disk)
.require "MyApp.Utils"

; Export functions for other modules to use
.export myFunction/1

Processes

Processes are the unit of concurrency. Each process has its own stack, locals, and mailbox:

.process main
  push "I am a process"
  call IO.printLine/1

  push :normal
  exit
.end

Variables

Local variables are declared with .local and accessed with load/store:

.process main
  .local name
  .local counter

  push "alice"
  store name

  push 0
  store counter

  load name
  call IO.printLine/1

  push :normal
  exit
.end

Control Flow

Block-based control flow - no manual jump offsets:

; If/else
load x
push 10
gt
if
  push "x is greater than 10"
  call IO.printLine/1
else
  push "x is 10 or less"
  call IO.printLine/1
end

; Loops
push 0
store i
loop
  load i
  push 10
  gte
  break_if

  load i
  inc
  store i
end

; Try/catch
try
  push "something dangerous"
  throw
catch
  push "caught it"
  call IO.printLine/1
end

Subroutines

Reusable code blocks within a module:

.subroutine greet
  .local name
  store name
  push "Hello, "
  load name
  call String.concatenate/2
  return
.end

Message Passing

Processes communicate through messages:

; Send a message to a named process
push "worker"
push "do something"
send

; Receive a message (blocks until one arrives)
receive

; Wait for a process to register
await "worker"

Spawning Processes

; Spawn a new process
spawn
  self
  register "worker"
  loop
    receive
    call IO.printLine/1
  end
end

; Spawn with a link (crash propagation)
spawn_link
  push "linked child"
  call IO.printLine/1
  push :normal
  exit
end

Lambdas

; Create a lambda capturing a variable
lambda [multiplier]
  load multiplier
  mul
  return
end

; Invoke with arity
push 5
invoke 1

Hot Code Reloading

Mark a module as dynamic to enable live reloading:

.module MyApp.Config
.dynamic

.export version/1

.subroutine version
  push "1.0.0"
  return
.end

Reload at runtime from another process:

push "MyApp.Config"           ; module name to reload
push "MyApp.Config.v2"        ; file hint (resolved by module resolver)
reload

The new code is picked up by all processes on their next function call - no restart required.

Supervision Trees

Declarative supervisor configuration:

.supervisor pool :one_for_one max_restarts=3 window=5

  .child "logger" :permanent
    self
    register "logger"
    loop
      receive
      call IO.printLine/1
    end
  .end

  .child "worker" :transient
    push "working..."
    call IO.printLine/1
    push :normal
    exit
  .end

.end

CLI

Usage: x [options] <file.xasm> [file2.xasm ...]

Options:
    -v, --version                    Show version
    -h, --help                       Show this help
    -d, --debug                      Enable debug logging
    -q, --quiet                      Suppress info logging
    -I PATH, --include PATH          Add search path for module resolution
    --ast                            Print the AST and exit
    --instructions                   Print compiled instructions and exit
    --debugger                       Launch interactive debugger

Interactive Debugger

Launch with --debugger to step through execution:

-- Process <1> (room) @ instruction 0 --
  -> PROCESS_SELF
  Stack: (empty)
xdb>

Commands:

Command	Short	Description
step	s	Execute one instruction
next	n	Step over subroutines
continue	c	Continue until next breakpoint
run	r	Run without stopping
kill	k	Kill current process
stack	st	Show full stack
locals	l	Show local variables
mailbox	mb	Show process mailbox
processes	ps	List all processes
registry	reg	Show named processes
instructions	is	Show nearby instructions
callstack	cs	Show call frames
break <addr>	b	Breakpoint at instruction
break <name>	b	Breakpoint on named process
break <name>:<addr>	b	Breakpoint on process at instruction
filter <pid>	f	Only break on one process
eval <expr>	e	Inspect values
help	h	Show all commands
quit	q	Exit

Press Enter to repeat the last command.

Standard Library

IO

Function	Description
IO.puts/1	Print string with newline, returns :okay
IO.print/1	Print string without newline, returns :okay
IO.printLine/1	Alias for IO.puts/1
IO.inspect/1	Print inspect representation, returns the value
IO.gets/0	Read a line from stdin

String

Function	Description
String.concatenate/2	Concatenate two strings
String.length/1	String length
String.reverse/1	Reverse a string
String.upcase/1	Convert to uppercase
String.downcase/1	Convert to lowercase
String.trim/1	Strip whitespace from both ends
String.trimLeading/1	Strip leading whitespace
String.trimTrailing/1	Strip trailing whitespace
String.split/2	Split string by delimiter
String.join/2	Join array with separator
String.contains/2	Check if string contains substring
String.startsWith/2	Check prefix
String.endsWith/2	Check suffix
String.replace/3	Replace all occurrences
String.slice/3	Extract substring (string, start, length)
String.at/2	Character at index
String.toInteger/1	Parse to integer
String.toFloat/1	Parse to float
String.toAtom/1	Convert to atom/symbol
String.duplicate/2	Repeat string N times
String.padLeading/3	Pad start to width
String.padTrailing/3	Pad end to width
String.toString/1	Convert any value to string

Integer

Function	Description
Integer.toString/1	Convert to string
Integer.toFloat/1	Convert to float
Integer.parse/1	Parse string to integer
Integer.isEven/1	Check if even
Integer.isOdd/1	Check if odd
Integer.digits/1	Get array of digits
Integer.gcd/2	Greatest common divisor

Float

Function	Description
Float.toString/1	Convert to string
Float.toInteger/1	Truncate to integer
Float.parse/1	Parse string to float
Float.round/2	Round to N decimal places
Float.ceil/1	Ceiling
Float.floor/1	Floor
Float.isNan/1	Check for NaN
Float.isInfinity/1	Check for infinity

Array

Function	Description
Array.new/0	Create empty array
Array.length/1	Array length
Array.size/1	Alias for length
Array.first/1	First element
Array.last/1	Last element
Array.at/2	Element at index
Array.get/2	Alias for at
Array.set/3	Set element at index
Array.append/2	Add to end
Array.prepend/2	Add to start
Array.push/2	Alias for append
Array.pop/1	Remove last, returns [array, element]
Array.concat/2	Concatenate two arrays
Array.reverse/1	Reverse array
Array.sort/1	Sort array
Array.uniq/1	Remove duplicates
Array.flatten/1	Flatten one level
Array.contains/2	Check membership
Array.indexOf/2	Find index of element
Array.slice/3	Extract sub-array
Array.take/2	Take first N elements
Array.drop/2	Drop first N elements
Array.zip/2	Zip two arrays into pairs
Array.isEmpty/1	Check if empty
Array.sum/1	Sum of elements
Array.product/1	Product of elements
Array.min/1	Minimum element
Array.max/1	Maximum element
Array.join/2	Join elements with separator

Map

Function	Description
Map.new/0	Create empty map
Map.put/3	Set key-value pair
Map.get/2	Get value by key
Map.getWithDefault/3	Get with fallback
Map.delete/2	Remove key
Map.hasKey/2	Check if key exists
Map.keys/1	Get all keys
Map.values/1	Get all values
Map.size/1	Number of entries
Map.merge/2	Merge two maps
Map.toArray/1	Convert to array of [key, value] pairs
Map.isEmpty/1	Check if empty

Type

Function	Description
Type.of/1	Get type name as string
Type.inspect/1	Get inspect representation
Type.toString/1	Convert any value to string
Type.isNull/1	Check if null
Type.isInteger/1	Check if integer
Type.isFloat/1	Check if float
Type.isString/1	Check if string
Type.isBoolean/1	Check if boolean
Type.isArray/1	Check if array
Type.isMap/1	Check if map
Type.isSymbol/1	Check if symbol
Type.isLambda/1	Check if lambda
Type.isNumeric/1	Check if integer or float

TCP

Function	Description
TCP.listen/1	Create a TCP server on a port (binds to 0.0.0.0)
TCP.listenOn/2	Create a TCP server on a specific address and port
TCP.listenWithBacklog/3	Create a TCP server with custom backlog
TCP.accept/1	Accept a client connection (async, blocks process)
TCP.acceptTimeout/2	Accept with timeout in milliseconds
TCP.connect/2	Connect to a host and port (async)
TCP.connectTimeout/3	Connect with timeout in milliseconds
TCP.send/2	Send string data over a socket (async)
TCP.sendBinary/2	Send binary data over a socket (async)
TCP.receive/2	Receive up to N bytes as string (async)
TCP.receiveBinary/2	Receive up to N bytes as binary (async)
TCP.receiveTimeout/3	Receive with timeout in milliseconds
TCP.receiveLine/2	Read a line up to max bytes (async)
TCP.receiveExact/2	Read exactly N bytes (async)
TCP.close/1	Close a socket or server
TCP.isClosed/1	Check if a socket is closed
TCP.setNodelay/2	Enable/disable TCP_NODELAY
TCP.setKeepalive/2	Enable/disable keepalive
TCP.setReceiveBufferSize/2	Set receive buffer size
TCP.setSendBufferSize/2	Set send buffer size
TCP.setReadTimeout/2	Set read timeout in milliseconds
TCP.setWriteTimeout/2	Set write timeout in milliseconds
TCP.clearReadTimeout/1	Remove read timeout
TCP.clearWriteTimeout/1	Remove write timeout
TCP.setReuseAddress/2	Enable/disable SO_REUSEADDR
TCP.setReusePort/2	Enable/disable SO_REUSEPORT
TCP.setLingerOption/3	Set linger option (socket, enabled, timeout)
TCP.localAddress/1	Get local [address, port]
TCP.remoteAddress/1	Get remote [address, port]
TCP.shutdown/2	Shutdown socket direction ("read", "write", or "both")

UDP

Function	Description
UDP.open/1	Open a UDP socket bound to a port
UDP.openOn/2	Open a UDP socket bound to address and port
UDP.openUnbound/0	Open an unbound UDP socket
UDP.connect/3	Connect a UDP socket to a remote host and port
UDP.send/2	Send string data on a connected socket (async)
UDP.sendTo/4	Send string data to a specific host and port (async)
UDP.sendToBinary/4	Send binary data to a specific host and port (async)
UDP.receive/2	Receive up to N bytes as string (async)
UDP.receiveFrom/2	Receive data with sender [data, address, port] (async)
UDP.receiveFromBinary/2	Receive binary data with sender info (async)
UDP.receiveFromTimeout/3	Receive with sender info and timeout (async)
UDP.close/1	Close a UDP socket
UDP.isClosed/1	Check if socket is closed
UDP.setBroadcast/2	Enable/disable broadcast
UDP.setReceiveBufferSize/2	Set receive buffer size
UDP.setSendBufferSize/2	Set send buffer size
UDP.joinMulticastGroup/2	Join a multicast group
UDP.leaveMulticastGroup/2	Leave a multicast group
UDP.setMulticastLoopback/2	Enable/disable multicast loopback
UDP.setMulticastHops/2	Set multicast TTL/hops
UDP.localAddress/1	Get local [address, port]

Unix

Function	Description
Unix.listen/1	Create a Unix domain socket server at a path
Unix.listenWithBacklog/2	Create server with custom backlog
Unix.accept/1	Accept a client connection (async)
Unix.acceptTimeout/2	Accept with timeout in milliseconds
Unix.connect/1	Connect to a Unix socket path (async)
Unix.send/2	Send string data (async)
Unix.sendBinary/2	Send binary data (async)
Unix.receive/2	Receive up to N bytes as string (async)
Unix.receiveBinary/2	Receive up to N bytes as binary (async)
Unix.receiveTimeout/3	Receive with timeout in milliseconds
Unix.receiveLine/2	Read a line up to max bytes (async)
Unix.close/1	Close a socket or server
Unix.isClosed/1	Check if closed
Unix.unlink/1	Delete the socket file from disk
Unix.setReadTimeout/2	Set read timeout in milliseconds
Unix.setWriteTimeout/2	Set write timeout in milliseconds
Unix.clearReadTimeout/1	Remove read timeout
Unix.clearWriteTimeout/1	Remove write timeout
Unix.path/1	Get the socket file path

Socket

Function	Description
Socket.resolve/1	Resolve hostname to list of IP addresses (async)
Socket.resolveAll/3	Resolve with service and family filter ("ipv4", "ipv6", "any") (async)
Socket.parseIpAddress/2	Parse an IP address string and port into [address, port, family]
Socket.isValidIp/1	Check if a string is a valid IP address

Instruction Set Reference

Stack Operations

XASM	Description
push <value>	Push literal (string, integer, float, symbol, true, false, null)
pop	Discard top of stack
dup	Duplicate top
over	Copy second element to top
swap	Swap top two
rot	Rotate top three up
-rot	Rotate top three down
nip	Remove second element
tuck	Copy top below second
depth	Push stack depth
pick	Copy Nth element to top
roll	Move Nth element to top

Arithmetic

XASM	Description
add	a + b
sub	a - b
mul	a * b
div	a / b
mod	a % b
neg	Negate
abs	Absolute value
inc	Increment by 1
dec	Decrement by 1
pow	Power
floor	Floor
ceil	Ceiling
round	Round
min	Minimum of two
max	Maximum of two

Bitwise

XASM	Description
band	Bitwise AND
bor	Bitwise OR
bxor	Bitwise XOR
bnot	Bitwise NOT
shl	Shift left
shr	Shift right
ushr	Unsigned shift right

Comparison

XASM	Description
eq	Equal
neq	Not equal
ideq	Identical (strict)
nideq	Not identical
lt	Less than
lte	Less than or equal
gt	Greater than
gte	Greater than or equal
is_null	Check null
is_not_null	Check not null

Logic

XASM	Description
and	Logical AND
or	Logical OR
not	Logical NOT
xor	Logical XOR

Variables

XASM	Description
load <name>	Push local variable onto stack
store <name>	Pop stack into local variable
gload <name>	Load global variable
gstore <name>	Store global variable

Control Flow

XASM	Description
if...else...end	Conditional block
loop...end	Loop block
break	Exit loop
break_if	Exit loop if top is true
break_unless	Exit loop if top is false
continue	Jump to loop start
call Module.func/arity	Call built-in or module function
return	Return from subroutine
nop	No operation
halt	Halt execution

Process Operations

XASM	Description
self	Push current process ID
register <name>	Register process with a name
unregister <name>	Remove name registration
whereis <name>	Look up process by name
spawn...end	Spawn a new process
spawn_link...end	Spawn with bidirectional link
spawn_monitor...end	Spawn with monitor
exit	Exit current process (reason on stack)
kill	Kill a process
sleep	Sleep for duration
yield	Yield to scheduler
link	Link to another process
unlink	Unlink from a process
monitor	Monitor a process
demonitor	Stop monitoring
trap_on	Enable exit signal trapping
trap_off	Disable exit signal trapping
alive?	Check if process is alive
await <name>	Wait for a process to register

Messages

XASM	Description
send	Send message (name and value on stack)
send_after	Send message with delay
receive	Receive next message (blocks)
receive_timeout	Receive with timeout
peek	Peek at next message without consuming
mailbox_size	Push mailbox size

Exceptions

XASM	Description
try...catch...end	Exception handling block
throw	Throw an exception
rethrow	Re-throw current exception

Hot Reload

XASM	Description
reload	Reload a dynamic module (file hint and module name on stack)

Module Resolution

When you .require "MyApp.Utils", the resolver searches for matching files in this order:

1. MyApp/Utils.xasm
2. my_app/utils.xasm
3. my_app.utils.xasm
4. MyApp/utils.xasm
5. Utils.xasm
6. utils.xasm
7. MyApp.Utils.xasm

Search roots include the directory of the entry file and any paths added with -I.

If no file matches by name, the resolver scans .xasm files for a matching .module declaration.

Examples

The examples/ directory contains working demos:

Run any example:

shards run -- examples/single_module/Stick.Messaging.xasm
shards run -- examples/chat/Chat.Main.xasm
shards run -- examples/dynamic/Dynamic.Main.xasm

Architecture

                    XASM Source
                   (.xasm files)
                        |
                   +----v----+
                   |  Lexer  |  Tokenization
                   +----+----+
                   +----v----+
                   |  Parser |  AST generation
                   +----+----+
                   +----v---------+
                   | Code Generator|  Bytecode compilation
                   +----+---------+
                   +----v----+
                   |  Loader |  Module resolution, wiring
                   +----+----+
                        |
    +-------------------v---------------------+
    |            X VM Engine                   |
    |                                          |
    | +--------+  +--------+  +--------+       |
    | |Proc <1>|  |Proc <2>|  |Proc <N>|       |
    | | Stack  |  | Stack  |  | Stack  |       |
    | | Locals |  | Locals |  | Locals |       |
    | |Mailbox |  |Mailbox |  |Mailbox |       |
    | +--------+  +--------+  +--------+       |
    |                                          |
    | +--------------------------------------+ |
    | |           Scheduler                  | |
    | | Reduction-based preemptive scheduling| |
    | +--------------------------------------+ |
    |                                          |
    | +-------------+  +-------------------+   |
    | |Fault Handler|  |Supervisor Registry|   |
    | |Links/Monitors| |Restart strategies |   |
    | +-------------+  +-------------------+   |
    |                                          |
    | +--------------------------------------+ |
    | |    Built-in Function Registry        | |
    | | IO String Array Map Type Integer ... | |
    | +--------------------------------------+ |
    +------------------------------------------+

Why X?

• Learning - Understand how actor-model VMs work from the inside
• Embedding - Drop a concurrent runtime into your Crystal application
• Experimentation - Build DSLs, game scripting engines, or workflow systems
• Compiler target - XASM is a clean compilation target for higher-level languages

Contributing

1. Fork it (https://github.com/konjac-lang/x/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Giorgi Kavrelishvili - creator and maintainer