On-Prem Worker

BigPanda's L1 Agent On-Premises Worker is a lightweight containerized agent that runs on your infrastructure to execute runbook automation steps. It connects to BigPanda using mutual TLS (mTLS) authentication and executes pre-registered workflows on demand.

The worker is required for L1 Agent runbook automation. It is not required for AI Detection and Response (ADR).AI Detection and Response

Key features

Secure by design: All communication is encrypted with per-organization certificates. The worker only makes outbound connections.
Read-only and data-in-place: The worker reads data from your systems at the source and returns structured diagnostic results to BigPanda. It does not copy, replicate, or move data between systems or environments.
No standing credentials: The worker does not store or cache credentials. At runtime it assumes a customer-defined service role to obtain temporary, scoped credentials, which exist in memory only for the duration of the runbook execution.
Customer-controlled execution: All runbooks are authored, reviewed, and owned by your team. The worker only runs pre-registered workflows. No arbitrary code execution is possible.

On-prem worker architecture

The worker connects outbound to BigPanda and waits for workflow instructions. When BigPanda's triage agent detects a device-related incident, it triggers the health check workflow for your worker.

The BigPanda triage agent detects an incident that requires information from your environment.
BigPanda routes a workflow task to your on-premises worker.
The worker executes the workflow (for example, checking device health against your monitoring platform).
The worker returns the result to BigPanda, where it feeds into the L1 Agent's reasoning.

BigPanda Cloud                        Your Network
──────────────                        ────────────

Triage Agent detects                  Worker (this service)
"device unreachable"                      │
        │                                 │ Connects to BigPanda
        ▼                                 │ via mTLS (outbound only)
Temporal Server                           │
        │                                 │
        └── Routes workflow ─────────────►│
            to your worker                │
                                          ▼
                                   Calls your monitoring API
                                   GET {healthCheckUrl}/{deviceName}
                                   Auth: Bearer <DEVICE_API_KEY>
                                          │
                                          ▼
                                   Returns result to BigPanda
                                   (UP / DOWN / NOT_SUPPORTED)

All workflow configuration, including which monitoring endpoints to call and which devices to check, is managed by BigPanda. The worker receives this information as input at execution time. You don't need to configure or schedule workflows -- BigPanda manages this automatically. The worker just needs to be running and connected.

Communication model

Direction	Destination	Protocol	Purpose
Outbound	BigPanda cloud services	gRPC + mTLS	Workflow task retrieval and result delivery
Outbound	Your monitoring platform	HTTPS	Data collection (for example, device health checks)
Inbound	None required	--	The worker only makes outbound connections

Install the On-prem worker

The worker ships as a Docker container image. BigPanda provides a presigned download URL during onboarding.

Before you start

Make sure you have the following ready:

Docker installed on the target machine
mTLS certificates from BigPanda (provided during onboarding)
An API key for your monitoring platform with read access to the relevant health or status endpoints

Deploy the worker with Docker

Download and load the image

BigPanda provides a pre-signed URL for the Docker image. Download and load it:

curl -L '<PRESIGNED-URL>' -o health-check-worker.tar.gz
docker load < adr-temporal-worker.tar.gz

Install certificates

BigPanda provides your organization's mTLS certificates during onboarding. Place them in a certs/ directory:

certs/
├── client.pem       # Client certificate (identifies your organization)
├── client-key.pem   # Client private key
└── ca.cert          # BigPanda CA certificate

Certificate security

Keep client-key.pem secure. It authenticates your worker to BigPanda. If compromised, contact BigPanda immediately to rotate the certificate.

(Optional) Stop the existing worker

If you are upgrading an existing worker, stop and remove the current container:

docker stop adr-temporal-worker && docker rm adr-temporal-worker

Create a configuration file

Create an .env file with the following variables:

# --- Connection (provided by BigPanda) ---
TEMPORAL_ADDRESS=temporal.prod.bigpanda.io:7233
TEMPORAL_TLS_CERT_PATH=/certs/client.pem
TEMPORAL_TLS_KEY_PATH=/certs/client-key.pem
TEMPORAL_TLS_CA_PATH=/certs/ca.cert

# --- Secrets (configured by you) ---
DEVICE_API_KEY=<your-monitoring-platform-api-key>

Monitoring platform authentication

DEVICE_API_KEY must have read access to device health status on your monitoring platform. The worker sends it as a Bearer token in the Authorization header. If your monitoring platform does not require authentication, you can omit this variable.

Run the worker

