TuneVault Docs

Getting Started

Prerequisites

TuneVault works with any Oracle database accessible from a Linux server. The agent is a single Python process — no root required for read-only checks.

Requirement	Details	Status
Oracle Database	12c, 18c, 19c, 21c, 23ai (12.1+). EBS 12.2 supported for EBS Operations tab.	Required
Linux server	Oracle Linux 7/8/9, RHEL 7/8/9, Amazon Linux 2/2023, Ubuntu 20.04+. The agent runs on any server that can reach the DB — does not need to be the DB host itself.	Required
Python	Python 3.6+ (standard on all supported OS versions). cx_Oracle / oracledb installed automatically by the installer if Oracle Instant Client is found.	Required
Outbound port 443	Agent polls `tunevault.app` every 25 seconds over HTTPS. No inbound ports, no firewall rules, no VPN.	Required
DB user	`tunevault_reader` role with SELECT_CATALOG_ROLE. Script at /docs/privileges.	Required
systemd	For persistent agent process. Falls back to nohup if systemd is unavailable.	Recommended

Agent Install

The installer downloads the agent, creates a service user, installs the systemd unit, and registers the connection — all in under 60 seconds.

Get your install token from /connections/new, then run on your Oracle server:

curl -fsSL https://tunevault.app/install.sh \
  | sudo TUNEVAULT_TOKEN=<your-token> bash

The installer will:

Download oracle-proxy.py to /opt/tunevault/
Create a tunevault service user (no shell, no sudo)
Install and start the tunevault-agent.service systemd unit
Register the agent with TuneVault and show a green checkmark in the UI

EBS note: On an EBS app tier, the installer also detects $CONTEXT_FILE, extracts s_base, and writes APPS_ENV_FILE to agent.env so EBS Operations commands can source EBSapps.env automatically.

Verify installation

                systemctl status tunevault-agent
# Expected: Active: active (running)

journalctl -u tunevault-agent -n 20
# Look for: "Agent registered" or "Heartbeat OK"
            

Add Connection

1

Open Add Connection

Go to /connections/new in TuneVault. This generates a one-time install token (30-minute TTL).

2

Run the install command on your server

Copy the pre-filled curl | bash command from the wizard and run it on the Oracle server as root or a sudo user.

3

Create the tunevault_reader DB user

Run the setup script from /docs/privileges in SQL*Plus as SYSDBA. This creates a least-privilege read-only role — no DML access, no DDL, SELECT_CATALOG_ROLE only.

4

Watch the agent come online

The wizard polls for the agent heartbeat. When it appears, you'll see a green checkmark and the connection is ready.

5

Run your first health check

Click Run Health Check from the Connections page. Results appear in 30–90 seconds.

Run Your First Health Check

From /connections, click Run Check on your connection. TuneVault runs 200+ checks in parallel across 13 categories and returns results in 30–90 seconds.

You'll land on the report page with a score, AI summary, and per-category findings. The report is automatically saved — you can return to it from /reports any time.

Tip: Enable autonomous monitoring in Connection Settings → Schedule to run checks every 4–24 hours and get email alerts on new critical findings.

Understanding Your Health Report

Score Ranges

The overall score is a weighted composite across 13 check categories. Each category contributes a percentage of the total based on its risk impact. A score above 80 is healthy for a production database; anything under 60 warrants investigation.

80–100

All checks passing or minor warnings. Normal production state.

● Healthy

60–79

Multiple warnings or one critical finding. Review and remediate within the week.

● Warning

40–59

Critical findings present. Risk of performance degradation or data loss.

● Critical

0–39

Multiple critical issues. Immediate action required — do not defer.

● Emergency

What affects the score most

Category	Weight	What it checks
Backup & Recovery	25%	RMAN last run, archivelog mode, FRA usage, guaranteed restore points
Performance	20%	Wait events, buffer cache hit ratio, shared pool fragmentation, PGA usage
Security	15%	Default passwords, PUBLIC grants, auditing config, sys login policy
Space Management	15%	Tablespace usage, segment growth, undo retention, temp usage
Other categories	25%	Active sessions, objects, jobs, parameters, patch level, RAC, replication

Finding Severity

Each individual check returns one of three severities:

Severity	Meaning	Action
● Critical	Immediate risk: data loss, corruption, compliance breach, or imminent outage.	Remediate within 24 hours. TuneOps tickets auto-created for critical findings.
● Warning	Degraded or sub-optimal configuration. Performance or risk impact if left unaddressed.	Review within the week. Include in your next DBA maintenance window.
● OK	Check passed. Value is within healthy thresholds.	No action required.

