System

The system module reports runtime, memory, process, host, supervisor, and cluster state. It also exposes selected runtime controls.

This is an API reference. Most snippets show one isolated operation; controls such as shutdown, runtime tuning, and distributed locks require explicit policy authorization and application-specific failure handling.

Loading

local system = require("system")

Shutdown

Request system shutdown with an exit code. Calling this function from any process or actor terminates the entire system:

local ok, err = system.exit(0)

Returns: boolean, error

Listing Modules

List the loaded Lua modules and their metadata:

local mods, err = system.modules()

Returns: table[], error

Each module table contains:

Deployment Sources

The system.source sub-table reads the normalized deployment baseline: the entry set produced by the sources the application was assembled from, before any registry history is applied.

local loaded, err = system.source.load()

Returns: table, error

owners is sorted with the application owner first, then the remaining owners alphabetically. The application owner is the string "application".

local loaded, err = system.source.load()
if err then return nil, err end

for _, owner in ipairs(loaded.owners) do
    print(owner)
end

for _, entry in ipairs(loaded.entries) do
    print(entry.id, entry.kind)
end

The load is taken from one stable source generation, so entries and owners always describe the same baseline. Filesystem paths behind each source are runtime-private and are not exposed; a failed load reports a generic internal error rather than leaking the backing path.

Permission: system.read on sources

Memory Statistics

Read detailed memory statistics:

local stats, err = system.memory.stats()

Returns: table, error

The statistics table contains:

Current Allocation

Read the number of bytes currently allocated:

local bytes, err = system.memory.allocated()

Returns: number, error

Heap Objects

Read the number of allocated heap objects:

local count, err = system.memory.heap_objects()

Returns: number, error

Memory Limit

Set the memory limit and return its previous value:

local prev, err = system.memory.set_limit(1024 * 1024 * 100)

Returns: number, error

Read the current memory limit:

local limit, err = system.memory.get_limit()

Returns: number, error

Force GC

Run garbage collection immediately:

local ok, err = system.gc.collect()

Returns: boolean, error

GC Target Percentage

Set the garbage-collection target percentage and return its previous value. A value of 100 triggers collection when the heap doubles:

local prev, err = system.gc.set_percent(200)

Returns: number, error

Read the current garbage-collection target percentage:

local percent, err = system.gc.get_percent()

Returns: number, error

Goroutine Count

Read the number of active goroutines:

local count, err = system.runtime.goroutines()

Returns: number, error

GOMAXPROCS

Read or set the GOMAXPROCS value:

-- Get current value
local current, err = system.runtime.max_procs()

-- Set new value
local prev, err = system.runtime.max_procs(4)

Returns: number, error

CPU Count

Read the number of logical CPUs:

local cpus, err = system.runtime.cpu_count()

Returns: number, error

Process ID

Read the current operating-system process ID:

local pid, err = system.process.pid()

Returns: number, error

Hostname

Read the system hostname:

local hostname, err = system.process.hostname()

Returns: string, error

Working Directory

Read the runtime's current working directory:

local dir, err = system.process.cwd()

Returns: string, error

Process Hosts

List process hosts with worker and queue statistics:

local hosts, err = system.hosts.list()

Returns: table[], error

Each host table contains:

List processes running on a specific host:

local procs, err = system.hosts.processes("app:host")

Returns: table[], error

Each process table contains:

Service State

Read the state of a supervised service:

local state, err = system.supervisor.state("namespace:service")

Returns: table, error

The state table contains:

All Service States

List the states of all supervised services:

local states, err = system.supervisor.states()

Returns: table[], error

Each state table has the same format as system.supervisor.state().

Cluster Primitives

The system.node, system.cluster, system.raft, and system.lock sub-tables expose the clustering layer. They are most useful when clustering is enabled; on a standalone node they degrade predictably — system.raft.* reports "raft not available", system.cluster reports just the local node, and system.lock requires the Raft-backed KV store that clustering provides.

Read calls report this node's local view of committed state and do not block on the network.

Node Identity

system.node reports the current node's identity in the cluster.

local id, err = system.node.id()      -- this node's ID
local addr, err = system.node.addr()  -- advertised network address
local role, err = system.node.role()  -- "leader" | "voter" | "standby" | "non-member"

Permission: system.read on node.

Cluster Membership

system.cluster reports cluster membership and the current leader.

local members, err = system.cluster.members()  -- array of node tables
local leader, err = system.cluster.leader()    -- leader node ID, or "" if unknown
local n, err = system.cluster.size()           -- count of visible members

system.cluster.members() returns an array of node tables. The local node is included once and sorts first.

Permission: system.read on cluster.

Raft State

system.raft reads this node's local view of the Raft consensus core. Every function returns nil, error ("raft not available") when Raft is not running on this node.

local leader, err = system.raft.is_leader()      -- boolean
local member, err = system.raft.is_member()      -- boolean: voter or standby
local role, err = system.raft.role()             -- same values as system.node.role()
local term, err = system.raft.term()             -- current Raft term
local idx, err = system.raft.commit_index()      -- highest committed log index
local stats, err = system.raft.stats()           -- raw stats map (string -> string)

Permission: system.read on raft, except system.raft.stats() which requires system.read on raft_stats.

Distributed Locks

system.lock provides cluster-wide mutual exclusion. A lock is a globally unique name owned by the calling process. It is built on the Raft-replicated system KV store, so at most one holder can exist across the cluster, and the lock auto-releases when the holder process exits or its node leaves — there is no stuck lock to clean up.

local ok, err = system.lock.acquire("orders.migration")
if not ok then
  -- err has kind errors.ALREADY_EXISTS when another process holds the lock.
  -- Apply the caller's retry and backoff policy for that case if needed.
  return nil, err
end

-- critical section: only one holder cluster-wide
local released, release_err = system.lock.release("orders.migration")
if release_err then
  return nil, release_err
end
return released

Acquisition is fail-fast: when a lock is already held, the call returns false immediately instead of blocking. Callers provide any required retry and backoff. Only the current holder can release a lock; a release attempt by another process is a no-op.

Permission: system.lock on the lock name (so policy can restrict which names a caller may lock).

Permissions

Security policy evaluation applies to system operations.

Errors

See Error Handling for working with errors.