> ## 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.

# Quickstart

> Connect your first source and preview data in under 15 minutes.

This walkthrough gets you from a fresh sevvo account to a live Postgres
connection with a working preview query. You will deploy the data-plane agent
into your own environment, point it at a Postgres database, and confirm the
round-trip by running a `SELECT` from the sevvo UI.

## Before you start

You will need:

* A sevvo workspace. Sign in at [app.getsevvo.com](https://app.getsevvo.com)
  and create or join an organization.
* A host you control that can run a container and reach the public internet on
  outbound port 443. A developer laptop works for testing; any Linux VM,
  Kubernetes pod, or ECS task works for production.
* A Postgres database the agent can reach, plus credentials with read access
  to the tables you want to preview.
* An HTTPS URL for the agent that your browser can reach. This can be a private
  hostname available only while you are connected to your VPN.

You do not need to allow inbound connections from sevvo's control plane. You
do need to allow console users' browsers to reach the agent from your internal
network or VPN.

## 1. Provision an agent deployment

In the sevvo UI, open **Settings → Agent deployments** and click
**Provision**. sevvo creates a deployment token for this agent and reveals it
once:

* `SEVVO_AGENT_TOKEN`

Copy it now. You can rotate it later by clicking **Revoke and reprovision**
on the same page.

## 2. Run the agent

The agent ships as a single Docker image. The minimum configuration is the
deployment token:

```bash theme={null}
docker run --rm \
  -e SEVVO_AGENT_TOKEN=... \
  -p 8080:8080 \
  ghcr.io/sevvo/agent:latest
```

You should see a polling log line for `tenant-{orgId}` followed by
`[agent] health server listening on :8080`. `curl http://localhost:8080/healthz`
should return `ok`.

See [Deploying the agent](/deploying-the-agent) for the full reference — TLS
for Temporal, canonical output URIs, AWS credentials for S3 sinks, etc.

## 3. Connect the console to the agent

Expose the agent through an internal HTTPS URL, for example
`https://sevvo-agent.corp.internal`. In **Settings → Agent deployments**, open
the deployment and enter that data-plane URL.

The hosted console calls this URL from your browser. The hostname can remain
private and resolve only on your VPN; sevvo's control-plane servers do not need
to reach it. Use `http://localhost:8080` only for local development.

Test the connection from the console. If it fails, confirm that the same
browser can load `https://sevvo-agent.corp.internal/healthz` while connected to
the VPN.

## 4. Confirm the agent is registered

Back in the sevvo UI, the **Agent deployments** page should now show your
agent as **Connected**, with a recent heartbeat timestamp. If it stays on
**Pending** for more than a minute, see
[Deploying the agent → Troubleshooting](/deploying-the-agent#troubleshooting).

## 5. Add a Postgres connection

Open **Connections → New connection**, pick **Postgres**, and fill in host,
port, database, username, password, and SSL mode. Click **Test connection**.
Your browser asks the agent at the configured data-plane URL to test the
credentials from the agent's network. On save, native database credentials are
stored on the control plane as a temporary JSON payload until encrypted vault
storage lands.

On success, you will see **Connected** and a `validatedAt` timestamp.

## 6. Run a preview query

From your new connection, click **Preview query** and enter a read-only
statement:

```sql theme={null}
select id, email, created_at
from public.users
order by created_at desc
```

The agent executes the query against your database, caps the result at 100
rows, sanitizes values, and returns a small tabular payload directly to your
browser for the UI to render. Preview rows do not pass through sevvo's control
plane. See [Security](/security#browser-direct-preview-queries) for the
controls applied to this path.

## Next steps

* [Connecting Postgres](/connecting-postgres) — field-by-field reference, SSL
  modes, and least-privilege user setup.
* [Security](/security) — what sevvo sees and what stays in your perimeter.
* [Architecture](/architecture) — how the control plane and data plane fit
  together.