Python
The Python binding gives you Session and Host with Python values over ctypes (glowcap). Runtime.open holds one Host and the transports you install, and runtime.connect picks the one that matches the locator. The transport modules include glowcap.iroh, glowcap.onion, glowcap.relay, and glowcap.tcp. See the installation options.
For complete client and server programs, start with the package quick start. Combine a transport tab with the common call or serving code beneath it. Keep imports at the top of your file and put the asynchronous code inside async def main(), called by asyncio.run(main()).
The WebRTC tab needs a signaling object supplied by your application. It carries offers, answers, and candidates between the peers.
The same round-trip
This is the Start building round-trip in Python. fetch and send start the inbound loop on demand, so a client that only makes calls never needs serve.
noise-tcp
from glowcap import Runtime, tcp
# Same TCP sockets as keyed dialing; Noise_XK seals the CapTP stream.
peer_key = "<64 lowercase hex characters from the server>"
partner = tcp.noise.locator(peer_key, "127.0.0.1", 9099)
async with Runtime.open(providers=[tcp.provider()]) as runtime:
iroh
from glowcap import Runtime
from glowcap.iroh import IrohConfig, Reachability, locator, provider
# DISCOVERY resolves a bare iroh node ID without an address hint.
node_id = "<64 lowercase hex characters from the server>"
partner = locator(node_id)
async with Runtime.open(
providers=[provider(IrohConfig(Reachability.DISCOVERY))]
) as runtime:
webrtc
from glowcap import Runtime
from glowcap.webrtc import SignalingAuthority, locator, provider
# Your signaling carries the offer and each candidate to the peer the locator
# names, over a path you already hold, such as an OCapN capability both peers
# can reach, and brings the answer and the peer's candidates back.
signaling: SignalingAuthority
partner = locator("<64 lowercase hex characters from the peer>")
async with Runtime.open(providers=[provider(signaling)]) as runtime:
noise-relay
from glowcap import Runtime, relay
# Noise_XK seals the CapTP stream end to end through the relay.
peer_key = "<64 lowercase hex characters from the server>"
relay_url = "wss://relay.example/relay"
partner = relay.noise.locator(peer_key, relay_url)
async with Runtime.open(providers=[relay.provider(relay_url)]) as runtime:
onion
from glowcap import Runtime, onion
# glowcap starts no Tor; point the provider at an existing SOCKS endpoint.
partner = onion.locator("<56-character onion service id>")
async with Runtime.open(
providers=[onion.provider(onion.OnionConfig(socks="/run/tor/socks"))]
) as runtime:
keyed-tcp
from glowcap import Runtime, tcp
# Key designator, cleartext CapTP. Partners dial the public key; the host:port is a hint.
peer_key = "<64 lowercase hex characters from the server>"
partner = tcp.keyed.locator(peer_key, "127.0.0.1", 9099)
async with Runtime.open(providers=[tcp.provider()]) as runtime:
keyed-relay
from glowcap import Runtime, relay
# The key names the peer; the hint names the relay that can reach it.
peer_key = "<64 lowercase hex characters from the server>"
relay_url = "wss://relay.example/relay"
partner = relay.keyed.locator(peer_key, relay_url)
async with Runtime.open(providers=[relay.provider(relay_url)]) as runtime:
tcp
from glowcap import Runtime, tcp
# Plain TCP uses a cleartext host and port.
partner = tcp.locator("127.0.0.1", 9099)
async with Runtime.open(providers=[tcp.provider()]) as runtime:
Fetch the greeter and call its greet method:
async with await runtime.connect(partner) as session:
greeter = await session.fetch("greeter") # a capability this peer published
reply = await session.send(greeter, "greet", ["world"])
print(reply)
The iroh tab needs the optional transport library and a node id that iroh discovery can resolve.
Listen
tcp.listen binds a port and accepts sessions that publish and serve. tcp.keyed.listen and tcp.noise.listen take a 32-byte seed so the listener keeps the same key across restarts. iroh.listen binds a node id instead.
noise-tcp
import os
from glowcap import Argument, tcp
# Same bind as keyed-tcp; Noise_XK seals every accepted CapTP stream.
# Persist the 32-byte seed to keep the same key.
seed = os.urandom(32)
async with await tcp.noise.listen("127.0.0.1", 9099, seed=seed) as server:
iroh
from glowcap import Argument
from glowcap.iroh import IrohConfig, Reachability, listen
# This listener is named by its node id. Partners can dial it from anywhere.
async with await listen(IrohConfig(Reachability.DISCOVERY)) as server:
noise-relay
import os
from glowcap import Argument, relay
# Register this key at the relay; Noise_XK seals every accepted CapTP stream.
seed = os.urandom(32) # load durable secret bytes in a real service
async with await relay.noise.listen(
"wss://relay.example/relay",
"wss://relay.example/register",
seed=seed,
) as server:
onion
from glowcap import Argument, onion
# glowcap starts no Tor. Name an already-running daemon's SOCKS (and control to host).
async with await onion.listen("/run/tor/socks", control="/run/tor/control") as server:
service_key = server.service_key # persist securely to restore this service
keyed-tcp
import os
from glowcap import Argument, tcp
# Key designator, cleartext CapTP. Persist the 32-byte seed to keep the same key.
seed = os.urandom(32)
async with await tcp.keyed.listen("127.0.0.1", 9099, seed=seed) as server:
tcp
from glowcap import Argument, tcp
# Plain TCP binds the host and port you choose.
async with await tcp.listen("127.0.0.1", 9099) as server:
Publish the greeter and answer incoming calls:
print(server.uri) # hand this locator to partners
def greet(verb: str | None, args: list[Argument]) -> str:
if verb != "greet":
raise LookupError("no such method")
if len(args) != 1 or not isinstance(args[0], str):
raise TypeError("bad invocation")
return f"Hello, "
server.host.publish("greeter", greet)
async for accepted in server:
async with accepted as session:
await session.serve()
Async
The binding uses asyncio. await session.send(...) returns the reply, and session.serve() runs the inbound loop as a background task until the session closes. Concepts covers the CapTP ideas.
Actors
session.spawn and session.publish take a behavior(verb, args) callable. If the callable raises, the caller’s promise breaks with the exception’s message. To let a third peer reach an actor directly through an introduction (Concepts explains handoffs), call publish on the Host from server.host.
The complete API lives in the Python binding README, and the rooms chat client shows a complete application.