{
  "schemaVersion": "1.0",
  "title": "Run the Hermes Agent connector quickstart",
  "description": "In this tutorial, you will start the repository's deterministic Hermes product path and route one signed cap:hermesagent:qualification:models action from aipctl, through product-neutral aipd, to the standalone aip-host-hermes-agent process.",
  "canonical": "https://getaip.org/docs/connectors/hermes-agent/getting-started/quickstart",
  "route": "/docs/connectors/hermes-agent/getting-started/quickstart",
  "source": "docs/connectors/hermes-agent/getting-started/quickstart.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/hermes-agent/getting-started/quickstart.md",
    "txt": "/docs/download/connectors/hermes-agent/getting-started/quickstart.txt",
    "json": "/docs/download/connectors/hermes-agent/getting-started/quickstart.json",
    "pdf": "/docs/download/connectors/hermes-agent/getting-started/quickstart.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Run the Hermes Agent connector quickstart\ndescription: >-\n  Route one signed models read through the deterministic Hermes standalone-host\n  topology\nkind: tutorial\naudience: application-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: hermes-agent\n---\n\n# Run the Hermes Agent connector quickstart\n\nIn this tutorial, you will start the repository's deterministic Hermes product\npath and route one signed `cap:hermes_agent:qualification:models` action from\n`aipctl`, through product-neutral `aipd`, to the standalone\n`aip-host-hermes-agent` process.\n\nThe provider is a controlled local fixture. You do not need a Hermes Agent\ndeployment, model provider, or credential, and the procedure does not call an\nexternal service. This is a learning exercise, not a production deployment or\nqualification run.\n\n## What you will verify\n\nBy the end, you will have observed:\n\n- source-derived local images and connector release identities;\n- registry admission before the Hermes host starts;\n- one healthy, tenant-bound host with endpoint ID `qualification`;\n- one signed, low-risk models read returning the deterministic fixture model;\n- the same durable action state through a second `aipd` replica;\n- cleanup limited to the named tutorial Compose project.\n\nYou will not test chat, streaming, a provider mutation, approval, operator\nexecution, delegation, MCP, restart, failover, an external model, or a\nproduction security boundary.\n\n## Prerequisites\n\nYou need:\n\n- a clean `aip-core` checkout at the reviewed source revision;\n- Docker Engine, Docker Compose v2, and BuildKit;\n- enough CPU, memory, and disk for the source-owned fleet images;\n- TCP port `18443` free on loopback;\n- a POSIX-compatible shell and `lsof`.\n\nRun every command from the `aip-core` repository root. Image preparation builds\nthe gateway, control plane, fixtures, and all product hosts, so the first run\ncan take substantially longer than a single native binary.\n\nThe Compose project name is fixed as `aip-connector-fleet-qualification`. Do\nnot continue if another investigation or retained qualification run owns that\nproject or its volumes.\n\n## 1. Verify the source boundary\n\nSet and verify the reviewed revision:\n\n```sh\nexport AIP_SOURCE_REVISION=97be86e9efedf07ecf1783b03800f683f107fb04\n\ntest \"$(git rev-parse HEAD)\" = \"$AIP_SOURCE_REVISION\"\ntest -z \"$(git status --porcelain)\"\n```\n\nBoth checks must exit with status `0`. Use a separate clean checkout if you\nhave local work; do not hide or discard changes to satisfy the preflight.\n\nConfirm that Docker and Compose are available:\n\n```sh\ndocker info >/dev/null\ndocker compose version\n```\n\nConfirm that the fixed edge port is unused:\n\n```sh\nif ! command -v lsof >/dev/null; then\n  echo \"lsof is required for the port preflight\" >&2\n  exit 1\nfi\n\nif lsof -nP -iTCP:18443 -sTCP:LISTEN | grep -q .; then\n  echo \"Port 18443 is already in use\" >&2\n  exit 1\nfi\n```\n\nExpected result: the port check prints nothing and exits with status `0`.\nIdentify an existing listener before changing it; this tutorial does not\nauthorize stopping an unrelated process.\n\n## 2. Prepare source-derived images\n\nRun the repository preparation script:\n\n```sh\n./deploy/connector-fleet/prepare.sh\ntest -s deploy/connector-fleet/.env.qualification\n```\n\nExpected result: preparation ends with `connector fleet preparation: PASS`.\nThe environment file has permissions `0600` and records the source digest,\nimage tag, image IDs, connector release ID, and monotonic release revision\nselected by Compose.\n\nThe preparation script builds every image in the products profile even though\nthis tutorial starts only the Hermes path. The resulting identities are local\nfixture inputs, not a production admission package or provider credential.\n\nDefine a helper that always selects the source-owned file, environment, and\nprofile:\n\n```sh\ncompose() {\n  docker compose \\\n    --profile products \\\n    --env-file deploy/connector-fleet/.env.qualification \\\n    -f deploy/connector-fleet/compose.yml \\\n    \"$@\"\n}\n```\n\nInspect the fixed project before starting it:\n\n```sh\ncompose ps --all\n```\n\nStop here if the command reveals resources you need to retain. Do not run\ncleanup merely because the project already exists.\n\n## 3. Start the Hermes path\n\nStart the Hermes host and the dependencies declared by the Compose graph:\n\n```sh\ncompose up --detach --wait --wait-timeout 300 hermes-acme-a\n```\n\nExpected result: the command exits with status `0`. The dependency graph starts\nPostgreSQL, identity and policy initialization, registry migration and grants,\nthe Hermes admission chain, the lifecycle control plane, the TLS edge, two\nproduct-neutral gateway replicas, the controlled product upstream, and\n`hermes-acme-a`.\n\nInspect one-shot and long-running services:\n\n```sh\ncompose ps --all\n```\n\nThe Hermes host, both gateways, control plane, edge, PostgreSQL, and product\nfixture should be running and healthy. Initialization, migration, grants, and\nadmission jobs may be exited with status `0`; that is their successful terminal\nstate.\n\nDo not bypass a failed admission job or start the host outside its declared\nidentity. Preserve the failed job's bounded logs and correct its source-owned\ninput.\n\n## 4. Read the Hermes model catalog\n\nRun `aipctl` inside the isolated network with the generated client identity and\ntrust material:\n\n```sh\ncompose run --rm --no-deps \\\n  --entrypoint /usr/local/bin/aipctl \\\n  -e AIPCTL_NATIVE_PRINCIPAL_ID=service:aipctl:qualification-acme \\\n  -e AIPCTL_NATIVE_TRUST_DOMAIN=fleet.test \\\n  -e AIPCTL_NATIVE_SIGNING_SEED_FILE=/fleet-state/secrets/client-acme-signing-seed.hex \\\n  -e AIPCTL_NATIVE_PEER_DID_FILE=/fleet-state/public/gateway.did \\\n  -e AIPCTL_NATIVE_TLS_CA_FILE=/caddy-data/caddy/pki/authorities/local/root.crt \\\n  qualification action call \\\n  https://aipd.fleet.test:8443 \\\n  cap:hermes_agent:qualification:models \\\n  --action-id act_hermes_quickstart_001 \\\n  --input '{}'\n```\n\nExpected result: the response identifies `act_hermes_quickstart_001`, names\n`cap:hermes_agent:qualification:models`, reports a completed action result, and\ncontains the fixture model `qualification-model`.\n\nThe provider fixture requires the connector-owned Bearer token for\n`GET /v1/models`. A completed result therefore demonstrates the configured\ncredential path as well as signature verification, tenant routing, standalone\nhost execution, and result persistence. It does not prove compatibility with a\nreal Hermes or model-provider deployment.\n\n## 5. Read the durable result through the second gateway\n\nQuery the stored action through `aipd-b` without repeating the provider call:\n\n```sh\ncompose run --rm --no-deps \\\n  --entrypoint /usr/local/bin/aipctl \\\n  -e AIPCTL_NATIVE_PRINCIPAL_ID=service:aipctl:qualification-acme \\\n  -e AIPCTL_NATIVE_TRUST_DOMAIN=fleet.test \\\n  -e AIPCTL_NATIVE_SIGNING_SEED_FILE=/fleet-state/secrets/client-acme-signing-seed.hex \\\n  -e AIPCTL_NATIVE_PEER_DID_FILE=/fleet-state/public/gateway.did \\\n  -e AIPCTL_NATIVE_TLS_CA_FILE=/caddy-data/caddy/pki/authorities/local/root.crt \\\n  -e AIPCTL_NATIVE_BEARER_TOKEN_FILE=/fleet-state/secrets/native-bearer-token \\\n  qualification action status \\\n  https://aipd-b.fleet.test:8443 \\\n  act_hermes_quickstart_001 \\\n  --include-result \\\n  --include-receipts\n```\n\nExpected result: the lifecycle view contains the same action and capability,\nreports a terminal completed result, and includes the stored output. This\ndemonstrates shared durable lookup; it is not a gateway failover test.\n\n## 6. Verify the tutorial outcome\n\nRequire the named product host and both gateway replicas to remain running:\n\n```sh\ntest \"$(compose ps --status running --services | grep -cx 'hermes-acme-a')\" -eq 1\ntest \"$(compose ps --status running --services | grep -Ec '^aipd(-b)?$')\" -eq 2\n```\n\nRepeat a non-mutating status lookup through the first gateway:\n\n```sh\ncompose run --rm --no-deps \\\n  --entrypoint /usr/local/bin/aipctl \\\n  -e AIPCTL_NATIVE_PRINCIPAL_ID=service:aipctl:qualification-acme \\\n  -e AIPCTL_NATIVE_TRUST_DOMAIN=fleet.test \\\n  -e AIPCTL_NATIVE_SIGNING_SEED_FILE=/fleet-state/secrets/client-acme-signing-seed.hex \\\n  -e AIPCTL_NATIVE_PEER_DID_FILE=/fleet-state/public/gateway.did \\\n  -e AIPCTL_NATIVE_TLS_CA_FILE=/caddy-data/caddy/pki/authorities/local/root.crt \\\n  -e AIPCTL_NATIVE_BEARER_TOKEN_FILE=/fleet-state/secrets/native-bearer-token \\\n  qualification action status \\\n  https://aipd.fleet.test:8443 \\\n  act_hermes_quickstart_001 \\\n  --include-result >/dev/null\n```\n\nAll commands must exit with status `0`. You have now completed the tutorial's\nsingle learning outcome: one signed Hermes read crossed the admitted\nstandalone-host boundary and remained durably observable.\n\n## Diagnose before cleanup\n\nIf any step fails, capture bounded state first:\n\n```sh\ncompose ps --all\ncompose logs --no-color --tail 200 \\\n  aipd aipd-b control-plane hermes-acme-a product-upstream\n```\n\n| Symptom | Check |\n|---|---|\n| Preparation cannot reach Docker | Repair the daemon, then repeat the source and project checks |\n| Port `18443` is occupied | Identify the owner; do not terminate it without confirming scope |\n| Admission exits nonzero | Read that job's bounded log; do not bypass the package or trust policy |\n| Hermes host is unhealthy | Check its identity, endpoint file, API-key file, database, and fixture |\n| Signed action is rejected | Keep the generated principal, key, peer DID, CA, and tenant unchanged |\n| Models read returns unauthorized | Verify the generated endpoint key path and fixture token without printing either value |\n| Second lookup fails | Preserve both gateway and PostgreSQL logs before changing shared state |\n\nThis tutorial does not authorize regenerating identities, deleting the\ndatabase, weakening TLS, editing fixture credentials, or replacing admission\nwith manual host startup as a repair.\n\n## Stop and remove the tutorial project\n\nOnly after confirming that the fixed project contains no evidence or state you\nmust retain, remove its containers, network, and volumes:\n\n```sh\ncompose down --volumes --remove-orphans --timeout 30\ntest -z \"$(compose ps --all --quiet)\"\n```\n\nThe first command permanently deletes the named project's PostgreSQL state,\ngenerated keys, and retained evidence. It does not prune unrelated containers,\nimages, volumes, or build cache. Any broader cleanup requires a separate scope\ndecision.\n\n## What to do next\n\n- Read the [Hermes Agent connector overview](../README.md) for the five families\n  and four execution roles.\n- Use the [fleet quickstart](../../../getting-started/connector-fleet-quickstart.md)\n  to understand the cross-connector learning path.\n- Follow [Deploy the connector fleet](../../../guides/deploy-connector-fleet.md)\n  only after production admission material and identities exist.\n- Use [connector fleet qualification](../../../testing/connector-fleet-qualification.md)\n  for failure, restart, isolation, and evidence claims.\n- Read the [historical Hermes Agent report](../../../testing/hermes-agent-isolated-live.md)\n  before interpreting external-product evidence.\n",
    "text": "Run the Hermes Agent connector quickstart\n\nIn this tutorial, you will start the repository's deterministic Hermes product\npath and route one signed cap:hermesagent:qualification:models action from\naipctl, through product-neutral aipd, to the standalone\naip-host-hermes-agent process.\n\nThe provider is a controlled local fixture. You do not need a Hermes Agent\ndeployment, model provider, or credential, and the procedure does not call an\nexternal service. This is a learning exercise, not a production deployment or\nqualification run.\n\nWhat you will verify\n\nBy the end, you will have observed:\n• source-derived local images and connector release identities;\n• registry admission before the Hermes host starts;\n• one healthy, tenant-bound host with endpoint ID qualification;\n• one signed, low-risk models read returning the deterministic fixture model;\n• the same durable action state through a second aipd replica;\n• cleanup limited to the named tutorial Compose project.\n\nYou will not test chat, streaming, a provider mutation, approval, operator\nexecution, delegation, MCP, restart, failover, an external model, or a\nproduction security boundary.\n\nPrerequisites\n\nYou need:\n• a clean aip-core checkout at the reviewed source revision;\n• Docker Engine, Docker Compose v2, and BuildKit;\n• enough CPU, memory, and disk for the source-owned fleet images;\n• TCP port 18443 free on loopback;\n• a POSIX-compatible shell and lsof.\n\nRun every command from the aip-core repository root. Image preparation builds\nthe gateway, control plane, fixtures, and all product hosts, so the first run\ncan take substantially longer than a single native binary.\n\nThe Compose project name is fixed as aip-connector-fleet-qualification. Do\nnot continue if another investigation or retained qualification run owns that\nproject or its volumes.\n1. Verify the source boundary\n\nSet and verify the reviewed revision:\n\nexport AIPSOURCEREVISION=97be86e9efedf07ecf1783b03800f683f107fb04\n\ntest \"$(git rev-parse HEAD)\" = \"$AIPSOURCEREVISION\"\ntest -z \"$(git status --porcelain)\"\n\nBoth checks must exit with status 0. Use a separate clean checkout if you\nhave local work; do not hide or discard changes to satisfy the preflight.\n\nConfirm that Docker and Compose are available:\n\ndocker info >/dev/null\ndocker compose version\n\nConfirm that the fixed edge port is unused:\n\nif ! command -v lsof >/dev/null; then\n  echo \"lsof is required for the port preflight\" >&2\n  exit 1\nfi\n\nif lsof -nP -iTCP:18443 -sTCP:LISTEN | grep -q .; then\n  echo \"Port 18443 is already in use\" >&2\n  exit 1\nfi\n\nExpected result: the port check prints nothing and exits with status 0.\nIdentify an existing listener before changing it; this tutorial does not\nauthorize stopping an unrelated process.\n2. Prepare source-derived images\n\nRun the repository preparation script:\n\n./deploy/connector-fleet/prepare.sh\ntest -s deploy/connector-fleet/.env.qualification\n\nExpected result: preparation ends with connector fleet preparation: PASS.\nThe environment file has permissions 0600 and records the source digest,\nimage tag, image IDs, connector release ID, and monotonic release revision\nselected by Compose.\n\nThe preparation script builds every image in the products profile even though\nthis tutorial starts only the Hermes path. The resulting identities are local\nfixture inputs, not a production admission package or provider credential.\n\nDefine a helper that always selects the source-owned file, environment, and\nprofile:\n\ncompose() {\n  docker compose \\\n    --profile products \\\n    --env-file deploy/connector-fleet/.env.qualification \\\n    -f deploy/connector-fleet/compose.yml \\\n    \"$@\"\n}\n\nInspect the fixed project before starting it:\n\ncompose ps --all\n\nStop here if the command reveals resources you need to retain. Do not run\ncleanup merely because the project already exists.\n3. Start the Hermes path\n\nStart the Hermes host and the dependencies declared by the Compose graph:\n\ncompose up --detach --wait --wait-timeout 300 hermes-acme-a\n\nExpected result: the command exits with status 0. The dependency graph starts\nPostgreSQL, identity and policy initialization, registry migration and grants,\nthe Hermes admission chain, the lifecycle control plane, the TLS edge, two\nproduct-neutral gateway replicas, the controlled product upstream, and\nhermes-acme-a.\n\nInspect one-shot and long-running services:\n\ncompose ps --all\n\nThe Hermes host, both gateways, control plane, edge, PostgreSQL, and product\nfixture should be running and healthy. Initialization, migration, grants, and\nadmission jobs may be exited with status 0; that is their successful terminal\nstate.\n\nDo not bypass a failed admission job or start the host outside its declared\nidentity. Preserve the failed job's bounded logs and correct its source-owned\ninput.\n4. Read the Hermes model catalog\n\nRun aipctl inside the isolated network with the generated client identity and\ntrust material:\n\ncompose run --rm --no-deps \\\n  --entrypoint /usr/local/bin/aipctl \\\n  -e AIPCTLNATIVEPRINCIPALID=service:aipctl:qualification-acme \\\n  -e AIPCTLNATIVETRUSTDOMAIN=fleet.test \\\n  -e AIPCTLNATIVESIGNINGSEEDFILE=/fleet-state/secrets/client-acme-signing-seed.hex \\\n  -e AIPCTLNATIVEPEERDIDFILE=/fleet-state/public/gateway.did \\\n  -e AIPCTLNATIVETLSCAFILE=/caddy-data/caddy/pki/authorities/local/root.crt \\\n  qualification action call \\\n  https://aipd.fleet.test:8443 \\\n  cap:hermesagent:qualification:models \\\n  --action-id acthermesquickstart001 \\\n  --input '{}'\n\nExpected result: the response identifies acthermesquickstart001, names\ncap:hermesagent:qualification:models, reports a completed action result, and\ncontains the fixture model qualification-model.\n\nThe provider fixture requires the connector-owned Bearer token for\nGET /v1/models. A completed result therefore demonstrates the configured\ncredential path as well as signature verification, tenant routing, standalone\nhost execution, and result persistence. It does not prove compatibility with a\nreal Hermes or model-provider deployment.\n5. Read the durable result through the second gateway\n\nQuery the stored action through aipd-b without repeating the provider call:\n\ncompose run --rm --no-deps \\\n  --entrypoint /usr/local/bin/aipctl \\\n  -e AIPCTLNATIVEPRINCIPALID=service:aipctl:qualification-acme \\\n  -e AIPCTLNATIVETRUSTDOMAIN=fleet.test \\\n  -e AIPCTLNATIVESIGNINGSEEDFILE=/fleet-state/secrets/client-acme-signing-seed.hex \\\n  -e AIPCTLNATIVEPEERDIDFILE=/fleet-state/public/gateway.did \\\n  -e AIPCTLNATIVETLSCAFILE=/caddy-data/caddy/pki/authorities/local/root.crt \\\n  -e AIPCTLNATIVEBEARERTOKENFILE=/fleet-state/secrets/native-bearer-token \\\n  qualification action status \\\n  https://aipd-b.fleet.test:8443 \\\n  acthermesquickstart001 \\\n  --include-result \\\n  --include-receipts\n\nExpected result: the lifecycle view contains the same action and capability,\nreports a terminal completed result, and includes the stored output. This\ndemonstrates shared durable lookup; it is not a gateway failover test.\n6. Verify the tutorial outcome\n\nRequire the named product host and both gateway replicas to remain running:\n\ntest \"$(compose ps --status running --services | grep -cx 'hermes-acme-a')\" -eq 1\ntest \"$(compose ps --status running --services | grep -Ec '^aipd(-b)?$')\" -eq 2\n\nRepeat a non-mutating status lookup through the first gateway:\n\ncompose run --rm --no-deps \\\n  --entrypoint /usr/local/bin/aipctl \\\n  -e AIPCTLNATIVEPRINCIPALID=service:aipctl:qualification-acme \\\n  -e AIPCTLNATIVETRUSTDOMAIN=fleet.test \\\n  -e AIPCTLNATIVESIGNINGSEEDFILE=/fleet-state/secrets/client-acme-signing-seed.hex \\\n  -e AIPCTLNATIVEPEERDIDFILE=/fleet-state/public/gateway.did \\\n  -e AIPCTLNATIVETLSCAFILE=/caddy-data/caddy/pki/authorities/local/root.crt \\\n  -e AIPCTLNATIVEBEARERTOKENFILE=/fleet-state/secrets/native-bearer-token \\\n  qualification action status \\\n  https://aipd.fleet.test:8443 \\\n  acthermesquickstart001 \\\n  --include-result >/dev/null\n\nAll commands must exit with status 0. You have now completed the tutorial's\nsingle learning outcome: one signed Hermes read crossed the admitted\nstandalone-host boundary and remained durably observable.\n\nDiagnose before cleanup\n\nIf any step fails, capture bounded state first:\n\ncompose ps --all\ncompose logs --no-color --tail 200 \\\n  aipd aipd-b control-plane hermes-acme-a product-upstream\n\n| Symptom | Check |\n\n| Preparation cannot reach Docker | Repair the daemon, then repeat the source and project checks |\n| Port 18443 is occupied | Identify the owner; do not terminate it without confirming scope |\n| Admission exits nonzero | Read that job's bounded log; do not bypass the package or trust policy |\n| Hermes host is unhealthy | Check its identity, endpoint file, API-key file, database, and fixture |\n| Signed action is rejected | Keep the generated principal, key, peer DID, CA, and tenant unchanged |\n| Models read returns unauthorized | Verify the generated endpoint key path and fixture token without printing either value |\n| Second lookup fails | Preserve both gateway and PostgreSQL logs before changing shared state |\n\nThis tutorial does not authorize regenerating identities, deleting the\ndatabase, weakening TLS, editing fixture credentials, or replacing admission\nwith manual host startup as a repair.\n\nStop and remove the tutorial project\n\nOnly after confirming that the fixed project contains no evidence or state you\nmust retain, remove its containers, network, and volumes:\n\ncompose down --volumes --remove-orphans --timeout 30\ntest -z \"$(compose ps --all --quiet)\"\n\nThe first command permanently deletes the named project's PostgreSQL state,\ngenerated keys, and retained evidence. It does not prune unrelated containers,\nimages, volumes, or build cache. Any broader cleanup requires a separate scope\ndecision.\n\nWhat to do next\n• Read the Hermes Agent connector overview (../README.md) for the five families\n  and four execution roles.\n• Use the fleet quickstart (../../../getting-started/connector-fleet-quickstart.md)\n  to understand the cross-connector learning path.\n• Follow Deploy the connector fleet (../../../guides/deploy-connector-fleet.md)\n  only after production admission material and identities exist.\n• Use connector fleet qualification (../../../testing/connector-fleet-qualification.md)\n  for failure, restart, isolation, and evidence claims.\n• Read the historical Hermes Agent report (../../../testing/hermes-agent-isolated-live.md)\n  before interpreting external-product evidence.\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "bc79d64985cd1344d25331732868c85886611ed804f7b1f651d344b69f3d9d54"
  }
}