Architecture

Golem is a set of services that store components, run agents, and route calls to them. The same services run in one process on a laptop or as separately scaled deployments in a cluster.

Open full-size image in a new tab.Open full-size image in a new tab.

The CLI and the local server

The golem binary contains the command-line interface and a complete local Golem. golem server run starts the registry service, the gateway, the shard manager, the component compilation service, and one executor in a single process, behind a built-in router. The lightweight golem-cli binary has the same commands without the server and connects to an existing deployment.

The local server keeps its data in SQLite databases and local files under the user’s data directory, so agents and deployments survive a server restart. golem server run --clean deletes that data and starts empty.

The gateway

The gateway, deployed as golem-worker-service, keeps no agent state and scales independently of the executors.

1. Route invocations. The gateway maps the agent’s identity to a shard, looks up the executor that owns that shard in the routing table published by the shard manager, and forwards the call to that executor.
2. Handle executor failure. When an executor is unreachable or reports that it no longer owns the shard, the gateway refreshes its routing table, waits for the agent to be recovered on the shard’s new owner, and retries the invocation.
3. Serve application surfaces. The gateway serves the agent operations of the REST API, the HTTP endpoints and routers an application defines, including the files they serve, and the application’s MCP servers.

Agent-to-agent calls use the same routing. An executor delivers a call directly when it owns the target agent and otherwise sends it through the gateway.

The registry service

The registry service stores accounts, applications, environments, components, deployments, plugins, tools, and policies. golem deploy uploads components to it. It keeps metadata in a relational database (PostgreSQL, or SQLite locally) and component WebAssembly files in blob storage. The gateway and the executors read component and deployment information from the registry.

Executors

An executor runs agents. Each agent is an instance of an agent type, running in its own WebAssembly sandbox, and the executor records its interactions with the outside world in the agent’s oplog. An executor removes waiting agents from memory and rebuilds them from their oplogs when the next event arrives; crashes and moves between executors use the same reconstruction path.

Shards and ownership

Every agent identity hashes to one of a fixed number of shards (1024 by default). The shard manager assigns shards to executors and rebalances them when executors join or leave.

Ownership is fenced. Each executor holds a lease on its assignment and renews it periodically. An executor whose lease lapses stops admitting new work for those shards, and the shard manager reassigns the shards of an executor that stops renewing. Each shard also carries an epoch that advances whenever it moves. An agent’s oplog records the epoch allowed to write to it, and indexed storage checks every write against that record atomically, so an executor that has lost a shard cannot append to the oplogs of its agents. The new owner recovers those agents by replaying their oplogs.

The shard manager runs in local mode (state in PostgreSQL or SQLite, exactly one instance) or distributed mode (state in etcd, any number of replicas with one elected leader). See Shard Manager for lease timing and failover behavior.

The component compilation service

Executors run components as native code compiled from WebAssembly. The registry service asks the component compilation service to compile each uploaded component, and the results are stored in blob storage shared with the executors, so an executor does not compile a component on first use.

Storage

The oplog is the source of truth for an agent’s state; cached agent metadata is rebuilt from it when needed. Executors that share shards need indexed storage they can all reach, which means PostgreSQL or Redis. See Persistence for details, including scheduler storage.

Local and distributed deployments

Agents, components, and the CLI behave the same in both. Golem Cloud runs the distributed form as a hosted service. To run it yourself, see Deployment, Docker, and Kubernetes.