AI Summary

After all checks complete, TuneVault sends a structured snapshot of findings to GPT-4o. The AI summary appears at the top of your report and contains:

Executive summary — 2–3 sentence plain-English description of the database state
Top action — the single highest-impact remediation step to take now
Structured recommendations — per-finding fix suggestions with confidence level and SQL where applicable

The AI has no access to your actual data — it only sees check IDs, metric values, and severity labels. The prompt and model (GPT-4o) are logged in analysis_runs.

TuneBot (the chat icon) uses the same health check context and is powered by Claude Sonnet. Ask it "why is my buffer cache hit ratio low?" and it will answer with your actual metric values from the latest run.

Diagnostic SQL

Every finding includes the exact SQL that produced it, shown in a collapsible Evidence panel on the report page. You can copy it and run it directly in SQL*Plus or the built-in SQL Console.

Example — checking RMAN last backup:

SELECT TO_CHAR(MAX(completion_time), 'YYYY-MM-DD HH24:MI') AS last_backup,
       ROUND((SYSDATE - MAX(completion_time)) * 24, 1) AS hours_ago
FROM   v$backup_piece
WHERE  status = 'A';

The full catalog of 92 check definitions — including SQL, thresholds, and remediation text — is available at /docs/privileges and via the MCP API.

Security & Trust

Architecture

The agent makes outbound HTTPS connections only. TuneVault never initiates a connection into your network — there are no inbound ports, no VPN tunnels, no SSH from our side.

Your server

oracle-proxy.py

HTTPS poll / push

port 443 outbound only

TuneVault cloud

tunevault.app

Agent polls the TuneVault API every 25 seconds for pending commands
Results are pushed back over the same outbound connection
API key is AES-256-GCM encrypted at rest in our database
All traffic is TLS 1.2+ — the agent verifies the certificate
Agent runs as a dedicated tunevault OS user with no shell and no sudo rights

What We Read

TuneVault queries only Oracle catalog views — the same views your DBAs query manually every day. No application tables, no user data, no business data.

                -- Core Oracle catalog views accessed by tunevault_reader:
V$DATABASE, V$INSTANCE, V$VERSION, V$PARAMETER
V$SESSION, V$SQL, V$SQLSTATS, V$ACTIVE_SESSION_HISTORY
V$BACKUP_PIECE, V$ARCHIVED_LOG, V$RECOVERY_FILE_DEST
V$TABLESPACE, V$DATAFILE, V$TEMPFILE, V$SEGMENT_STATISTICS
V$RMAN_BACKUP_JOB_DETAILS, V$BLOCK_CHANGE_TRACKING
DBA_TABLESPACES, DBA_USERS, DBA_OBJECTS, DBA_INDEXES
DBA_JOBS, DBA_SCHEDULER_JOBS, DBA_SYS_PRIVS
DBA_SEGMENTS, DBA_FREE_SPACE, DBA_EXTENTS
-- EBS environments also grant (as APPS):
FND_CONCURRENT_QUEUES, FND_SVC_COMPONENTS,
FND_NODES, AD_ADOP_SESSIONS, FND_PROFILE_OPTION_VALUES
            

The full privilege setup script is at /docs/privileges. You can review every grant before running it.

What We Never Do

No DML — no INSERT, UPDATE, DELETE, or MERGE on any table
No DDL — no CREATE, ALTER, DROP of any object
No access to application tables or user data
No storage of query results beyond the health check run (results are your data, not ours)
No shell commands without your explicit confirmation — each EBS Operations action requires a click
No cold outreach — emails only to users who have signed up or opted in

EBS Operations commands (CM control, WF Mailer, ADOP) run through a whitelist enforced in the agent. The complete whitelist is live at /security/commands.

Source & Verification

The agent source is available for review. You can inspect every line before installing:

                # Download and inspect the agent before installing
curl -fsSL https://tunevault.app/oracle-proxy.py | less

# Or verify the SHA-256 hash matches what's on the trust page
curl -fsSL https://tunevault.app/oracle-proxy.py | sha256sum
curl -s https://tunevault.app/oracle-proxy.py.sha256
            

Agent source: tunevault.app/oracle-proxy.py
Installer source: tunevault.app/install.sh
SHA-256 hash (live, computed at request time): tunevault.app/oracle-proxy.py.sha256
Full trust center with architecture, command whitelist, and data handling: /trust
Security page for CISO review: /security