AgentSpaces for Ruby

AgentSpaces lets programs coordinate through shared, replicated memory with no broker or scheduler in the middle. This part walks you from an empty directory to two Ruby processes that share work, survive a kill, and take part in a vote.

A few words come up on every page:

• A peer is one running process in the fleet. It holds its own Ed25519 identity and signs what it writes.
• A group is the set of peers that trust each other. They share a founding text or a signed founding document.
• A space is a named, replicated store inside a group, such as orders.
• An entry is a typed value in a space. In Ruby it is a Data class.
• A lease is how long a value lives, or how long a peer may hold an entry it took.
• A take claims one entry for one peer. If that peer dies, the lease lapses and the entry reappears.
• An agent is a class whose methods take, watch, or vote on entries. The fleet sees it through its published card.
• A capability is a fleet service a peer advertises, such as vote counting or a fleet-wide average.

You need Ruby 3.3 or newer, built against OpenSSL 1.1.1 or newer. The macOS system Ruby (2.6, on LibreSSL) cannot run the gem. Install a current Ruby with Homebrew, rbenv, or mise.

Homebrew installs it as /opt/homebrew/opt/ruby/bin/ruby, so put that directory first on PATH. The agentspaces gems are not yet on RubyGems, so run them from a clone of agentspaces-rb. The core gem needs no native extension and no other gem at run time beyond logger.

doctor runs every crypto primitive the peer uses and names the OpenSSL build. A good result ends in five ok lines:

For a Bundler project, point the Gemfile at the clone with a path: option until the gems are published.

A Ruby peer dials out and does not listen, so it needs a seed: any peer with a listener that the others dial first. The Node service host is a seed with no code. Build it from a clone of agentspaces-typescript: run npm install and npm run build at the root, then npm run build in packages/node.

The dev-local profile signs every frame over plain loopback TCP and encrypts nothing. Use it on a laptop, never on a shared network. Production fleets use mtls, and a Ruby peer reaches them through a tls://host:port seed.

AgentSpaces::Entry.define makes a Data class and registers it under a schema name. The schema name is what every language on the wire agrees on.

• Members are snake_case in Ruby and travel under camelCase wire names, so order_id is the Java record component orderId.
• A field type is String, Integer, Float, :boolean, :bytes, :instant, an Array of one type such as [String], Hash, Object, or another entry class.
• A Float field widens an Integer on assignment, which is what a Java double needs.
• An unknown member raises ArgumentError and names the fields the entry has.

Entries are ordinary Data values, so ==, inspect, and pattern matching (in { winner: "yes" }) work as usual.

An agent is a class that includes AgentSpaces::Agent. The agent macro names it. Each verb macro, such as take, binds to the next def in the class, and the method's return value is the next entry in the space.

• take Order, space: "orders", lease: "30s" takes each Order written to orders and holds it for 30 seconds while ship runs.
• AgentSpaces.serve starts a peer, yields it so you can bind agents, and blocks until SIGINT or SIGTERM. Then it unbinds, drains, and closes.
• AgentSpaces.start starts a peer and yields it. Use it for scripts that write, read, and exit.
• orders << value writes an entry, and orders.read(Shipment, timeout: "30s") waits for one to appear.

Start the seed, then run the file twice in two terminals. The first instance only ships. The second also writes an order, prints the shipment, and exits.

Either instance can take the order, because both run the same agent. To watch a take recover from a crash:

1. Add puts "shipping #{order.order_id}" and sleep 10 at the top of ship, written as a multi-line def.
2. Start both instances, so the second writes the order.
3. Run kill -9 on whichever instance prints shipping.
4. If you killed the first, the second prints the shipment. If you killed the second, the first prints shipping o-1 again once the 30-second lease lapses.

The live peer finishes the order without a restart, because the lease on the take lapsed and the entry reappeared.

take is exclusive: one peer gets each entry. notify runs a method on every matching entry that appears, without taking it. bid prices an entry before the take; when several peers claim the same entry, the claim with the lowest bid takes it. The agent below, from the core test suite, uses all three. A macro can also take a block in place of a def, as bid does here.

• where: { priority: 1.. } limits the take to entries whose priority is at least 1. A Range, an Array, a plain value, or a clause string such as "priority>=3" all work.
• A notify method that returns nil writes nothing.
• Binding the class publishes its card, so other peers can find the research and audit actions.

