Documentation

# TuneVault Docs

Everything you need to install the agent, understand your Oracle health report, and trust the security model.

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.

Self-hosted? Run TuneVault on its own server. The TuneVault app installs on a dedicated Linux server, separate from your Oracle DB / EBS servers — putting it on a database or EBS host risks port conflicts, resource contention, and PostgreSQL clashing with Oracle. Any Oracle Linux 8 box (RHEL 8–9 also work) with 2 GB+ RAM and 10 GB+ disk is enough.

- The `oracle-proxy` agent (below) installs separately on each Oracle/EBS server you monitor — TuneVault detects it automatically once it's running.
- Agents dial out over HTTPS to the TuneVault server (a self-hosted install polls your own server, not tunevault.app) and open no inbound ports on your Oracle servers — so TuneVault can sit in a DMZ, a management VM, or any internal host your Oracle servers can reach outbound.
- Alternative — Direct TCP (no agent): skip the agent and TuneVault connects straight to the Oracle DB listener (default port 1521); in that mode the TuneVault server needs outbound access to the database on that port.
- Telemetry is off by default. A self-hosted install sends nothing outbound unless you opt in. Setting `TELEMETRY_OPT_IN=true` in `.env` sends a single anonymous startup ping (TuneVault version, Node.js version, platform) — no PII, no credentials, no connection or database data.

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

Database Operations

## Runbooks & Cloning

Step-by-step operational runbooks for common Oracle and EBS lifecycle tasks — styled for in-app reference and safe to hand to your DBA team.

Oracle EBS 12.2 + 19c RAC Clone (RMAN Duplicate). End-to-end procedure to clone an EBS 12.2 environment on a 2-node Oracle 19c RAC cluster using RMAN Active Database Duplicate — ASM, CDB/PDB, single-instance-to-RAC conversion, EBS Rapid Clone, post-clone tasks, RAC node addition, and a post-clone validation checklist. Read it at /docs/ebs-rac-clone.

- EBS 12.2 + 19c RAC Clone Using RMAN Duplicate — complete 10-section runbook
- Privilege Setup — the least-privilege `tunevault_reader` role

### Ready to connect your first database?

The agent installs in 60 seconds. Your first health check runs in under 2 minutes.

Add Connection → Trust Center