Skip to main content
The agent is a single container image that runs inside your perimeter. It extracts from your sources, builds canonical models, and writes to your destinations. It connects outbound to sevvo’s control plane and Temporal cluster — no inbound ports need to be opened.

​
What the agent is

A NestJS app that embeds a Temporal worker and a small HTTP server. It depends on two things you provide:
  1. Outbound HTTPS (443) to sevvo’s endpoints and your Temporal address. In most environments, no additional egress rules are needed.
  2. Network reachability to your sources for connectors you run through the agent, such as Postgres preview queries.
The agent does not require Redis, a cloud secret manager, or an inbound load balancer.

​
Prerequisites

  • Docker 24+ (or any OCI runtime — Kubernetes, ECS, Nomad, Fly, Railway all work).
  • A Postgres 14+ database the agent can reach. A 1 vCPU / 1 GB instance is ample for v1.
  • Outbound 443 to *.getsevvo.com and your Temporal address.
  • An agent deployment provisioned in the sevvo UI (see Quickstart → Provision an agent deployment).

​
Environment variables

Required:
VariablePurpose
SEVVO_AGENT_TOKENDeployment token revealed once during provisioning. The agent unwraps it, exchanges it for a short-lived bearer, and derives the org-scoped task queue from the returned JWT.
SEVVO_AGENT_DATABASE_URLPostgres DSN for agent-local state, including AI chat threads, messages, sandbox state, and artifacts.
Optional:
VariableDefaultPurpose
SEVVO_TEMPORAL_ADDRESStemporal.getsevvo.com:7233Temporal frontend address. Override only if sevvo gives you a different endpoint.
SEVVO_TEMPORAL_NAMESPACEdefaultTemporal namespace.
SEVVO_TEMPORAL_TLS_CERT—Base64-encoded client certificate for mTLS to Temporal. Must be set together with SEVVO_TEMPORAL_TLS_KEY.
SEVVO_TEMPORAL_TLS_KEY—Base64-encoded client private key.
SEVVO_HEALTH_PORT8080Port the HTTP server listens on (/healthz, /metrics).
OPENAI_API_KEY—Required only for the AI analyst chat endpoint. Kept in the agent environment so inference runs from the data plane.
SEVVO_AI_ANALYST_MODELprovider defaultOptional model override for the AI analyst.
SEVVO_AI_SANDBOX_BACKENDlocalAI sandbox backend: local, docker, or daytona. Cloud-hosted agents can use daytona; self-hosted defaults local.
SEVVO_AI_SANDBOX_WORKSPACE_BASE_DIRSDK defaultLocal workspace base directory for AI sandbox sessions.
DAYTONA_API_KEY / DAYTONA_API_URL / DAYTONA_TARGET—Required only when SEVVO_AI_SANDBOX_BACKEND=daytona.
SEVVO_CANONICAL_OUTPUT_BASE_URI—Base URI for canonical model output (e.g. s3://my-bucket/canonical/). Required before the first sync.
AWS_REGION / AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN / AWS_ENDPOINT_URL_S3—Standard AWS SDK variables. Needed only if the canonical sink writes to S3. IAM roles on the host are also supported.
The agent validates its environment on boot and refuses to start with a detailed error listing every missing or malformed variable.

​
Docker

docker run --detach --restart=always \
  --name sevvo-agent \
  -e SEVVO_AGENT_TOKEN=... \
  -e SEVVO_AGENT_DATABASE_URL=postgresql://user:pass@host:5432/sevvo_agent \
  -p 8080:8080 \
  ghcr.io/sevvo/agent:latest

​
Kubernetes

A minimal Deployment. Mount the deployment token from a Secret; keep non-secret config in a ConfigMap. 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sevvo-agent
spec:
  replicas: 1
  selector:
    matchLabels: { app: sevvo-agent }
  template:
    metadata:
      labels: { app: sevvo-agent }
    spec:
      containers:
        - name: agent
          image: ghcr.io/sevvo/agent:latest
          ports:
            - containerPort: 8080
          envFrom:
            - configMapRef: { name: sevvo-agent-config }
            - secretRef: { name: sevvo-agent-secrets }
          livenessProbe:
            httpGet: { path: /healthz, port: 8080 }
            periodSeconds: 10
          readinessProbe:
            httpGet: { path: /healthz, port: 8080 }
            periodSeconds: 5
Run a single replica per deployment. The Temporal worker is horizontally scalable, but v1 is sized for a single agent per tenant; contact us if you need to scale out.

​
Health checks

  • GET /healthz returns 200 ok once the Temporal worker has connected. Use it for liveness and readiness probes.
  • GET /metrics is reserved for a Prometheus endpoint — no metrics are exposed yet.

​
Upgrading

Upgrades are image-tag swaps. The control plane cannot execute code on your agent remotely; you control the rollout by changing the image tag in your Deployment / Docker run command. Workflow definitions are versioned so in-flight executions replay safely across agent upgrades. We recommend pinning to a specific tag (e.g. ghcr.io/sevvo/agent:2026.4.2) rather than latest in production.

​
Troubleshooting

Agent stays on “Pending” in the UI. Check the agent’s logs for the polling line and a healthy HTTP listener. The most common causes are a mistyped SEVVO_TEMPORAL_ADDRESS or a revoked deployment token. Reprovision the deployment and relaunch with the new value. Invalid agent environment on boot. The container exits with a list of every invalid variable. Fix them and restart — the agent does not partially start. SEVVO_TEMPORAL_TLS_CERT and SEVVO_TEMPORAL_TLS_KEY must be set together. If you enable mTLS, you must provide both. They must be base64-encoded PEM blobs (including headers). Preview queries fail with connection refused. The agent runs the query — not the control plane. The source database must be reachable from the agent’s host, not from sevvo’s network. connection is not found when running a sync. The agent resolves connector credentials through the control plane at runtime. Re-save the connection from the UI if its control-plane credential payload is missing or stale.