docker run -d \
  --name adr-temporal-worker \
  --restart unless-stopped \
  --log-opt max-size=50m \
  --log-opt max-file=3 \
  -p 8080:8080 \
  -v $(pwd)/certs:/certs:ro \
  --env-file .env \
  adr-temporal-worker:latest

Verify the deployment

Check the worker logs to confirm a successful start:

docker logs -f adr-temporal-worker

You should see output similar to:

Starting Temporal Worker
Worker state changed { state: 'RUNNING' }
Worker started
Health server listening

Then verify the health endpoints:

curl http://localhost:8080/health    # Returns: {"status":"ok","startedAt":"..."}
curl http://localhost:8080/ready     # Returns: {"status":"ready"}

Deploy the worker with Kubernetes

If you are deploying to Kubernetes, use the following manifests as a starting point.

Create certificates and monitoring API key

apiVersion: v1
kind: Secret
metadata:
  name: adr-temporal-worker-secrets
  namespace: bigpanda
type: Opaque
stringData:
  DEVICE_API_KEY: "<your-monitoring-platform-api-key>"
---
apiVersion: v1
kind: Secret
metadata:
  name: adr-temporal-worker-certs
  namespace: bigpanda
type: Opaque
data:
  client.pem: <base64-encoded-cert>
  client-key.pem: <base64-encoded-key>
  ca.cert: <base64-encoded-ca>

Create the deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: adr-temporal-worker
  namespace: bigpanda
spec:
  replicas: 1
  selector:
    matchLabels:
      app: adr-temporal-worker
  template:
    metadata:
      labels:
        app: adr-temporal-worker
    spec:
      containers:
        - name: worker
          image: adr-temporal-worker:latest
          ports:
            - containerPort: 8080
          envFrom:
            - secretRef:
                name: adr-temporal-worker-secrets
          env:
            - name: TEMPORAL_ADDRESS
              value: "temporal.prod.bigpanda.io:7233"
            - name: TEMPORAL_TLS_CERT_PATH
              value: "/certs/client.pem"
            - name: TEMPORAL_TLS_KEY_PATH
              value: "/certs/client-key.pem"
            - name: TEMPORAL_TLS_CA_PATH
              value: "/certs/ca.cert"
          volumeMounts:
            - name: certs
              mountPath: /certs
              readOnly: true
          resources:
            requests:
              memory: "256Mi"
              cpu: "100m"
            limits:
              memory: "512Mi"
              cpu: "500m"
          livenessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 30
          readinessProbe:
            httpGet:
              path: /ready
              port: 8080
            initialDelaySeconds: 15
      volumes:
        - name: certs
          secret:
            secretName: adr-temporal-worker-certs

Configure the worker

Connection configuration

Primary connection configuration is provided by the Bigpanda team.

Variable	Description	Example
`TEMPORAL_ADDRESS`	BigPanda server address	`temporal.prod.bigpanda.io:7233`
`TEMPORAL_TLS_CERT_PATH`	Path to mTLS client certificate	`/certs/client.pem`
`TEMPORAL_TLS_KEY_PATH`	Path to mTLS client private key	`/certs/client-key.pem`
`TEMPORAL_TLS_CA_PATH`	Path to BigPanda CA certificate	`/certs/ca.cert`

Secrets

Secrets are configured by you, following the procedure for the connected monitoring platform.

Variable	Description	Required
`DEVICE_API_KEY`	API key for your monitoring platform. Sent as a `Bearer` token in the `Authorization` header.	Only if your monitoring platform requires authentication

Optional configuration

Variable	Default	Description
`METRICS_PORT`	`8080`	Port for health endpoints
`LOG_LEVEL`	`info`	Log level (`debug`,`info`,`warn`,`error`)

Health and Monitoring endpoints

Endpoint	Response	Purpose
`GET /health`	`{"status":"ok","startedAt":"..."}`	Health check — returns 200 if the worker is running
`GET /ready`	`{"status":"ready"}`	Readiness check — returns 200 if the worker is initialized

Use these endpoints for container orchestration health probes such as Docker healthcheck or Kubernetes liveness and readiness probes.

Network Requirements

Direction	Destination	Port	Protocol	Purpose
Outbound	`temporal.prod.bigpanda.io`	`7233`	gRPC + mTLS	BigPanda server connection
Outbound	Your monitoring platform	Varies	HTTPS	Device health checks
Inbound	None required	—	—	—

Firewall configuration

No inbound ports need to be opened. The worker only makes outbound connections.

Troubleshooting

