Installation
AgentData installs from a versioned release package onto your own machine — a Windows laptop for a proof of concept, a macOS/Linux workstation, or a Linux server. One script installs everything, runs the database migration, and points you at a guided setup wizard. If you only want to try AgentData, the hosted app needs no install at all.
What a release package contains
Each release ships as an archive per operating system, built from one source tree:
| File | For |
|---|---|
agentdata-<version>-windows.zip | Windows 10/11 |
agentdata-<version>-unix.tar.gz | macOS and Linux |
release.yaml | Version, schema version and SHA-256 checksums |
Verify the checksum of the archive you downloaded against release.yaml before unpacking.
Minimum system requirements
| Windows | macOS | Linux | |
|---|---|---|---|
| OS version | Windows 10 21H2 or Windows 11 (winget is required) | macOS 13 Ventura or later | Ubuntu 22.04+ / Debian 12+ / RHEL-family 9+ (apt or dnf) |
| CPU | x64, 4 cores | Apple Silicon or Intel, 4 cores | x64 or arm64, 4 cores |
| RAM | 8 GB (16 GB recommended) | 8 GB (16 GB recommended) | 8 GB (16 GB recommended) |
| Disk | 10 GB free | 10 GB free | 10 GB free |
| Runtimes | Python 3.10+, Node.js 18+, PostgreSQL 14+ — installed by install.ps1 via winget if missing | same — installed via Homebrew | same — installed via apt/dnf |
Notes:
- 8 GB RAM runs the full Tier-1 stack (backend, MCP, UI, Data API, PostgreSQL) for a POC. Move to 16 GB when running data flows over large tables, or raise
flows.defaults.bulk_rows-sized pipelines on the same machine. - Federation (Trino + Cube) is optional and containerized: it additionally requires Docker Desktop — on Windows that means WSL2 and roughly +8 GB RAM. Skip it unless a single query must join different source systems.
- Heavy pipelines (hundreds of millions of rows) belong on a dedicated transform node rather than the POC machine: a Linux host sized from the in-app capacity estimator, typically 16–32 GB RAM. The POC machine then delegates runs to it (
flows.transform_url). - The document engine (Docling) runs hosted by default and adds no local requirement.
Network prerequisites (restricted environments)
On a machine behind a strict firewall, ask the network team to open the endpoints below before installation day. Everything is outbound HTTPS (port 443) unless noted.
One-time installs
These runtimes install once; the installer fetches them through the OS package manager, which needs its own repositories reachable:
| Requirement | Downloaded from |
|---|---|
| Python 3.10+ | python.org/downloads — or via winget / Homebrew / apt / dnf |
| Node.js 18+ | nodejs.org/download — or via winget / Homebrew / apt / dnf |
| PostgreSQL 14+ | postgresql.org/download — or via winget / Homebrew / apt / dnf |
When the package manager is used, also allow its repository hosts (Windows winget: cdn.winget.microsoft.com; macOS Homebrew: github.com, ghcr.io, formulae.brew.sh; Linux: the distro's apt/dnf mirrors).
Docker — only when federation is in scope
Docker is not part of a standard installation. Request it only when the POC needs cross-source joins (the Trino + Cube federation pair) — see Cross-source joins below:
| Requirement | Endpoint |
|---|---|
| Docker Desktop (Windows/macOS) or Docker Engine (Linux) — one-time install | docker.com/products/docker-desktop — or via the OS package manager; Windows additionally needs WSL2 enabled |
Image pulls (docker compose up) | Docker Hub: registry-1.docker.io, auth.docker.io, production.cloudflare.docker.com |
If Docker Hub cannot be opened, the same GitHub-bundle alternative applies: the exact Trino and Cube images are exported with docker save and attached to a GitHub release, then imported on the closed machine with docker load — only the GitHub endpoint below is needed.
Package registries — keep open for the project duration
AgentData is under active development: updates during an engagement routinely add libraries, so these registries should stay reachable rather than being opened once:
| Endpoint | Used for | Driven by |
|---|---|---|
pypi.org, files.pythonhosted.org | Python packages (pip install) | backend/requirements.txt |
registry.npmjs.org | UI packages (npm install) | ui/package.json |
If registry access cannot be granted at all, an alternative is a pinned dependency bundle: the required Python wheels and node_modules are packaged as a zip in the GitHub repository per release, and only the GitHub endpoint below is needed to refresh it. Ask for this option explicitly — the open-registry setup is preferred while the product evolves.
Source code — GitHub
| Endpoint | Used for |
|---|---|
github.com, api.github.com, codeload.github.com, objects.githubusercontent.com | Cloning and updating the AgentData repository, and downloading release assets |
During a migration project the code is updated in place from the repository — fixes and customer-specific changes land there and pull straight to the installed machine — so direct GitHub access is strongly preferred over carrying archives by hand.
LLM provider — customer-supplied access
AgentData requires one LLM endpoint; the customer chooses which, in this order of preference:
| Option | Endpoint |
|---|---|
| 1. Anthropic (recommended) | api.anthropic.com |
| 2. AWS Bedrock | bedrock-runtime.<region>.amazonaws.com — also works fully privately through a VPC interface endpoint (PrivateLink), with no public internet |
| 2. Google (Gemini) | generativelanguage.googleapis.com |
| 3. OpenAI-compatible | api.openai.com — also used by the optional embeddings feature; a local OpenAI-compatible server (Ollama/vLLM) works with no egress at all |
Supporting services
| Endpoint | Used for |
|---|---|
| Your hosted Docling URL | Document OCR/extraction — only when Documents Automation is in scope (or run Docling locally) |
github.com (release assets, above) | AgentDesk installer download — the migration project is managed in AgentDesk; its MSI package ships self-contained with its dependencies pre-bundled, so no further endpoints are needed for it |
Customer data sources (SQL Server, Oracle, AS400, file shares) live on the internal network and need no internet access.
Windows
Everything runs natively — Python backend services, the React UI and PostgreSQL. Docker is not required for a standard installation.
- Unpack the
.zipand open PowerShell in the unpacked folder. - Run the installer:
.\install.ps1
The script installs missing prerequisites with winget (Python 3, Node.js, PostgreSQL), creates the registry database, installs dependencies, applies the database schema, and prints the setup-wizard URL. Re-running it later is safe — it updates in place.
- Start the stack and open the wizard:
.\start-all.ps1
# → http://localhost:5173/setup
Cross-source joins (optional)
Queries against a single source run natively and need nothing extra. Only if you join different source systems in one query does AgentData use its federation pair (Trino + Cube), which runs in containers — Trino is Linux-only. Install Docker Desktop, enable federation.enabled in config.yaml, and start-all.ps1 brings the pair up automatically via docker compose.
macOS and Linux
- Unpack the
.tar.gzand open a terminal in the unpacked folder. - Run the installer:
./install.sh # add --start to also launch the stack
Prerequisites install through Homebrew (macOS) or apt/dnf (Linux). The same script handles updates — re-run it on a newer unpacked release.
On a Linux server you can instead run the stack with docker compose (the same images used by cloud deployments); the native path above remains the quickest for a workstation.
The setup wizard
After installation, open http://localhost:<ui-port>/setup (the installer prints the exact URL) and sign in with an administrator account. The wizard walks the remaining configuration — LLM provider key, document engine (Docling) URL, your data sources — each on its normal settings screen, then runs the prerequisite checks:
- registry database and schema version
- LLM provider access
- document engine (Docling) reachability
- a live connection test for every registered source, including reporting platforms
Every check shows pass/fail with the reason, so a missing firewall rule or wrong credential is visible before your first demo. The same checks run from the shell:
python scripts/check-prerequisites.py
Updating to a new release
Releases are published on demand, not on a schedule. To update:
- Unpack the new release next to the old folder and copy your
.env(and anyconfig.yamledits) over. - Run the installer again (
install.ps1/install.sh).
The migration step compares the installed schema version with the release's and fails closed rather than guessing:
- Same schema version — the update applies in place; your data is untouched.
- Changed schema version — the installer stops and asks for an explicit upgrade:
./install.sh --upgrade-schema # Windows: .\install.ps1 -UpgradeSchema
An upgrade recreates the registry tables from the new schema. User accounts, tenants and memberships are always preserved, but discovered models, sources and other working data are reset — export anything you want to keep first. This keeps POC updates simple and predictable.
A clean install on a fresh database always applies the full current schema in one step.