Skip to main content

Quant0-agent Configuration

The q0-agent runs locally in your environment and provides the connection between your application and Quant0.

For most deployments, you only need to:

  1. Enroll the agent.
  2. Configure the agent credentials.
  3. Start the agent.
  4. Verify that the agent is healthy.

Prerequisites​

Before configuring the agent, make sure you have:

  • A Quant0 organization
  • Permission to enroll an agent
  • A valid enrollment token
  • Access to the environment where the agent will run

Enroll the Agent​

Use your Quant0 enrollment token to register the agent:

q0-agent enroll --token eet:... --gateway https://api.quant0.io

The enrollment process provides the agent with the credentials required to communicate with Quant0.

Keep these credentials private and do not commit them to source control.

Configuration​

The agent can be configured using environment variables.

Required​

VariableDescription
Q0_AGENT_IDThe ID assigned to your agent
Q0_AGENT_CREDENTIALThe credential assigned during enrollment

Optional​

VariableDefaultDescription
Q0_GATEWAY_URLhttp://localhost:5100Quant0 gateway address
Q0_WORKLOAD_ADDR127.0.0.1:9595Local address used by the agent

For most installations, the default Workload API address does not need to be changed.

Start the Agent​

Start the agent in the foreground:

q0-agent run

For server environments, you can install it as a system service:

sudo q0-agent service install
sudo systemctl enable --now q0-agent

Verify the Agent​

After starting the agent, check its health:

curl http://127.0.0.1:9595/healthz

A healthy agent returns:

{
  "status": "ok"
}

You can also check the agent status:

curl http://127.0.0.1:9595/status

The status information can help you confirm that the agent is connected and ready.

Docker Deployment​

The agent can also run as a Docker container.

docker run -d \
  --name q0-agent \
  --network host \
  -e Q0_AGENT_ID="$AGENT_ID" \
  -e Q0_AGENT_CREDENTIAL="$EAC" \
  -e Q0_GATEWAY_URL="http://localhost:8082" \
  -e Q0_WORKLOAD_ADDR="127.0.0.1:9595" \
  q0-agent:demo

After starting the container, verify:

curl http://127.0.0.1:9595/healthz

Docker Desktop​

On macOS or Windows Docker Desktop, use a mapped port:

docker run -d \
  --name q0-agent \
  -e Q0_AGENT_ID="$AGENT_ID" \
  -e Q0_AGENT_CREDENTIAL="$EAC" \
  -e Q0_GATEWAY_URL="http://host.docker.internal:8082" \
  -e Q0_WORKLOAD_ADDR="0.0.0.0:9595" \
  -p 9595:9595 \
  q0-agent:demo

Production Recommendations​

For production deployments:

  • Run the agent close to the application that uses it.
  • Keep the agent's local endpoint private.
  • Do not expose the agent publicly.
  • Store agent credentials securely.
  • Do not commit agent credentials to source control.
  • Use a separate agent for each application environment when appropriate.

The default local endpoint is:

127.0.0.1:9595

Troubleshooting​

Agent does not start​

Check that:

  • Q0_AGENT_ID is configured.
  • Q0_AGENT_CREDENTIAL is configured.
  • The configured gateway is reachable.
  • Port 9595 is available.

Agent is not healthy​

Check:

curl http://127.0.0.1:9595/healthz

Then inspect:

curl http://127.0.0.1:9595/status

Enrollment fails​

Make sure:

  • Your enrollment token is valid.
  • The token has not already been used.
  • The gateway address is correct.
  • Your organization has permission to enroll the agent.

Next Steps​

Once the agent is running and healthy, configure your Quant0 SDK or application to use the local agent.

Your application should communicate with the local agent rather than exposing the agent directly to external traffic.