> ## Documentation Index > Fetch the complete documentation index at: https://docs.getsevvo.com/llms.txt > Use this file to discover all available pages before exploring further. # Deploying the agent > Install and operate the sevvo data-plane agent in your environment. 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: 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. 3. **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](/quickstart#1-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: ```text theme={null} 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 ```bash theme={null} 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`. ```yaml theme={null} 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.