Client Configuration

Client Configuration

Constructor

from archipelagopy import Client

client = Client(
    port=12345,                    # required: server port
    host="archipelago.gg",         # server hostname
    secure=True,                   # use encrypted connection (wss://)
    auto_reconnect=False,          # retry on disconnect
)

Parameters

Parameter	Type	Default	Description
port	int	(required)	The server port to connect to
host	str	"archipelago.gg"	The server hostname
ssl_context	SSLContext | None	None	Custom SSL configuration for encrypted connections. Most users can ignore this — a default is created automatically when secure=True
secure	bool	True	Use wss:// (encrypted) or ws:// (unencrypted). Use False for local servers
auto_reconnect	bool	False	Automatically retry the connection when the server disconnects or refuses the connection
websocket_kwargs	dict | None	None	Advanced: additional keyword arguments passed directly to websockets.connect(). See the websockets docs for available options

Usage patterns

Context manager (recommended)

The simplest way to use the client. async with automatically connects on entry and disconnects on exit:

import asyncio
from archipelagopy import Client

async def main():
    async with Client(port=12345) as client:
        await client.wait_closed()  # keep running until disconnected

asyncio.run(main())

async with is Python's way of managing resources that need cleanup. It ensures stop() is called even if an error occurs.

Manual start/stop

If you need more control over when the client connects and disconnects:

client = Client(port=12345)
await client.start()
# ... do work ...
await client.stop()

Waiting for shutdown

wait_closed() blocks your code until the client disconnects. You can optionally pass a task — the function will return when either the task finishes or the client disconnects, whichever happens first:

async def my_game_logic():
    while True:
        await asyncio.sleep(1)
        # ... your game logic here ...

async with Client(port=12345) as client:
    my_task = asyncio.create_task(my_game_logic())
    await client.wait_closed(my_task)

asyncio.create_task() starts a function running concurrently (in the background) within the same event loop. This lets your game logic and the client's network communication run at the same time.

Auto-reconnect

When auto_reconnect=True, the client automatically retries the connection in these cases:

• Connection refused: Retries with exponential backoff — the wait time starts at 2 seconds and doubles each attempt, capping at 60 seconds. Failed attempts older than 60 seconds are discarded from the backoff calculation.
• Server going to standby (GOING_AWAY): Retries immediately.
• All other disconnects: The client stops without retrying.

client = Client(port=12345, auto_reconnect=True)

SSL / Encryption

By default, connections use wss:// (encrypted WebSocket) with standard SSL settings. This works out of the box for the public Archipelago server.

For local development servers that don't use encryption:

client = Client(port=12345, host="localhost", secure=False)

For advanced use cases with custom certificates:

import ssl

ctx = ssl.create_default_context()
ctx.load_cert_chain("client.pem")
client = Client(port=12345, ssl_context=ctx)