Actor System

The ActorSystem is the top-level runtime that hosts actors and orchestrates messaging, clustering, remoting, and lifecycle. There is one ActorSystem per process. All actors, grains, and system services run within it.

Role and responsibilities

Responsibility	Description
Actor hosting	Spawns and supervises actors under the `/user` guardian. Manages the actor tree and parent-child relationships.
Messaging	Routes messages locally or remotely. Serializes and deserializes when crossing node boundaries.
Clustering	When enabled, joins a cluster, discovers peers, and provides location-transparent actor resolution.
Remoting	When enabled, exposes a TCP server and client for cross-node communication.
Event stream	Publishes system and cluster events (ActorStarted, NodeJoined, Deadletter, etc.) to subscribers. See Event Streams.
PubSub	When `WithPubSub()` or cluster is enabled, a topic actor manages application-level topics. See PubSub.
Scheduling	Delivers one-time, recurring, and cron-scheduled messages to actors.
Coordinated shutdown	Runs shutdown hooks, stops actors depth-first, and leaves the cluster gracefully.

See Architecture Overview for the component diagram.

Lifecycle

Start(ctx) → [running] → Stop(ctx) → [stopped]

NewActorSystem — Applies options; does not start services.
Start — Initializes remoting (if enabled), cluster (if enabled), scheduler, eviction, passivation, and system actors. Handle SIGTERM/SIGINT and call Stop for clean shutdown.
Stop — Runs coordinated shutdown hooks, stops user actors, deactivates grains, shuts down system actors, leaves cluster, stops remoting. Does not exit the process; call os.Exit if needed.

Details: Coordinated Shutdown, First Actor.

API surface

Spawning

Method	Use case
`Spawn(ctx, name, actor, opts...)`	Create a named actor locally (or on a specific host with `WithHostAndPort`).
`SpawnOn(ctx, name, actor, opts...)`	Create actor on a cluster node (placement: RoundRobin, Random, Local, LeastLoad) or in another data center (`WithDataCenter`).
`SpawnFromFunc(ctx, receiveFunc, opts...)`	Functional actor; no `Actor` implementation.
`SpawnNamedFromFunc(ctx, name, receiveFunc, opts...)`	Named functional actor.
`SpawnRouter(ctx, name, poolSize, routeesKind, opts...)`	Router with a pool of routees. Not cluster-relocatable.
`SpawnSingleton(ctx, name, actor, opts...)`	Cluster singleton; one instance across the cluster, hosted on the oldest node. See Singletons.

See Actor Lifecycle, Routers, Singletons, Clustering.

Resolution and inspection

Method	Purpose
`ActorOf(ctx, name)`	Resolve a PID by name. Local or remote; use `pid.IsLocal()` / `pid.IsRemote()` when it matters.
`ActorExists(ctx, name)`	Check if an actor exists locally or in the cluster.
`Actors(ctx, timeout)`	Enumerate all actors visible to this node. Use sparingly; cluster scan is costly.
`NumActors()`	Count of local actors only.
`Partition(name)`	Partition ID for a given actor name (cluster hashing).
`InCluster()`	Whether the system is running in cluster mode.

See PID, Location Transparency.

Messaging from outside

From outside the actor system (e.g. main), use system.NoSender():

NoSender().Tell(pid, msg) — Fire-and-forget.
NoSender().Ask(ctx, pid, msg, timeout) — Request-response; actor must call ctx.Response(resp).

For processes that do not run an actor system (CLI, API server, batch job), use the Client package to connect to the cluster and send messages by actor name. See Messaging.

Scheduling

Method	Purpose
`ScheduleOnce(ctx, msg, pid, delay, opts...)`	One-time delivery after `delay`.
`Schedule(ctx, msg, pid, interval, opts...)`	Recurring delivery at `interval`.
`ScheduleWithCron(ctx, msg, pid, cronExpr, opts...)`	Cron-based delivery.
`CancelSchedule(reference)`	Cancel by reference.
`PauseSchedule(reference)` / `ResumeSchedule(reference)`	Pause or resume a scheduled task.

