Working with Socket Actors

A Socket Actor is the Pod-OS entity for running your software—anything that can open a TCP connection and exchange messages. Where an Evolutionary Neural Memory is a built-in Actor that stores and links data, a Socket Actor is a general-purpose Actor whose behavior you define. It is how you bring greenfield services, existing production systems, and AI/agentic workloads into an Actor Network.

Run any software as an Actor

Pod-OS supports several Actor types. Socket Actors are the most flexible because they impose almost no requirements on your code. If your program can:

1. Connect to a Gateway over a socket, and
2. Receive and respond to Messages,

then it can be a Socket Actor—regardless of language, framework, or age.

This makes Socket Actors a practical on-ramp for:

The base runtime image ships with the Pod-OS binaries only—no language toolchain is assumed at runtime. You bring your own executable (a committed binary or a container image); Pod-OS runs it and manages its lifecycle. See Socket Deployment Types for the two ways to package and ship that software.

How Socket Actors simplify your architecture

Socket Actors let you delete most of the "plumbing" that normally surrounds a distributed service. The platform provides it instead.

One communication model: Messages

All communication between Actors—with no exceptions—is a Message addressed as <actor>@<gateway>.<domain>. You do not choose between REST, gRPC, a message bus, and a queue for different interactions; there is a single addressing and delivery model for every Actor in the network, whether it is next to you or in another region. The Gateway handles routing, so your code never hard-codes hostnames or service-discovery logic.

Share-nothing by default

Each Actor owns its private state and reacts only to the Messages it receives. There is no shared memory, no lock coordination, and no cross-service database contention to design around. This removes entire categories of concurrency bugs and lets you reason about each Actor as an isolated unit with clear inputs and outputs. (See What is an Actor? for the underlying model.)

Location transparency

Because Actors are addressed by name and routed by the Gateway, the same message-sending code works whether the target Actor runs in the same pod, elsewhere in the cluster, or on an edge device in another country. You can move and scale Actors without changing application code.

The platform manages the lifecycle

When you deploy a Socket Actor, Pod-OS handles the operational concerns that would otherwise be bespoke infrastructure code:

• Startup — clones or pulls your software and starts the process.
• Registration — makes the Gateway aware of the Actor so Messages can be routed to it.
• Health — probes the Actor and reports its status to the Actor Network.
• Reconnection & supervision — the client reconnects with backoff across transient blips, and the Gateway supervises the Actor.

Your program is left to do one thing well: handle its Messages.

What every Socket Actor must get right

No matter how you deploy it, a Socket Actor is only "healthy" in the Actor Network when it does two things:

1. Register with its configured Gateway. The Gateway must be aware of the Actor before it can route Messages to it.
2. Answer health probes. Pod-OS health-checks a Socket Actor with a lightweight status handshake (StatusRequest → Status).

A passing Kubernetes probe is not the same as a healthy Actor. Accepting a TCP connection on :62312 only proves the process is listening. Actor Network health additionally requires Gateway registration and a reply to StatusRequest.

The Pod-OS SDK (the pod-os-go-client) does the heavy lifting here: connect with the client, then call RespondToHealthChecks(client) to install a handler that answers status probes automatically.

Next: Socket Deployment Types — the two ways to package and ship a Socket Actor, and when to use each.