Deploying the agent

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. For interactive features, the hosted sevvo console connects from the user’s browser directly to the agent over the customer’s network. The sevvo control plane never initiates an inbound connection to the agent.

What the agent is

A NestJS app that embeds a Temporal worker and a data-plane HTTP API. It depends on three things you provide:

Outbound HTTPS (443) to sevvo’s endpoints and your Temporal address. In most environments, no additional egress rules are needed.
Network reachability to your sources for connectors you run through the agent, such as Postgres preview queries.
An HTTPS data-plane URL reachable from your users’ browsers, such as https://sevvo-agent.corp.internal. The URL may resolve only while the user is connected to your VPN.

The agent does not require Redis, a cloud secret manager, or a publicly accessible load balancer. You may expose it through an internal load balancer, private ingress, or reverse proxy that is reachable only from your VPN.

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 internal DNS name and TLS certificate trusted by the browsers that will use the sevvo console. Local development can use http://localhost:8080.
An agent deployment provisioned in the sevvo UI (see Quickstart → Provision an agent deployment).

Environment variables

Required:

Variable	Purpose
`SEVVO_AGENT_TOKEN`	Deployment 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_URL`	Postgres DSN for agent-local state, including AI chat threads, messages, sandbox state, and artifacts.

Optional:

Variable	Default	Purpose
`SEVVO_TEMPORAL_ADDRESS`	`temporal.getsevvo.com:7233`	Temporal frontend address. Override only if sevvo gives you a different endpoint.
`SEVVO_TEMPORAL_NAMESPACE`	`default`	Temporal 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_PORT`	`8080`	Port the data-plane HTTP API listens on, including health, connector, preview, and AI routes.
`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_MODEL`	provider default	Optional deployment default used by AI chat requests that omit a model override.
`SEVVO_AI_SANDBOX_BACKEND`	`local`	AI sandbox backend: `local`, `docker`, or `daytona`. Cloud-hosted agents can use `daytona`; self-hosted defaults local.
`SEVVO_AI_SANDBOX_WORKSPACE_BASE_DIR`	SDK default	Local 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.

Expose the data-plane URL

Choose a base URL that users can reach from their browsers while connected to your network, for example:

https://sevvo-agent.corp.internal

Enter this URL for the agent deployment in the hosted sevvo console. The browser resolves and calls the URL directly; sevvo’s control-plane servers do not proxy the request and do not need network access to the hostname. Use HTTPS in production. Because the hosted console is served over HTTPS, browsers will block calls to a plain-HTTP data-plane URL other than local development exceptions such as localhost. Allow inbound traffic only from the user networks that need the console, and configure the agent or its reverse proxy to accept requests from the sevvo console origin.

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

The published port is suitable for local testing. In production, place it behind your internal TLS endpoint and give console users that HTTPS URL.

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

containerPort alone does not make the agent reachable from a user’s browser. Add an internal Kubernetes Service plus a private ingress or internal load balancer, then use its HTTPS hostname as the deployment’s data-plane URL. The exact annotations depend on your cluster and cloud provider. 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. The console cannot connect to the data-plane URL. Open the URL from the same browser while connected to the VPN and verify that /healthz returns ok. Check private DNS, the TLS certificate, firewall or security-group rules, Kubernetes Service/Ingress configuration, and the URL saved for the deployment. Testing the URL from sevvo’s control-plane network is not meaningful because the browser makes this connection directly. 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.

Get started

Guides

Concepts

Deploying the agent

What the agent is

Prerequisites

Environment variables

Expose the data-plane URL

Docker

Kubernetes

Health checks

Upgrading

Troubleshooting

​What the agent is

​Prerequisites

​Environment variables

​Expose the data-plane URL

​Docker

​Kubernetes

​Health checks

​Upgrading

​Troubleshooting

What the agent is

Prerequisites

Environment variables

Expose the data-plane URL

Docker

Kubernetes

Health checks

Upgrading

Troubleshooting