Symptom	Likely Cause	Solution
Worker fails to start with an ENOENT error	Certificate files not found	Verify that cert files exist at the paths specified in `TEMPORAL_TLS_CERT_PATH`, `TEMPORAL_TLS_KEY_PATH`, and `TEMPORAL_TLS_CA_PATH`.
TLS handshake failed in logs	Invalid, expired, or incorrectly signed certificates	Contact BigPanda to verify or rotate your certificates.
Worker crashes with DEADLINE_EXCEEDED or a connection error	Cannot reach BigPanda	Verify that your firewall or proxy allows outbound traffic to the address specified in `TEMPORAL_ADDRESS`.
Health endpoint not responding	Port not exposed or blocked	Verify that port 8080 is exposed (`-p 8080:8080`) and not blocked by a local firewall.
Device check returns DOWN for all devices	Invalid or missing monitoring API key	Verify that `DEVICE_API_KEY` has read access to device health status. Test the API manually: `curl -H "Authorization: Bearer <key>" https://your-monitor/api/device-health/<device>`
Device check times out (60 seconds)	Monitoring platform unreachable from worker	Verify that the worker can reach your monitoring platform. Check DNS resolution and firewall rules.
Container exits immediately	Missing required environment variables	Verify that all `TEMPORAL_*` variables are set in your `.env` file. Run `docker logs adr-temporal-worker` to identify the specific missing variable.
Container restarts repeatedly	Persistent connection or authentication failure	Run `docker logs adr-temporal-worker` to identify the error, then refer to the relevant row above.

Useful Commands

docker logs -f adr-temporal-worker          # View live logs
docker logs --tail 100 adr-temporal-worker  # View last 100 lines
docker restart adr-temporal-worker          # Restart the worker
docker stop adr-temporal-worker             # Stop the worker
docker rm adr-temporal-worker               # Remove the worker
curl http://localhost:8080/health           # Check health status
curl http://localhost:8080/ready            # Check readiness status

Security

The On-Premises Worker is designed for read-only, data-in-place information gathering. The following sections describe the controls that enforce that posture.

Identity and access management

The worker does not maintain standing credentials to your systems. All access is obtained through role assumption: at execution time, the worker requests temporary, scoped credentials from your identity provider.

Role assumption: You define a service role with the minimum permissions required for runbook execution. The worker assumes this role at runtime to perform the workflow.
Least privilege: Scope the assumed role to only the systems and data your runbooks need. BigPanda provides guidance on recommended permission scoping.
No credential storage: The worker does not store, cache, or persist credentials beyond the active execution session. Credentials live in memory only for the duration of the runbook execution.
Customer-controlled credential rotation: You fully control credential rotation according to your internal security requirements. BigPanda never stores or manages your infrastructure credentials.
Certificate-derived org identity: Your organization identity is derived from the mTLS certificate. No manual namespace configuration is needed.

Network security

The worker operates entirely within your network perimeter. All communications between the worker and your systems are subject to your network policies, firewall rules, and segmentation controls.

Encrypted communications: All communication between BigPanda and the worker uses TLS 1.2 or higher, with strong cipher suites. The worker validates certificates to prevent man-in-the-middle attacks.
Outbound-only connectivity: The worker initiates outbound mTLS connections to BigPanda. No inbound ports need to be opened in your firewall.
Network isolation: The worker can be deployed in an isolated network segment with access limited to only the systems required by your runbooks.

Data protection

Data in place: The worker reads and processes data at its origin. It does not copy, replicate, or relocate data between systems or environments. Diagnostic results returned to BigPanda are structured summaries, not raw data exports.
Data in transit: Execution requests and results are transmitted over mutually authenticated, TLS 1.2+ encrypted channels.
Data at rest: The worker does not persist data at rest. Execution context, gathered information, and credentials exist only in memory and are released on completion or failure.
Data minimization: The worker collects only the information specified by your runbook steps. It does not perform broad discovery, scanning, or enumeration. You control what data is gathered by controlling runbook content.

Controlled Execution

The worker only executes pre-registered workflows authored and approved by your team. No arbitrary code execution is possible.

Compliance and trust posture

BigPanda undergoes annual SOC 2 Type II audits covering security, availability, and confidentiality trust service criteria. The On-Premises Worker development and release processes are within the audit scope.

For the SOC 2 Type II report, the L1 Agent On-Premises Worker security and trust brief, and additional security documentation, visit the BigPanda Trust Center.

Shared responsibilities

Security of the On-Premises Worker deployment operates under a shared responsibility model. BigPanda is responsible for the security of the worker software itself. You are responsible for the security of the environment in which it runs and the access it is granted. For the full security posture, including the SOC 2 Type II report, see the BigPanda Trust Center.

