The Ergo Framework is an implementation of ideas, technologies, and design patterns from the Erlang world in the Go programming language. It is based on the actor model, network transparency, and a set of ready-to-use components for development. This significantly simplifies the creation of complex and distributed solutions while maintaining a high level of reliability and performance.

Features

Actor Model: isolated processes communicate through message passing, handling messages sequentially in their own mailbox with four priority queues. Processes support both asynchronous messaging and synchronous request-response patterns, enabling flexible communication while maintaining the actor model guarantees.
Network Transparency: actors interact the same way whether local or remote. The framework uses custom serialization and protocol for efficient distributed communication with connection pooling, compression, and type caching, making network location transparent to application code.
Supervision Trees: hierarchical fault recovery where supervisors monitor child processes and apply restart strategies when failures occur. Supports multiple supervision types (One For One, All For One, Rest For One, Simple One For One) and restart strategies (Transient, Temporary, Permanent) for building self-healing systems.
Meta Processes: bridge blocking I/O with the actor model through dedicated meta processes that handle TCP, UDP, Port, and Web protocols. Meta processes run blocking operations without affecting regular actor message processing.
Distributed Systems: service discovery through embedded or external registrars (etcd, Saturn), distributed publish/subscribe events with token-based authorization and buffering, remote process spawning with factory-based permissions, and remote application orchestration across nodes.
Ready-to-use Components: core framework includes Actor, Supervisor, Pool, and WebWorker actors plus TCP, UDP, Port, and Web meta processes. Extra library provides Leader, Metrics actors, WebSocket, SSE meta processes, Observer application, Colored and Rotate loggers, Erlang protocol support.
Flexibility: customize network stack components, certificate management, compression and message priorities, logging, distributed events, and meta processes. Framework supports mTLS, NAT traversal, important delivery for guaranteed messaging, and Cron-based scheduling.

Examples demonstrating the framework's capabilities are available in the examples repository.

Benchmarks

On a 64-core processor, Ergo Framework demonstrates a performance of over 21 million messages per second locally and nearly 5 million messages per second over the network.

Available benchmarks can be found in the benchmarks repository.

Messaging performance (local, network)
Memory consumption per process (demonstrates framework memory footprint)
Serialization performance comparison: EDF vs Protobuf vs Gob
Distributed Pub/Sub (event delivery to 1,000,000 subscribers across 10 nodes)

Observer

To inspect the node, network stack, running applications, and processes, you can use the observer tool

To install the Observer tool, you need to have the Go compiler version 1.20 or higher. Run the following command:

$ go install ergo.tools/observer@latest

You can also embed the Observer application into your node. To see it in action, see the demo example. For more information, visit the Observer documentation.

Quick start

For a quick start, use the ergo tool — a command-line utility designed to simplify the process of generating boilerplate code for your project based on the Ergo Framework. With this tool, you can rapidly create a complete project structure, including applications, actors, supervisors, network components, and more. It offers a set of arguments that allow you to customize the project according to specific requirements, ensuring it is ready for immediate development.

To install use the following command:

$ go install ergo.tools/ergo@latest

Now, you can create your project with just one command. Here is example:

Supervision tree

  mynode
  ├─ myapp
  │  │
  │  └─ mysup
  │     │
  │     └─ myactor
  ├─ myweb
  └─ myactor2

To generate project for this design use the following command:

$ ergo -init MyNode \
      -with-app MyApp \
      -with-sup MyApp:MySup \
      -with-actor MySup:MyActor \
      -with-web MyWeb \
      -with-actor MyActor2 \
      -with-observer

as a result you will get generated project:

  mynode
  ├── apps
  │  └── myapp
  │     ├── myactor.go
  │     ├── myapp.go
  │     └── mysup.go
  ├── cmd
  │  ├── myactor2.go
  │  ├── mynode.go
  │  ├── myweb.go
  │  └── myweb_worker.go
  ├── go.mod
  ├── go.sum
  └── README.md

to try it:

$ cd mynode
$ go run ./cmd

Since we included Observer application, open http://localhost:9911 to inspect your node and running processes.

Erlang support

Starting from version 3.0.0, support for the Erlang network stack has been moved to a separate module. Version 3.0 was distributed under the BSL 1.1 license, but starting from version 3.1 it is available under the MIT license. Detailed information is available in the Erlang protocol documentation.

Requirements

Go 1.20.x and above

Changelog

Fully detailed changelog see in the ChangeLog file.

v3.2.0 2026-02-04 [tag version v1.999.320]

Introduced mTLS support - new gen.CertAuthManager interface for mutual TLS with CA pool management (ClientCAs, RootCAs, ClientAuth, ServerName). See Mutual TLS documentation
Introduced NAT support - new RouteHost and RoutePort options in gen.AcceptorOptions for nodes behind NAT or load balancers. See Behind the NAT documentation
Introduced spawn time control - InitTimeout option in gen.ProcessOptions limits ProcessInit duration for both local and remote spawn. Remote spawn and application processes limited to max 15 seconds. See Process documentation
Introduced zip-bomb protection - decompression size limits to prevent memory exhaustion attacks
Added gen.Ref methods for request timeout tracking. See Generic Types:
- Deadline - returns deadline timestamp stored in reference
- IsAlive - checks if reference is still valid (deadline not exceeded)
Added gen.Node methods. See Node documentation:
- ProcessPID / ProcessName - resolve process PID by name and vice versa
- Call, CallWithTimeout, CallWithPriority, CallImportant, CallPID, CallProcessID, CallAlias - synchronous requests from Node interface
- Inspect / InspectMeta - inspect processes and meta processes
- MakeRefWithDeadline - create reference with embedded deadline
Added gen.RemoteNode.ApplicationInfo - query application information from remote nodes. See Remote Start Application documentation
Added gen.Process methods. See Process documentation:
- SendWithPriorityAfter - delayed send with priority
- SendExitAfter / SendExitMetaAfter - delayed exit signals
- SendResponseImportant / SendResponseErrorImportant - important delivery for responses
Added gen.Meta methods. See Meta Process documentation:
- SendResponse / SendResponseError - respond to requests from meta process
- SendPriority / SetSendPriority - message priority control
- Compression / SetCompression - compression settings
- EnvDefault - get environment variable with default value
Added gen.ApplicationSpec / gen.ApplicationInfo fields:
- Tags - labels for instance selection (blue/green, canary, maintenance). See Tags for Instance Selection
- Map - logical role to process name mapping. See Process Role Mapping
Ad

Ergo

Install / Use

README