Deployment Options
You choose who hosts your Earnie environment and which SCANOSS API it talks to. The SCANOSS API is the service that matches your code against the SCANOSS knowledge base, a large index of known open-source code.
In each option, the orange box is where Earnie runs and your source code lives. The dark box is the SCANOSS API, which receives fingerprints and package identifiers, never your source code.
SCANOSS-Hosted
SCANOSS runs your Earnie environment on its own servers and operates it for you, including upgrades, backups, and monitoring. Your source code is uploaded to, or fetched into, that environment. It stays isolated from every other customer’s environment and isn’t sent anywhere else. You don’t need any hardware. Choose this option when you don’t want to run or maintain servers yourself. Once SCANOSS has set up your environment, continue with Workspace setup.Self-Hosted Earnie
You run Earnie on your own servers, and it uses the SCANOSS API atapi.scanoss.com for matching. Your source code never goes to SCANOSS. Only the fingerprints, hashes, and package identifiers described in What leaves your environment go to SCANOSS.
Choose this option to keep source code in-house without running the SCANOSS knowledge base yourself. It needs one Linux server with Docker. AI provenance isn’t available in this option: it runs only when SCANOSS hosts Earnie. See Self-hosting requirements, then Installing Earnie and Upgrading and backing up.
Fully On-Premises
You run Earnie and your own SCANOSS installation, meaning the SCANOSS API and its knowledge base. Earnie sends its fingerprints and package identifiers to your SCANOSS API instead ofapi.scanoss.com. Choose this option when your fingerprints must not leave your network. The exceptions below still reach api.scanoss.com. To set this up, set Earnie’s SCANOSS_API_URL setting to the address of your SCANOSS API. See Installing Earnie.
This option needs the Earnie server and the much larger SCANOSS knowledge-base server. See Self-hosting requirements and the SCANOSS on-premises hardware requirements.
An on-premises SCANOSS installation doesn’t include everything api.scanoss.com serves. In the fully on-premises option:
- The side-by-side comparison of a match needs
api.scanoss.com. An on-premises SCANOSS installation can’t serve the open-source file content it shows, for now. Earnie fetches that content fromapi.scanoss.comeven whenSCANOSS_API_URLpoints at your own SCANOSS API, so you don’t need to set anything. Earnie still reports each match without it, but the comparison works only while your environment can reachapi.scanoss.com. Only the hash of the matched file is sent.
These limits apply to on-premises SCANOSS installations today and may change. Contact SCANOSS for the current status.
api.scanoss.com for file content, to download dependencies for cryptography scans, and the CISA Known Exploited Vulnerabilities feed. Earnie doesn’t support fully air-gapped networks yet. Network access lists every connection.
What Runs in Your Environment
Your environment runs all of Earnie:- The web app and the API. Everyone in your organisation signs in to the web app. The CLI, the pre-commit hook, CI pipelines, and coding agents connect to the API. Coding agents connect over MCP (Model Context Protocol), which the API also serves.
- A reverse proxy. It receives all incoming traffic on HTTPS and manages the TLS certificate.
- The scanners. Open-source matching runs inside the API. Cryptography detection and AI provenance each run as a separate worker, and your environment runs only the scanners your organisation has. Cryptography detection builds your dependencies in a sandbox with restricted network access.
- The database. It’s PostgreSQL. It holds your projects, findings, decisions, policies, approvals, and audit trail. It also holds Earnie’s job queue, so Earnie needs no other data store or message broker.
- A data volume. It holds the scan archives, which are the source each scan received, along with scan results and working caches.
- Earnie fetches it from a GitHub or GitLab repository you connected, including for pull and merge request checks.
- A producer uploads it. Producers are the Earnie CLI, the pre-commit hook, CI pipelines, coding agents running a Self-check, the REST API, and uploads in the web app. You can also import an SBOM or upload an AI model file.
What Leaves Your Environment
Everything inside the orange box stays there. The diagram shows the main traffic that crosses its edge. The sections below describe it in detail, along with the traffic the diagram leaves out: connections to other services and operational telemetry.To the SCANOSS Platform
In the SCANOSS-hosted and self-hosted Earnie options, this traffic goes toapi.scanoss.com. In the fully on-premises option, it goes to your own SCANOSS API instead. Every request carries your organisation’s SCANOSS API key.
Two things come back from SCANOSS in addition to scan results:
- Matched open-source file content. When you compare a match side by side, and during each scan that keeps the Snippet classification layer (up to 2,000 files per scan), your environment downloads the published open-source file from SCANOSS, by its hash. Only that public file travels, and only towards you. Your own file is read from your environment. In the fully on-premises option, this download still comes from
api.scanoss.com, because an on-premises SCANOSS installation can’t serve file content for now. - Detection rules. Your environment downloads the cryptography detection rules from SCANOSS. Detection itself runs inside your environment.
To Other Services
When you host Earnie yourself, the server also connects to the container registry to install and upgrade, and to Let’s Encrypt for its TLS certificate unless you provide your own. Network access lists these connections.
Earnie doesn’t send your code, findings, or results to any AI model provider.
Operational Telemetry
In the SCANOSS-hosted option, SCANOSS monitors the health of your environment. To do this, your environment sends SCANOSS two things:- Operational metrics. These are counters, durations, and identifiers, such as how many scans ran and how long they took, labelled with your environment’s name. They also include the host’s CPU, memory, disk, and network usage. The metrics contain no source code, file content, findings, or scan results.
- Service logs. These are the log output of Earnie’s services, which SCANOSS uses to diagnose problems.
What Never Leaves
- Your source code. It’s fingerprinted inside your environment. Only the fingerprints and hashes described above reach SCANOSS.
- Your findings, triage decisions, policies, and approvals. They stay in your environment’s database.
- Your scan archives and results. They stay on your environment’s data volume.
- Your SBOMs and other evidence. They’re generated inside your environment, and you decide where they go.
What’s Next
- If SCANOSS hosts Earnie for you, start with Workspace setup.
- Self-hosting requirements lists the hardware, software, and network access you need to run Earnie yourself.
- Installing Earnie shows how to install and configure it.
- Connecting a repository lists the exact permissions Earnie asks your Git provider for.
- Running your first scan shows how source reaches Earnie during a scan.