Post-Install Setup

Once your TraceVault server is deployed, the steps below take you from an empty instance to a fully functional setup — admin account, LLM-powered features, connected GitHub repositories, and team access.

You can skip any optional step and come back to it later.

1. Bootstrap the First Admin

The first thing a fresh TraceVault server needs is a user. Open your server URL in a browser — the signup page creates the first organization and its owner in a single step.

You will be asked for:

  • An organization slug — lowercase letters, digits, and hyphens (this becomes your URL path, e.g. /orgs/acme)
  • An email and a password
  • Optionally, your display name

Once this first account is created, public registration is disabled automatically. Any further users must be invited from inside the app (see step 5). If you lose access to the first account before inviting others, you will need to reset state at the database level, so store the credentials somewhere safe.

2. Configure an LLM Provider (Optional)

TraceVault uses an LLM to power two features:

  • Stories — AI-written narratives that explain how a block of code came to be, drawn from commits and recorded sessions
  • Chat summaries — optional summaries layered on top of chat search results

Without an LLM configured, the rest of the product still works; only these two features are gated on it.

Navigate to Settings → LLM (/orgs/{org}/settings/llm) and fill in:

Field Notes
Provider Anthropic or OpenAI
API Key Stored encrypted at rest; never returned to the browser once saved
Model Specific model name, or leave blank for the provider's default
Base URL Optional — use this if you route through a proxy or a self-hosted OpenAI-compatible endpoint

Only owners and admins can change LLM settings.

Encryption of the API key requires the server's TRACEVAULT_ENCRYPTION_KEY environment variable to be set. See the security note at the bottom of this page.

3. Register a Repository

Repositories are the unit TraceVault tracks commits, sessions, policies, and stories against. To register the first one, install the CLI on a developer machine, log in to the server, and run tracevault init inside the repo directory — see Getting Started for details.

After the first push, the repo appears under /orgs/{org}/repos.

4. Connect the Repository to GitHub

Connecting to GitHub unlocks three capabilities:

  • Code browser with syntax highlighting
  • Code attribution — matching committed lines back to the AI sessions that produced them
  • Push & tag tracking via webhooks

Everything below is configured per repository at Repo → Settings (/orgs/{org}/repos/{id}/settings).

4a. GitHub URL

Paste the SSH clone URL, e.g. git@github.com:acme/backend.git.

4b. Deploy Key (required for code browsing)

TraceVault clones the repo server-side using a read-only SSH deploy key you generate yourself:

ssh-keygen -t ed25519 -f tracevault-deploy-key -N ""

This produces two files:

  • tracevault-deploy-key — the private key (paste this into TraceVault)
  • tracevault-deploy-key.pub — the public key (add this to GitHub)

On GitHub:

  1. Go to the repository's Settings → Deploy keys → Add deploy key
  2. Paste the contents of tracevault-deploy-key.pub
  3. Leave Allow write access unchecked
  4. Save

In TraceVault, paste the contents of the private key file into the Deploy Key field and save. As soon as both the URL and the deploy key are present, the server clones the repo in the background. The page's Sync status shows cloning → ready, along with the last fetched timestamp.

5. Invite Team Members

Go to Settings → Members (/orgs/{org}/settings/members). Administrators can invite new users by email, picking a role at invite time:

Role What they can do
Owner Full control, including LLM and SSO settings
Admin Manage members, invites, pricing, LLM config, and compliance
Developer Push traces, view analytics and traces
Policy Admin Create and configure enforcement policies
Auditor Read-only: compliance data, audit logs, analytics

Each invitation produces a URL you can share with the invitee. Pending invites can be revoked; accepted, revoked, and expired invites appear in the history table.

6. Enable SSO (Enterprise, Optional)

If your organization runs an OIDC identity provider (Google Workspace, Azure AD, Okta, Keycloak, …), you can enable Single Sign-On at Settings → SSO (/orgs/{org}/settings/sso).

  • Issuer URL — e.g. https://accounts.google.com
  • Client ID / Client Secret — from your IdP
  • Allowed email domains — comma-separated; users outside these domains are rejected
  • Enforce SSO — disables password login for non-admins (owners and admins keep password access as break-glass)
  • Auto-provision — auto-create users on first SSO login, with a configurable default role

Only organization owners can change SSO configuration.

Security Checklist Before Going Live

  • Server is behind HTTPS (reverse proxy terminating TLS — see Server Setup)
  • TRACEVAULT_ENCRYPTION_KEY is set to a 32-byte base64-encoded value. This key is used to encrypt LLM API keys, deploy keys, SSO client secrets, and the org signing key. Without it, those fields cannot be stored encrypted.
  • First-admin credentials are saved in your password manager
  • At least one additional owner has been invited, so the instance is not single-person

What's Next?

  • CLI Reference — full command reference for developers
  • Repositories — what the web UI shows for each registered repo
  • Settings — full breakdown of the settings area
  • Policies — enforcing tool-call requirements per repository