Skip to content

Sovereign agent deployment guide

The Secruna sovereign agent runs in your environment — your VPC, your Azure subscription, your GCP project. It performs AI discovery + classification locally and ships only verdicts back to Secruna's control plane. No raw artifact content, code, or LLM input / output leaves your network.

Architecture summary

  • Network: outbound HTTPS only to https://api.secruna.com. No inbound port required.
  • Auth: each request to our control plane mints a fresh JWT signed with your RSA-2048 private key. We verify against the public key registered when the agent was provisioned.
  • Rule book: the agent pulls a signed tarball from our CDN at startup + every 15 min. Tampered artifacts are rejected.
  • LLM: you choose. Ollama (in your network), Azure OpenAI (your subscription), or byo (your own endpoint). Anthropic / OpenAI direct is supported but leaves your network — pick Ollama or Azure OpenAI for full data sovereignty.

Bundle handoff

Your Secruna contact will provide:

  • The agent subject string (a stable identifier we use to verify your agent).
  • A one-time private key PEM — store this in your secrets manager immediately; it cannot be retrieved later.
  • A deployment template in your preferred shape (Docker Compose, Helm values, or Bicep).
  • The rule book signing public key — embedded in the template so the agent can verify rule book updates.

Deploy: Docker Compose

For a single VM or laptop-grade deployment:

  1. Save the rendered template as docker-compose.yml.
  2. Confirm the SECRUNA_AGENT_PRIVATE_KEY_PEM block carries the full PEM (BEGIN / END lines plus body).
  3. Pick an LLM provider — uncomment one block:
LLM_PROVIDER: "ollama"
OLLAMA_BASE_URL: "http://host.docker.internal:11434"
OLLAMA_MODEL: "llama3:8b"
  1. Bring it up:
docker compose up -d
docker compose logs -f
  1. Verify the agent appears as online on the operator-side /admin/agents dashboard within 60s.

Deploy: Helm chart

For K8s shops:

  1. Drop the rendered values.yaml into your Helm chart values directory.
  2. Critical: replace the inline secrets.privateKeyPem block with a Sealed Secret or External Secrets reference before committing. Never commit the raw PEM to git.
  3. Install / upgrade:
helm upgrade --install secruna-agent ./chart -f values.yaml
  1. Watch the deployment:
kubectl logs -f deploy/secruna-sovereign-agent

Deploy: Azure Container Apps (Bicep)

For Azure-native customers:

  1. Save the rendered Bicep as secruna-agent.bicep.
  2. Set the two required @secure() params before deployment — these never appear in deployment history:
az deployment group create \
  --resource-group rg-secruna-agent \
  --template-file secruna-agent.bicep \
  --parameters environmentId="..." \
               agentPrivateKeyPem=@./agent-private-key.pem \
               ruleBookPublicKeyPem=@./rule-book-public-key.pem
  1. Confirm the container app appears in your Azure portal under your resource group.

LLM provider configuration

LLM_PROVIDER Data leaves your network? Required env
ollama No OLLAMA_BASE_URL, OLLAMA_MODEL
azure_openai Stays in your Azure subscription AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY, AZURE_OPENAI_DEPLOYMENT
anthropic Yes — leaves your network to Anthropic ANTHROPIC_API_KEY, ANTHROPIC_MODEL
byo Depends — you point at your own endpoint BYO_BASE_URL, BYO_API_KEY

For full data sovereignty pick ollama or azure_openai. The other providers are convenience options for customers who care about agent / artifact isolation but not LLM-side egress.

Verifying the agent

  1. Tail container logs. You should see agent.heartbeat.ok lines roughly every 60s and agent.poll.empty lines continuously (no work queued yet is fine).
  2. Ask your Secruna contact to confirm the operator-side /admin/agents row shows your agent as online with a current heartbeat timestamp.
  3. If you provisioned with LLM_PROVIDER=ollama confirm the container can reach your Ollama service:
docker compose exec secruna-agent curl -fsS http://host.docker.internal:11434/api/tags

Key rotation

To rotate the agent's keypair:

  1. Ask your operator to revoke the existing agent (/admin/agents/{id}/revoke).
  2. Operator re-provisions; you receive a new one-time private key + template.
  3. Swap the secret in your secrets manager and restart the container.

To rotate the rule book signing key (operator-driven):

  1. Operator rotates the cp-api side; the new public key is included in subsequent provisions.
  2. Existing agents continue running on the old public key until their SECRUNA_RULE_BOOK_PUBLIC_KEY_PEM env var is updated and the container restarted.

Audit

You retain full visibility:

  • docker compose logs secruna-agent — every poll, heartbeat, verdict POST is structlog'd locally.
  • Secruna's operator dashboard shows verdict counts but not the underlying artifact content.

For your annual security review, the data flow diagram is in docs/engineering/sovereign-agent-architecture.md.

Support

If the agent loses connection to cp-api for >30 min, contact your Secruna point of contact. Common causes:

  • Customer-side egress proxy / firewall changes.
  • Expired private key (rare — RSA-2048 has no expiry, but the agent itself may have been revoked).
  • Container restarted with stale env vars.

Bring the relevant docker compose logs excerpt + the agent subject string when you contact support.