BigPanda responsibilities

Worker software security: Secure development lifecycle (threat modeling, secure coding, static and dynamic analysis, dependency scanning, peer code review, and penetration testing). Continuous monitoring for known vulnerabilities in the worker codebase and dependencies, with severity-based remediation SLAs.
Secure communication protocol: Maintenance of the encrypted communication channel between BigPanda and the worker, including certificate management for the BigPanda-side endpoints.
Security updates and advisories: Release of security patches and advisories for the worker, with notifications through standard communication channels.
Audit trail: Platform-side logging of the end-to-end process for review and troubleshooting.

Customer responsibilities

Runbook authoring and review: Create, review, and maintain runbooks. Runbooks define what systems the worker connects to and what data it gathers.
Incident-runbook associations: Configure which runbooks are triggered for which incident types.
Role provisioning and scoping: Define and provision the service role the worker assumes, applying least-privilege principles.
Credential and identity infrastructure: Maintain the identity provider and role assumption infrastructure, including trust policies, session duration limits, and conditional access policies.
Network security: Manage the network environment in which the worker operates, including firewall rules, segmentation, DNS, and traffic monitoring.
Host and container security: Manage the compute environment running the worker container, including host OS patching, container runtime security, and resource isolation.
Worker updates: Apply BigPanda-released worker updates in line with your patch management SLA.
Monitoring and alerting: Monitor the worker's operational behavior, including resource consumption, network connections, and execution anomalies.

Operational Security Guidance

The following recommendations supplement the deployment instructions above and are aligned with the controls described in the L1 Agent On-Premises Worker security and trust brief on the BigPanda Trust Center.

Deployment best practices

Image verification: Always verify the container image before deployment.
Dedicated service account: Create a dedicated service identity for the worker. Do not reuse identities shared with other services or human users.
Network segmentation: Deploy the worker in an isolated network segment with access limited to only the systems required by active runbooks.
Resource limits: Configure CPU and memory limits on the worker container to prevent resource exhaustion and contain unexpected behavior. See the Resource Requirements table for recommended values.
Update cadence: Establish a process to apply BigPanda-released worker updates within your organization's patch management SLA.

Role scoping recommendations

Start minimal: Begin with the narrowest permissions possible and expand only as specific runbooks require additional access.
Read-only by default: The worker's intended function is information gathering. Scope the role to read-only permissions unless a runbook explicitly requires write access for a documented, approved purpose.
Short session duration: Configure the shortest practical session duration for assumed-role credentials, aligned with your session management policies.
Conditional access: Where supported by your identity provider, apply conditional access policies to the worker's role (source IP restrictions, time-of-day constraints, MFA on role assumption).

Runbook governance

Peer review: Require peer review for all runbook changes before deployment, applying the same rigor used for infrastructure-as-code.
Version control: Maintain runbooks in version control with a complete audit trail of changes, approvals, and deployments.
Testing: Test runbooks in a non-production environment before associating them with production incident types.
Periodic review: Review active runbooks on a regular cadence to confirm they remain aligned with current infrastructure, access policies, and operational requirements.

FAQs

Does BigPanda have access to my systems?

No. The worker runs in your environment using credentials you provision. BigPanda does not have direct access to your infrastructure.

Can the worker modify my systems?

The worker is designed for read-only information gathering. It does not modify systems unless a customer-authored runbook explicitly instructs it to do so. BigPanda recommends scoping the assumed role to read-only permissions.

Where does my data go?

Data is processed in place within your environment. Only structured diagnostic results specified by your runbook are returned to BigPanda over an encrypted channel.

How do I control what the worker can access?

You control access entirely through role provisioning. The worker can only access systems and data that the assumed role permits. Apply least-privilege principles when defining the role.

Does BigPanda write or modify my runbooks?

No. All runbooks are authored, maintained, and owned by you. BigPanda provides the execution engine but does not create, modify, or inject runbook logic.

How are worker updates delivered?

BigPanda releases updated container images. Download and deploy updates according to your organization's change management process.

Get Help

If you run into any issues or need help with your deployment, contact BigPanda support at [email protected] with:

Your worker version (docker images | grep adr-temporal-worker)
Relevant logs (docker logs --tail 200 adr-temporal-worker)
Steps to reproduce the issue

For broader L1 Agent capabilities, see the BigPanda L1 Agent overview. For the security posture, including the SOC 2 Type II report and the worker security and trust brief, visit the BigPanda Trust Center.

In this section: