Skip to main content

​
Architecture

Kubernetes is the production deployment model for Siclaw: 
Portal Deployment
  ├── Web UI (React) + REST API
  ├── Auth + user management
  └── MySQL connection

Runtime Deployment
  ├── Channels (Slack / Lark / Discord / Telegram)
  ├── Cron / scheduled tasks
  └── K8s AgentBox spawner

AgentBox Pod  (spawned per user / workspace)
  ├── Isolated agent runtime
  ├── Synced skills and credentials
  └── Internal mTLS back to Runtime

​
Prerequisites

  • A Kubernetes cluster
  • A MySQL database reachable from the cluster
  • Published Siclaw images for runtime, portal, and agentbox
Build and push images first if you are using your own registry: 
make docker REGISTRY=registry.example.com/myteam TAG=latest
make push REGISTRY=registry.example.com/myteam TAG=latest

​
Quick Start

Install from the chart in this repository: 
helm upgrade --install siclaw ./helm/siclaw \
  --namespace siclaw \
  --create-namespace \
  --set image.registry=registry.example.com/myteam \
  --set image.tag=latest \
  --set database.url="mysql://user:pass@mysql.svc.cluster.local:3306/siclaw"
All three images share image.registry and image.tag by default.

​
Important Values

Current top-level values look like this: 
image:
  registry: registry.example.com/myteam
  tag: latest

runtime:
  replicas: 1

portal:
  enabled: true
  replicas: 1
  service:
    type: NodePort
    port: 3003
    nodePort: 31003

database:
  url: mysql://user:pass@mysql.svc.cluster.local:3306/siclaw
Use database.existingSecret.name if you do not want to pass the connection string on the command line.

​
Accessing the UI

The Portal Service is the front door. With default values it listens on port 3003 inside the cluster and on NodePort 31003 on any node.
  • Keep portal.service.type: NodePort for quick access via http://<any-node-ip>:31003
  • Or point an Ingress at the Portal Service on service port 3003
Example Ingress backend: 
backend:
  service:
    name: siclaw-portal
    port:
      number: 3003
WebSocket support is required for live investigation updates. Keep proxy read/send timeouts high enough for multi-minute investigations.

​
Authentication

On first launch, open the Portal UI and register the first user — that account becomes the admin. Registration is open only for the very first account; every subsequent registration requires admin authentication.

​
Metrics

Runtime and Portal both expose Prometheus metrics at /metrics. The chart can create ServiceMonitor, PodMonitor, Grafana dashboard, and PrometheusRule resources under the metrics.* values block. Common settings: 
metrics:
  enabled: true
  serviceMonitor:
    enabled: true
  podMonitor:
    enabled: true
  grafanaDashboard:
    enabled: true
  prometheusRule:
    enabled: false
If you want bearer-token protection for /metrics, add: 
runtime:
  env:
    SICLAW_METRICS_TOKEN: "your-secret-token"
To remove the user_id label from token and cost metrics: 
runtime:
  env:
    SICLAW_METRICS_USER_ID: "false"

​
Operational Notes

  • Kubernetes mode requires MySQL. SQLite is only for single-process local use.
  • AgentBox pods are created on demand by the Runtime.
  • Runtime ↔ AgentBox traffic is secured with mTLS automatically.
  • If you deploy monitoring resources from the chart, do not also apply duplicate monitor manifests manually.