Victoria is Elcano's AI agent for navigating programmatic advertising datasets. Ask natural-language questions of CSVs, Excel workbooks, and SQL-queryable sources to surface insights without leaving the terminal.
- Container-first distribution. Victoria ships as a Podman image that packages Python, the
crushCLI, and required dependencies. The container isolates the agent from the host OS while still allowing controlled file sharing via~/Victoriawhen you opt to mount it. - Task isolation without sharing directories. Automated runs launched with
victoria --taskcan execute entirely inside the container without mounting a host workspace, eliminating the need to expose local files during read-only operations. - Secrets stay in your control. Provide API keys as environment variables when you launch the container or store them in
~/Victoria/.envif you choose to mount that directory. Victoria consumes credentials at runtime without persisting new secrets to disk. - Transparent builds. GitHub Actions builds and publishes the container to
ghcr.io/elcanotek/victoria-terminal, ensuring every release is reproducible and verified in CI. - Source-available license. Usage is governed by the Victoria Terminal Business Source License (BUSL-1.1). See LICENSE for details.
- Contributor license agreement. Submitting a patch, issue, or other material constitutes acceptance of the ElcanoTek Contributor License Agreement.
Victoria renders a richly styled terminal experience. Use a modern, standards-compliant emulator that supports OSC-52 and 24-bit color. To get the best results, pick a contemporary terminal such as:
- Ghostty (Linux and macOS) — recommended for its deep feature support.
- Windows Terminal (Windows only) which offers solid OSC-52 and 24-bit color support out of the box.
Podman is required for every installation option. Install it first, then verify the setup with podman --version.
- macOS and Windows: Install Podman Desktop from podman.io.
- Linux: Install Podman with your distribution's package manager.
The fastest way to get Victoria on your machine is the guided installer. It checks for Podman, ensures your ~/Victoria workspace exists, detects the host architecture, pulls the matching container image tag, and adds a reusable victoria command to your shell profile.
- macOS / Linux
curl -fsSL https://raw.githubusercontent.com/ElcanoTek/victoria-terminal/main/install_victoria.sh | bash - Windows (PowerShell)
& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/ElcanoTek/victoria-terminal/main/install_victoria.ps1')))
After the helper finishes, open a new terminal session (or reload your profile with source ~/.bashrc, source ~/.zshrc, or . $PROFILE) and start Victoria with a single command:
victoriaRe-run the script any time you want to refresh the alias. It will not reinstall Podman, but it will remind you to start podman machine on macOS and Windows if needed.
Victoria can execute non-interactive tasks when launched with the --task flag:
victoria --task "create a Gamma presentation on this week's optimizations and email it to [email protected]"Use clear, production-ready instructions in the quoted task string—automation jobs frequently power integration tests and CI workflows. The example above mirrors the internal integration scenario we maintain; adapt the prompt to match the workflow you need to validate. When automations require filesystem output, specify both the filename and the directory inside your mounted ~/Victoria workspace so downstream jobs can inspect the results.
Need manual commands, pre-built image instructions, or the full development workflow? Head over to CONTRIBUTING.md for step-by-step guidance on running published container images and building Victoria from source.
We welcome contributions to Victoria! Review our Contributing Guidelines for the full development workflow, workspace anatomy, and pull-request expectations.