• Key features covers the macros, the Space API, the two ways into a fleet, and the Rails, RubyLLM, and MCP gems.
• Examples runs three complete programs, two of them with no network.
• The developer guide's Ruby section maps Ruby onto the Java chapters. Read leases and cards there for depth.
• The architecture guide explains how the replicated space and the claim lattice work.

The pieces in this part are specific to Ruby: the class macros, the Ruby idioms in the Space API, the two runtimes, and the hosts and AI gems.

Every verb is a macro whose options are the Java annotation attributes in snake_case. The macro records a clause, and the next def in the class becomes the method that clause calls.

space_ref and capability declare readers that the binder fills with a space or a capability client at bind time.

A method can return one entry, an Array of entries, AgentSpaces::Tagged.of(entry, region: "eu") for a tagged result, an AgentSpaces::Motion to open a vote, or nil for no result. A method that raises leaves its take to lapse, and the binder counts the failure.

Every macro checks its options when the class body evaluates. A misspelled option, a duration that does not parse, a where: key that names no field, or a macro with no def below it raises AgentSpaces::DefinitionError with the file and line. For scripts and tests, AgentSpaces.agent("name") { take(...) { |order| ... } } builds an agent from a block.

peer.space("orders") returns a space. Its verbs take an entry class and keyword options, and some take a block.

• write and << write an entry. write also takes lease: and tags:.
• read waits for a matching entry, all returns every match now, and watch calls a block on each event.
• take with a block completes the take with the block's result. Without a block, it returns a Taken; call complete(result) on it when you finish.
• A Regexp or a lambda in where: runs on this replica only. A Regexp runs under a timeout.

AgentSpaces.start and AgentSpaces.serve accept three forms of configuration:

• Keyword shorthand for one group: group:, founding:, seeds:, spaces:, and join: for a group founded with a signed document.
• A path to a YAML file, or YAML text.
• A Hash in the same shape.

The YAML is the same agentspaces: subtree the Spring starter, Micronaut, Groovy, and the Node host read, in kebab-case or snake_case keys. The Ruby peer dials out only, so it logs once and ignores the listener keys bind, advertise, and roles.

On a network, the peer behaves as follows:

• A tls://host:port seed dials TLS 1.3 and attests the remote end with its identity key. It has been tested against a Java seed that requires attestation.
• A ws:// or wss:// seed dials WebSocket with the aspace.1 subprotocol (default path /aspace). An http:// or https:// seed runs the long-poll exchange (default path /aspace/h) for networks that pass only HTTP.
• On a connection the transport cannot attest (tcp, ws, http), the peer runs session attestation with a member that offers it: one signed hello each way, then a shared key tags every frame.
• A plain tcp, ws, or http seed on a non-loopback host is refused unless the configuration sets allow_plain: true.
• A lost connection re-dials every 5 seconds for 10 minutes, failing over across the seeds.
• keystore: keeps the identity in peer.key and peer.pub, the layout a Java peer reads. Without it, each run gets a fresh identity.
• A forked child closes the connections it inherited. Using an inherited peer raises AgentSpaces::ForkError; call AgentSpaces.after_fork in the child.

See security in the developer guide for the profiles and keys.

Ruby has two ways into a fleet, and both run the same agent classes.

The MRI peer has no listener, so a Ruby process cannot be a seed. It also has no quic, dtls, udp, or webrtc dialer, no content swarm, and no gossip-learning learner. Use the Node host as the seed, and the JRuby face or a Java peer for the ordered verbs. Binding an ordered_take agent on MRI raises EngineUnsupported and names the JRuby face.

On JRuby, Fleet.start takes the starter's whole key set, including bind:

The face writes a Java interface for each agent shape and a record for each entry the classpath lacks, compiles them with the JDK's compiler, and binds a proxy. An ordered log still needs a Java-side voter, as described in ordered takes.

A capability is a fleet service a peer advertises. The core gem includes clients for the ones Java providers serve, under AgentSpaces::Capabilities, all over one pipe multiplexer, Pipes.new(peer).

• Votes. AgentSpaces::Votes.propose, cast, tally, and decision run over a space and need no provider. The ballot and on_decision macros use them.
• Aggregate. Push-sum averages and rosters across the fleet: start(epoch, value), run, await_settled, and on_estimate.
• Semantic. query(text) ranks the cards this peer has cached, and remote_query(text) asks the fleet.
• RemoteActions. actions(peer) lists the actions every card declares, and invoke writes the input and waits for the correlated result.
• OrderedLog. A client of the Raft ordered log: space.take(Type, through: log) claims through it. The voters run in Java or TypeScript.
• DataQueryClient and AssetInvocations. The agent side of the connector protocol.

