Skip to content
Seylo Docs

Install the agent

The agent is a single Deployment inside your cluster. It dials out to Seylo over an outbound WebSocket. It has no Service, no Ingress, no NodePort and no inbound port.

What you need: admin in Seylo, and cluster-admin (or enough rights to create a namespace, ServiceAccount and RBAC objects) on the target cluster.

Use the guided install page

Section titled “Use the guided install page”

  1. Register the cluster.

    Clusters → Add cluster, connection method In-cluster agent. Give it an ID you will recognise — it appears in the install command and in every audit row.

  2. Open the install page.

    Clusters → Agent install / status for that cluster. It walks three steps and renders the exact command for your cluster, with the server URL already filled in.

  3. Choose the scope.

    Cluster-wide, or namespace-scoped to a list you provide. This is not cosmetic — Seylo re-renders the RBAC objects in all three output formats from your choice. Read choose an RBAC posture first; the namespace-scoped option has one real consequence for metrics.

  4. Issue the enrollment token.

    It is shown once, is single-use, and expires in about an hour. Until you issue one, the rendered command carries the literal placeholder <enrollment-token> rather than anything that looks runnable.

    You can re-issue one at any time if it expires.

  5. Copy the command and run it inside your cluster.

    Helm, kubectl and raw YAML are rendered side by side, each with Copy, plus a download of the rendered manifest.

  6. Watch step 3 of the page.

    It polls Never enrolled → Waiting for agent… → Connected and stops once the agent attaches, showing its version, protocol version, last-seen time and the namespace and deployment counts it reported.

Verify the signature first

Section titled “Verify the signature first”

Do this once per version. One command, and it is the difference between “I pulled a container off the internet” and “I checked who built it”.

Both the image and the chart are signed with cosign keyless: the signature is made by the release workflow using its OIDC identity and recorded in the public Rekor transparency log. There is no key to distribute.

Terminal window
# The IMAGE.
cosign verify \
  --certificate-identity-regexp '^https://github.com/seylo-inc/k8s-deploy/\.github/workflows/release-agent\.yml@refs/tags/agent-v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/seylo-inc/seylo-agent:0.1.0


# The CHART. A Helm OCI artifact is signed the same way; `helm pull` on its
# own verifies nothing.
cosign verify \
  --certificate-identity-regexp '^https://github.com/seylo-inc/k8s-deploy/\.github/workflows/release-agent\.yml@refs/tags/agent-v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/seylo-inc/charts/seylo-agent:0.1.0

Expect Verified OK. If it fails, do not install — the bytes are not what we published.

Full detail, including the SBOM attestation and how to pin a digest: verify what you install.

Install

Section titled “Install”

Installs the published chart straight from the OCI registry. No helm repo add, no clone, no registry login.

Terminal window
helm upgrade --install seylo-agent \
  oci://ghcr.io/seylo-inc/charts/seylo-agent --version 0.1.0 \
  --namespace seylo-agent --create-namespace \
  --set serverUrl=wss://portal.seylo.in/agent/connect \
  --set clusterId=your-cluster-id \
  --set enrollmentToken=k8sdt-enroll_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The image comes from the chart’s own defaults, at the digest that chart version was released with, so there is nothing to pass for it.

Namespace-scoped variant. watchNamespaces is required here: a namespace-scoped agent is bound with a Role inside each managed namespace and cannot list namespaces itself, so the chart refuses to render without it.

Terminal window
helm upgrade --install seylo-agent \
  oci://ghcr.io/seylo-inc/charts/seylo-agent --version 0.1.0 \
  --namespace seylo-agent --create-namespace \
  --set serverUrl=wss://portal.seylo.in/agent/connect \
  --set clusterId=your-cluster-id \
  --set enrollmentToken=k8sdt-enroll_XXXX \
  --set rbac.scope=namespaced \
  --set 'watchNamespaces={prod,staging}'

Read it before you run it, if you would rather read than trust:

Terminal window
helm show values oci://ghcr.io/seylo-inc/charts/seylo-agent --version 0.1.0


helm template seylo-agent \
  oci://ghcr.io/seylo-inc/charts/seylo-agent --version 0.1.0 \
  --set serverUrl=wss://x/agent/connect --set clusterId=x --set enrollmentToken=x

Confirm it worked

Section titled “Confirm it worked”
Terminal window
kubectl -n seylo-agent logs -f deploy/seylo-agent
# expect: ENROLLED (first install), then "reporting inventory every 30s"

In the portal, the cluster shows a green Agent: Connected chip with its version and last-seen time, and dashboard rows for that cluster carry a small agent badge so operators can see the data path.

Once connected, delete the one-time enrollment Secret:

Terminal window
kubectl -n seylo-agent delete secret seylo-agent-enrollment

See verify the install for what “connected” should actually look like.

How the two secrets work

Section titled “How the two secrets work”
Enrollment token Per-agent credential
Prefix k8sdt-enroll_ k8sdt-agent_
Lifetime ~1 hour, single use Long-lived, held by the agent
Where it lives The Secret you install with; delete it after The agent’s own Secret in your cluster
Stored by Seylo as A hash A hash

Neither is ever stored in plaintext by Seylo, and a token cannot be recovered from its hash. The enrollment token is never written to the audit log, and the install page uses a POST so a freshly issued token never appears in a URL — and therefore never in a reverse proxy’s access log.

After the first enrollment the agent holds its own credential, which survives upgrades. You do not need a new enrollment token to upgrade.

Next

Section titled “Next”