Skip to content

Quickstart

This walks through launching a Cresco fabric and connecting a client. It assumes you have built the agent jar.

The shared environment

The launch scripts source run/cresco.env, which fixes the values every node in one fabric must agree on:

Variable Purpose
JAVA_HOME, PATH JDK 21
AGENT_JAR the staged agent-1.3-SNAPSHOT.jar
CRESCO_DISCOVERY_SECRET_GLOBAL / _REGION / _AGENT join secrets — a node presents the secret for the tier it joins
CRESCO_SERVICE_KEY shared symmetric key that authenticates agent traffic; every node in the fabric must match
CRESCO_XMX JVM heap

1. Start a global controller

A global controller is also its own region and agent, so a single one is a complete, self-contained fabric.

cd run
./run-global.sh

This launches region=global-region agent=global-controller with:

Port Service
32005 TCP discovery listener
32010 embedded ActiveMQ broker
8282 wsapi — the secure WebSocket endpoint clients connect to (wss://host:8282)
8080 Felix console / HTTP

Under the hood it sets -Dis_global=true -Denable_wsapi=true plus the discovery secrets and service key.

2. Attach a region (optional)

A regional controller runs its own broker and federates up to the global via a broker-to-broker bridge. On the same host it uses non-default ports to avoid clashing with the global:

./run-region.sh          # region=edge-region agent=edge-controller -> global@127.0.0.1

Key flags: -Dis_region=true -Dglobal_controller_host=127.0.0.1 -Dnetdiscoveryport=32015 -Dbroker_port=32020. The agents in this region connect to its broker (32020), and the region bridges to the global.

3. Attach a plain agent (optional)

A plain agent runs no broker; it connects directly to a controller's broker.

./run-agent.sh           # region=global-region agent=agent-001 -> regional controller@127.0.0.1

Key flags: -Dis_agent=true -Dregional_controller_host=127.0.0.1 -Dregional_controller_port=32005.

Two-node helper

run/launch_2node.sh brings up a global + a second node in one step for quick testing.

4. Connect a client

Clients connect to the global controller's wsapi at wss://host:8282 using the service key.

from pycrescolib.clientlib import clientlib

client = clientlib("localhost", 8282, "<CRESCO_SERVICE_KEY>")
if client.connect():
    # list the mesh
    print(client.get_global_controller().get_agent_list())
    client.close()

CrescoClient client = new CrescoClient("localhost", 8282, "<CRESCO_SERVICE_KEY>");
client.connect();
System.out.println(client.getAgents().getAgentList());
client.close();

See the Java and Python client references for the full API, and Plugin Actions for everything you can invoke.

5. Shut down and reset

./stop.sh                       # or: pkill -9 -f agent-1.3-SNAPSHOT.jar
rm -rf run/cresco-data run/nodes   # wipe state before the next run

Where to go next