What is a Gateway?
A Gateway is the entry point to Actor networks. A Gateway receives messages from the network and routes them to the correct destination inside or outside your network.
The Role of a Gateway
Every Pod-OS domain deployment deploys with one root Gateway "zeroth". When a client — whether it is a web application, a mobile app, an IoT sensor, or another Actor or Gateway — wants to communicate with your system, it communicates using messages, via Gateway(s).
The Gateway is responsible for:
- Receiving inbound connections from external clients over standard protocols (TCP, WebSocket)
- Authenticating and authorizing the source of the message
- Routing messages to the correct Actor or other Gateways based on addressing
- Managing the lifecycle of connections and child Actors, including reconnection, start/stop, and failover.
Gateways Are Actors
A Gateway is not a special infrastructure component that sits outside your system. It is an Actor — it follows the same rules as every other Actor in the network:
- It has its own isolated state
- It communicates exclusively through messages
- It can be deployed, scaled, and managed like any other Actor
- It can be moved to a different node without changing the rest of the system
This is a powerful property. Because Gateways are Actors, you do not need a separate mental model for "infrastructure" versus "application logic." The same patterns, tools, and management approaches work for everything.
Gateway Addressing
Every Gateway has a fully-qualified name that uniquely identifies it in the network. For example:
skills.pod-os.com
Format: {{gateway-name}}.{{domain}}; extendable into namespaces: sub-gateway.gateway-domain.domain, etc.
This name is used for both external and internal actor-network routing.
Gateways Form Networks
Your Pod-OS deployment can have multiple Gateways. Common reasons to deploy more than one:
| Scenario | Why Multiple Gateways |
|---|---|
| Multi-region | Place Gateways close to your users for lower latency |
| Isolation | Separate public-facing traffic from internal service-to-service traffic |
| Scaling | Distribute inbound load across multiple entry points |
| Multi-tenant | Give each tenant their own dedicated Gateway |
| Sharding, Replication | Distribute the same message in multiple locations. |
Each Gateway is independently deployable and configurable, but they all participate in the same Actor network and can route messages to any Actor in the system (controlled by permissions).
Gateways also can connect to Actors and Gateways outside your deployment. For example, if you needed to query a publicly-available or federated Wikipedia Actor, your local Gateway already knows how to route the message based on routing connections. As a developer, you fire and forget.
What Sits Behind a Gateway?
Behind a Gateway you will find the rest of your Actor network: Actors that perform computation, Actors that store data (like Evolutionary Neural Memory), and Actors that vend your software (legacy and greenfield). The Gateway only needs to know how to communicate with them via socket messages and how to manage them (autostart, throttling, etc.).
This is the power of the Actor Model: each piece of the system is decoupled from every other piece. The Gateway routes messages; the destination Actors decide what to do with them.
Next: What is an Actor? — learn about the fundamental building block behind Gateways and everything else in Pod-OS.