Use WithReference(id) when scheduling if you need to cancel, pause, or resume. See Scheduling.

Events and observability

Method	Purpose
`Subscribe()`	Create an event-stream subscriber for system/cluster events. Returns `eventstream.Subscriber`; iterate via `Iterator()`.
`Unsubscribe(subscriber)`	Release subscriber; call to avoid leaks.
`TopicActor()`	Topic actor PID for PubSub (when `WithPubSub()` or cluster is enabled). Send Subscribe, Unsubscribe, Publish.
`Metric(ctx)`	Node-level metrics (actor count, mailbox sizes, throughput, uptime).

See Event Streams, PubSub, Observability.

Cluster and lifecycle control

Method	Purpose
`Kill(ctx, name)`	Stop an actor by name (local or remote).
`ReSpawn(ctx, name)`	Restart an actor; children are recreated with initial state.
`Name()`	Actor system name.

Dependency injection

Method	Purpose
`Inject(dependencies...)`	Register dependency types with the actor system after startup. Enables restoration during cluster topology changes and when creating actors on remote hosts. Must be called after `Start`.

Configuration options

Options are passed to NewActorSystem(name, opts...). Each option is documented in the source; this table groups them by concern.

Option	Purpose
Core
`WithLogger(logger)`	Custom logger. `WithLoggingDisabled()` for no-op.
`WithActorInitTimeout(d)`	Actor startup timeout.
`WithActorInitMaxRetries(n)`	Retries for actor init.
`WithShutdownTimeout(d)`	Total shutdown timeout (default: 3 min).
`WithAskTimeout(d)`	System-wide timeout for internal Ask round-trips (default: 5s).
`WithDefaultSupervisor(supervisor)`	Fallback supervisor for actors without explicit config.
Remoting & cluster
`WithRemote(config)`	Enable remoting. See Remoting.
`WithCluster(config)`	Enable clustering. See Clustered.
`WithTLS(info)`	TLS for remoting.
`WithoutRelocation()`	Disable actor relocation on node departure.
Extensions & capabilities
`WithExtensions(ext...)`	System-wide extensions. See Extensions and Dependencies.
`WithPubSub()`	Enable topic-based pub/sub.
`WithMetrics()`	OpenTelemetry metrics. See Observability.
Shutdown & eviction
`WithCoordinatedShutdown(hooks...)`	Shutdown hooks. See Coordinated Shutdown.
`WithEvictionStrategy(strategy, interval)`	Passivation when actor count exceeds limit.
Advanced
`WithPartitionHasher(hasher)`	Custom partition hasher for cluster placement.

Component relationships

The ActorSystem composes:

Remoting — TCP server/client; used when WithRemote is set.
Cluster — Membership, discovery, Olric DMap; used when WithCluster is set.
Event stream — In-process pub/sub; always present; topic actors when WithPubSub is set.
Scheduler — For ScheduleOnce, Schedule, ScheduleWithCron.
Extensions — Accessed via ctx.Extension(id) from actors.

Actors obtain the system via ctx.ActorSystem() (or ReceiveContext, GrainContext). Use it to spawn children, resolve actors, schedule, or access extensions. Do not store the ActorSystem in actor state; always obtain it from context.

Getting Started

Actor

Grains

Remoting

Cluster

Observability

Advanced

Architecture

Contribution

Reference

Meta Framework

Actor System

Role and responsibilities

Lifecycle

API surface

Spawning

Resolution and inspection

Messaging from outside

Scheduling

Events and observability

Cluster and lifecycle control

Dependency injection

Configuration options

Component relationships

Further reading

​Role and responsibilities

​Lifecycle

​API surface

​Spawning

​Resolution and inspection

​Messaging from outside

​Scheduling

​Events and observability

​Cluster and lifecycle control

​Dependency injection

​Configuration options

​Component relationships

​Further reading

Role and responsibilities

Lifecycle

API surface

Spawning

Resolution and inspection

Messaging from outside

Scheduling

Events and observability

Cluster and lifecycle control

Dependency injection

Configuration options

Component relationships

Further reading