GreyCat Server

Introduction

To empower digital twin, GreyCat is not only a Runtime but also a Server.

Any function can be exposed to remote procedure call (RPC) by adding an @expose pragma

@expose
fn compute(p: int): int {
    return 3 + 5 + p;
}
fn main() {
    println(compute(2));
}

This minimal code snippet already defines a server (–user=root impersonates the root user and bypasses authentication, more on this later)

greycat serve --user=root
# 10
# INFO  2026-10-27T09:28:06.293689Z GreyCat is serving on port: 8080, runtime: 8.4.594-stable+fe2b2a3fc
# WARN  2026-10-27T09:28:06.293715Z Impersonate mode with user: root

GreyCat server can be queried through an HTTP API.

The parameters for the endpoint can be url encoded:

curl -X POST -d "[100]" http://localhost:8080/project::compute
> 108

Or the parameters for the endpoint can be JSON encoded:

curl -X POST --json "[100]" http://localhost:8080/project::compute
> 108

From a terminal, greycat call does the same without writing the request, and authenticates with the root token of the project (see Call):

greycat call project::compute 100
> 108

Functions and error handling

fn sub_process() {
    throw "stop here";
}
@expose
fn computeWithSub(p: int): int {
    sub_process();
    return 3 + 5 + p;
}
fn main() {
    var res = computeWithSub(2);
    println(res);
}

In this example, sub_process and computeWithSub share error handling management, leading to the following error stack

greycat run --format=json

{
  "message": "stop here",
  "stack": [
    { "module": "project", "function": "main", "line": 10, "column": 33 },
    { "module": "project", "function": "computeWithSub", "line": 6, "column": 18 },
    { "module": "project", "function": "sub_process", "line": 2, "column": 23 }
  ]
}

Function entrypoint == Transaction

Every exception thrown activates a rollback mechanism, leaving the temporal graph unchanged

var counter: node<int?>;

@expose
fn inc_count() {
    println(*counter);
    counter.set((counter.resolve() ?? 0) + 1);
    throw "my bad";
}

This is illustrated in this example, where multiple calls do not alter the counter due to the following exception

greycat run inc_count --format=json
# null
# {"message":"my bad","stack":[{"module":"project","function":"inc_count","line":7,"column":20}]}

greycat run inc_count --format=json
# null
# {"message":"my bad","stack":[{"module":"project","function":"inc_count","line":7,"column":20}]}

Exposed functions are for short computations!

Like many API-oriented frameworks, GreyCat adds a timeout to remote function calls (default of 20s, configurable with --request_ttl)

@expose
fn heavy_computation() {
    while (true) {
        // noop
    }
}

any call through the HTTP API will then result in a timeout exception (and therefore rollback)

greycat serve --user=root

curl -X POST http://localhost:8080/project::heavy_computation
# {"message":"timeout","stack":[{"module":"project","function":"heavy_computation","line":3,"column":16}]}

timeout is similar for write and read function entrypoints; this enhances the server for multi-user experience

Long running functions? Task is the answer!

An in depth explanation can be found here

Env variables

GreyCat supports a wide range of environment variables that can either be defined on the cli or in an .env file

Runtime info

The runtime module provides a RuntimeInfo object, returned by Runtime::info(), which contains all important information about the currently running GreyCat server

Runtime Info Class

Store Stats

Runtime::store_stats() returns a StoreStats object describing the store. It reads every live block, so it lasts as long as a full backup.