The council worker of the cross-language example sets up three of them:

A remote action call, from the capability tests:

The developer guide's capabilities chapter explains each service.

agentspaces-rails is a Railtie. It reads config/agentspaces.yml through config_for, so ERB and environments work. The file holds the shared agentspaces: subtree:

• Put agent classes in app/agents. Zeitwerk loads them.
• Run them with bin/rails agentspaces:work, for example as a Procfile line. It binds every agent class and serves until SIGTERM. bin/rails agentspaces:config prints the configuration it reads.
• Write from controllers and jobs with AgentSpaces::Rails.peer.space("orders") << order. The web process starts its peer lazily, once per process.
• A forked Puma, Unicorn, or Passenger worker starts its own peer.
• A fleet outage raises AgentSpaces::Unavailable when a request needs the fleet. It never stops the application from booting.
• write.agentspaces, take.agentspaces, and complete.agentspaces notifications carry the space, the schema, and the entry id.

agentspaces-ruby_llm turns every action on the fleet's cards into a RubyLLM::Tool. The tool's parameters come from the entry class this process registered for the action's input schema, so a model sees typed fields. Pass them to a chat with RubyLLM.chat.with_tools(*tools).

AgentSpaces::Lease.keepalive renews a take's lease on a timer while its block runs. Wrap a long model call inside a take body with it, so the entry stays yours while the model thinks. Inside a take body it finds the current take on its own.

agentspaces-mcp serves the same actions as MCP tools on the official Ruby SDK, over stdio or Streamable HTTP. For stdio, open the server with MCP::Server::Transports::StdioTransport.new(server).open.

The core gem ships an agentspaces executable in gems/agentspaces/exe.

check needs no fleet. Point it at files that define classes and start no peer, such as an app/agents directory:

A mistake prints as file:line: error: message, for example fulfiller.rb:8: error: take has no option :lese; accepted: space, group, lease, ..., and the command exits 1.

The first two examples run three in-memory fleets inside one Ruby process, with no seed, no network, and no model key. The third drains a Java coordinator's tasks over TCP.

This example shows an agent on one peer finishing work that another peer writes, and a take that reappears after its holder dies. AgentSpaces::Testing::Network.fleet builds connected in-memory peers, and TestClock lets the test move time forward.

The agent signs as its own subordinate key (renewing_subordinate), so every peer stores its work as attested by that agent. The method body is where a model call goes: whatever it returns is the next entry.

The second half takes a ticket by hand, closes the peer before it completes, and moves the clock past the lease:

Run both from the agentspaces-rb clone:

The full source is gems/agentspaces/test/readme_examples_test.rb in agentspaces-rb.

This example shows the ballot macro. Two reviewers answer a proposal, and a third peer reads the decision once the quorum of two closes.

• prefix: "release:" limits the ballot to proposals whose id starts with release:.
• A ballot method that returns nil abstains.
• until_true is the test's polling helper. It retries the block until it returns a value or ten seconds pass.

To act on the result in an agent, add an on_decision space: "votes", prefix: "release:" macro above a method that receives the decision. The same test file runs this example. Read votes in the developer guide for quorums and tallies.

This example shows a Ruby peer working beside Java. The Java coordinator of the research fleet publishes six ResearchTask entries and waits for six Finding entries. The Ruby worker takes each task under the same claim rules as a Java worker.

The entries name the Java records' schemas, so both sides read the same values:

Build the Java side first with mvn install in the agentspaces clone: the library is on Maven Central, but the example modules are not published. Then start the coordinator from the agentspaces Maven root, and the worker from agentspaces-rb/examples/ruby-fleet:

The worker prints each task it takes, and the coordinator prints finding: topic-1 by rb-worker for each of the six. Pass tls://host:port in place of the address to reach a TLS seed.

The same directory holds council_worker.rb. It joins the Java CouncilFleet coordinator, takes its tasks, votes on its proposal, contributes to a push-sum average, and answers semantic queries. The comment at the top of the file gives both commands. The Python guide and TypeScript guide run the same coordinators from their languages.