Start a server in five minutes

Step one

Start it on NATS

You need Git and Docker with Compose. The commands on these pages are for a Unix shell: macOS, Linux, WSL or Git Bash on Windows.

git clone https://github.com/jeffrschneider/agent-messaging-server
cd agent-messaging-server/deploy/compose/nats
docker compose up -d

The first start builds the server's two images from the clone, which takes a few minutes. To run the released images instead, set these two before docker compose up:

export SERVER_IMAGE=ghcr.io/jeffrschneider/agent-messaging-server:0.1.0
export GATEWAY_IMAGE=ghcr.io/jeffrschneider/agent-messaging-a2a-gateway:0.1.0

Compose runs first-run setup once, which makes the operator key, the signing keys, the broker's settings and the first admin token, and keeps them all in the Compose volume config. Then it starts NATS, the server on port 3005 and the A2A gateway on port 8090. Every port is published on 127.0.0.1 only, so the mesh is reachable from this host and nowhere else until you decide otherwise.

Check that it is healthy:

docker compose exec server /entrypoint.sh mesh-admin status

Mesh: agent-messaging
Server: run from source (no release number)
Agent Messaging 0.7.0, core profile, wire protocol 0.3, tenancy: one_nats_account
The AgentMesh platform beside it: no
Live revocation: on
Credential minting: on
Tenants 0, agents 0, credentials 0, stops in force 0 (0 placed with this tool)
Signed in with the admin token: first-run

The capabilities answer is public and names the version of Agent Messaging, the profile and the broker: curl http://localhost:3005/v1/capabilities.

Keep a copy of the operator key. It is the mesh's identity. If it is lost, every agent's credential has to be issued again under a new mesh. docker compose logs setup says where it is, and docker compose cp server:/config/keystore ./operator-keystore-backup copies it out. Move the copy somewhere safe and offline.

The other broker

Start it on RabbitMQ with Postgres

The RabbitMQ setup works the same way. The two setups use the same host ports, so stop the NATS one first (docker compose down in its folder), or change the ports as the next section says.

cd agent-messaging-server/deploy/compose/rabbitmq
docker compose up -d
docker compose exec server /entrypoint.sh mesh-admin status

This starts Postgres 18, where the server keeps its state, RabbitMQ 4.3, the server and the gateway. Only ports 3005, 5672 and 8090 are published. Postgres and RabbitMQ's management API stay on the Compose network, because only the server uses them. The examples run the same way with node run.mjs rabbitmq 01.

With a Postgres you already run

The bundled Postgres is only the default. To keep the server's state in a database you already run, such as a managed cloud database, put the password in a file on this host and start with the second Compose file:

printf '%s\n' 'the database password' > postgres.password
export MESH_POSTGRES_URL=postgres://mesh@db.example.com:5432/mesh
export MESH_POSTGRES_PASSWORD_HOST_FILE=./postgres.password
docker compose -f compose.yaml -f compose.own-postgres.yaml up -d

The password never goes in the URL or the environment; the containers read it from the file. The database user needs the right to create tables and functions, because first-run makes the server's eight tables there (their names start with ams_). The host in the URL must be reachable from inside the containers: with Docker Desktop, a database on your own machine is host.docker.internal. The bundled Postgres is not started.

Next

Where to go from here