Your First Agent

Agents are on-prem containers that connect to GNETiX via an outbound WebSocket relay. They receive structured A2A tasks from the Director, execute MCP tools against your infrastructure, and return results. Agents run no LLM -- they are pure tool executors.

No inbound firewall rules are required. Agents initiate outbound WebSocket connections to the GNETiX backend, so they work behind NAT and corporate firewalls.

Register an agent

Step

Navigate to the Agents page

In the GNETiX portal, go to Agents in the sidebar navigation.

Step

Create a new agent

Click Create Agent. Give it a descriptive name (e.g., dc-west-agent-01) and an optional description of the infrastructure it will manage.

Step

Copy the credentials

After creation, the portal displays the Agent ID and a call-home token. Copy both values immediately.

The call-home token is shown only once. It is stored as a bcrypt hash in the database and cannot be retrieved later. If you lose it, you must generate a new token.

Configure the agent container

The agent container only needs the call-home token to connect:

docker run -d \
  --name gnetix-agent \
  -e CALL_HOME_TOKEN=<your-call-home-token> \
  ghcr.io/gnetix-ai/gnetix-agent:latest

On startup, the agent authenticates with GNETiX using its call-home token and establishes a persistent WebSocket connection.

The agent connects to api.gnetix.ai by default. If you need to point it elsewhere (e.g. a self-hosted instance), set the SAAS_URL environment variable.

Verify connectivity

Once the agent container is running, go back to the Agents page in the portal. Your agent should show an Online status indicator, confirming the WebSocket relay connection is active.

You can also check the agent container logs:

docker logs gnetix-agent

A successful connection looks like:

INFO:  Connecting to wss://api.gnetix.ai/ws/relay
INFO:  Relay connected — agent dc-west-agent-01 online
INFO:  Waiting for tasks...

Next steps

Your agent is connected but has no tools yet. To give it capabilities:

Build an MCP server with the tools you need
Register the MCP server in the portal
Assign the MCP server to this agent
The Director will automatically discover and use the agent's tools when processing user requests

On this page