---
slug: enterprise-installation
title: Enterprise Installation
section: Reference
description: Network, endpoint, and browser policy prerequisites for IT and security teams deploying OrcaSheets on managed Windows devices.
listed: true
navOrder: 5
---

# Enterprise Installation

**OrcaSheets is offline-first: customer data stays on the laptop unless someone shares a Dashboard or uses an AI feature. On managed devices, a few security controls can still block start-up or sign-in. This page lists what to permit, why, and how to verify it.**

> Applies to OrcaSheets desktop **26.9 and later**. Share this page with IT / Security when rolling out on locked-down Windows laptops.

**How to use it.** Section 1 is the one-page summary. Sections 2-3 are the allow-lists. Section 4 maps features to permissions. Section 5 covers what the app sends. Section 6 is the desk-side verification checklist.

Contact OrcaSheets support at `hello@orcasheets.io` with any question. We are happy to join a call with your security team.

## 1. Summary: what to enable

On a locked-down laptop the app needs exactly four things:

| # | Requirement | Why |
|---|---|---|
| 1 | Allow outbound HTTPS (443) to the OrcaSheets domains in §2.1 | Sign-in, licence token, AI chat, telemetry |
| 2 | Allow the OrcaSheets process to run `powershell.exe` (read-only WMI/CIM queries: see §3.1) | The licence is bound to the machine, and device identity is read via PowerShell. If PowerShell is blocked for the app, none of the sign-in options can complete. |
| 3 | Allow the installed binaries to execute (AppLocker / WDAC / EDR rule for the OrcaSheets publisher certificate) and install per-machine (MSI) into Program Files | Per-user installs land in `%LOCALAPPDATA%`, which AppLocker default rules block, so the app never opens |
| 4 | Let the browser open `orcasheets://` links and allow mail from `subscriber@orcasheets.com` | Google sign-in returns to the app via a custom protocol; e-mail sign-in delivers the activation key by mail |

Everything else in this document is detail: the full allow-list, a per-scenario matrix, what the app sends, and a troubleshooting checklist.

## 2. Network: domain allow-list

All traffic is client-initiated, outbound, HTTPS/443 unless noted. No inbound ports are required. The app does not use WebSockets or UDP.

### 2.1 Required: sign-in and core operation

| Domain | Purpose | When it is contacted |
|---|---|---|
| `api.orcasheets.ai` | OrcaSheets API gateway: licence token issue/renewal (`/v1/get_secure_token`, `/v2/get_secure_token`), e-mail activation (`/v1/get_secure_token_from_email`), guest check, terms, AI SQL generation, chat | Every sign-in; whenever an AI feature is used |
| `orcasheets.io` | Sign-in landing page opened in the system browser (`https://orcasheets.io/auth?token=…`), product website links | "Continue with Google" |
| `auth.orcasheets.ai` | Hosted authentication / subscription / org-admin pages | Google sign-in flow, Settings → Subscription, Org admin |
| `orcasheets.ai` | Docs, blog (Help menu links) | Help menu only |
| `accounts.google.com`, `*.googleusercontent.com`, `oauth2.googleapis.com`, `*.gstatic.com` | Google sign-in inside the browser (only if the user chooses "Continue with Google") | Google sign-in |

Allow the whole `*.orcasheets.io` and `*.orcasheets.ai` zones if your proxy supports wildcards.

### 2.2 Only if the customer uses the corresponding Connector

| Connector | Destinations |
|---|---|
| Google Sheets | `sheets.googleapis.com`, `www.googleapis.com`, `oauth2.googleapis.com`, `accounts.google.com`; plus a loopback listener on `127.0.0.1:<ephemeral port>` for the OAuth redirect (local firewall may prompt once) |
| Stripe / Shopify presets | `api.stripe.com`, `<store>.myshopify.com` |
| Amazon S3 / Cloudflare R2 | Customer's bucket endpoint (`*.s3.<region>.amazonaws.com`, `<account>.r2.cloudflarestorage.com`) |
| PostgreSQL / Redshift / MySQL / MariaDB / SQL Server / ClickHouse / Snowflake | Customer's own database hosts and ports (5432, 5439, 3306, 1433, 8443, 443 for `*.snowflakecomputing.com`) |
| Custom API / preset API | Whatever endpoint the customer configures |

### 2.3 Windows platform dependencies (installer time)

| Domain | Purpose |
|---|---|
| `go.microsoft.com`, `msedge.sf.dl.delivery.mp.microsoft.com`, `*.dl.delivery.mp.microsoft.com` | **Microsoft Edge WebView2 Runtime** bootstrapper. OrcaSheets renders its UI in WebView2. The default installer downloads the runtime from Microsoft if it is missing. Windows 11 and up-to-date Windows 10 already have it. If downloads are blocked, pre-deploy the WebView2 Evergreen Standalone Installer via your software distribution, or ask OrcaSheets support for the installer variant that bundles the WebView2 runtime. |
| `ocsp.sectigo.com`, `crl.sectigo.com`, `crt.sectigo.com` | Authenticode revocation checks for the OrcaSheets code-signing certificate (Sectigo). Usually already permitted for Windows itself. |

### 2.4 E-mail

The "Sign in with e-mail" option sends an **activation key** to the user's mailbox.

| Item | Value |
|---|---|
| Sender | `subscriber@orcasheets.com` |
| Sender domain to allow-list (anti-spam / quarantine policy) | `orcasheets.com` |
| Content | A one-time activation key (JWT text) the user pastes into the app, plus links to `orcasheets.io` |
| Notes | Link-rewriting ("Safe Links") does not break the flow because the key is pasted as text, but the mail must not be quarantined. The key is bound to the requesting device and expires. |

### 2.5 Proxy and TLS inspection

- The app honours the **Windows system proxy** (Internet Settings → static `ProxyServer`) and the `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` environment variables.
- It does **not** evaluate PAC scripts / WPAD and does **not** support proxies that require NTLM/Kerberos/Basic authentication. In those environments add the §2.1 domains to the **proxy bypass / direct-access list**, or configure a static unauthenticated proxy for the OrcaSheets process.
- TLS for OrcaSheets API calls uses the **Windows certificate store (SChannel)**, so a corporate TLS-inspection root CA deployed to the machine store is trusted. Connector traffic to customer databases uses its own TLS stacks; if the security gateway intercepts database ports, database connections may need to be excluded from inspection.
- No certificate pinning is used.

## 3. Endpoint (laptop) permissions: Windows

### 3.1 Process execution: PowerShell (critical for sign-in)

OrcaSheets licences are bound to the device. To compute the device fingerprint, the app runs **read-only CIM/WMI queries via PowerShell**.

What that means in practice:

- Nothing is written to disk.
- No scripts are downloaded.
- No execution-policy change is made (commands are passed inline, so the script Execution Policy does not apply).

#### Commands spawned by `OrcaSheets.exe`

Each command runs with `-NoProfile -NonInteractive -Command` in a hidden window:

```powershell
powershell -NoProfile -NonInteractive -Command "(Get-CimInstance -ClassName Win32_ComputerSystemProduct).UUID"
powershell -NoProfile -NonInteractive -Command "(Get-CimInstance -ClassName Win32_Processor).Name"
powershell -NoProfile -NonInteractive -Command "(Get-CimInstance -ClassName Win32_ComputerSystem).TotalPhysicalMemory"
powershell -NoProfile -NonInteractive -Command "[System.Environment]::OSVersion.Version.ToString()"
```

#### Fallback when PowerShell fails

Older Windows only. `wmic` no longer exists on Windows 11 24H2+:

```text
wmic csproduct get UUID
wmic cpu get name
```

#### What IT needs to allow

| Control | Setting |
|---|---|
| AppLocker / WDAC | `powershell.exe` may be launched **by `OrcaSheets.exe`** (a parent-process or publisher-scoped exception is sufficient; PowerShell does not need to be globally enabled for users) |
| EDR / behavioural AV ("Office/app spawning PowerShell" rules, e.g. Defender ASR "Block process creations originating from PSExec/WMI", CrowdStrike/SentinelOne script-control) | Exclude `OrcaSheets.exe` as parent, or allow the four commands above |
| PowerShell Constrained Language Mode | Compatible: only cmdlets and the `System.Environment` type are used |
| WMI service (`Winmgmt`) | Must be running (default). Standard users can read these classes. |
| "Prevent access to the command prompt" GPO | Not relevant: `cmd.exe` is not used |

**Effect when blocked:** the device identity cannot be established, so neither "Continue with Google" nor "Sign in with e-mail" can complete, and an already-activated licence cannot be verified. The app stays on the sign-in screen. From the next release the sign-in screen names the blocked prerequisite so it can be forwarded to IT directly.

### 3.2 Installer, install location and application control

| Item | Detail |
|---|---|
| Installers produced | `OrcaSheets_<ver>_x64-setup.exe` (NSIS, **per-user**, installs to `%LOCALAPPDATA%\OrcaSheets\`) and `OrcaSheets_<ver>_x64_en-US.msi` (WiX, **per-machine**, installs to `C:\Program Files\OrcaSheets\`) |
| Recommendation for managed devices | **Deploy the MSI per-machine.** AppLocker/WDAC default rules allow `Program Files` and block `%LOCALAPPDATA%`, so a per-user NSIS install silently fails to launch. |
| Code signing | All executables are Authenticode-signed (Sectigo, SHA-256). Create publisher rules on this certificate rather than path/hash rules so updates keep working. |
| Executables that must be allowed to run | `OrcaSheets.exe` (main), `background_sql.exe` (sidecar: runs heavy SQL out of process), `brs_cli.exe` (sidecar: used only by specific analysis Recipes), `WebView2Loader.dll` |
| Elevation | Not required at run time. MSI needs admin for installation only. |
| Auto-update | Checks `raw.githubusercontent.com` at start; downloads from GitHub Releases; verifies a minisign signature before installing (Windows "passive" install mode). Disable outbound access to those hosts and deploy via your own tooling. |
| WebView2 | Required. Pre-deploy the Evergreen runtime if the bootstrapper download (§2.3) is blocked. |
| SmartScreen | Signed binary; first launch may show a reputation prompt on brand-new releases. Publisher-based allow rules avoid this. |

### 3.3 File system

| Path (Windows) | Contents | Access |
|---|---|---|
| `%APPDATA%\OrcaSheets\` (Roaming) | Application databases (project metadata is encrypted at rest), `orca_ocean\` (imported data in columnar format: **can be large, GBs**), licence token, `orca_logs\app.log` | Read/write required. The app cannot start without this folder. |
| `%LOCALAPPDATA%\OrcaSheets\Logs\`, `%TEMP%\orcasheets_logs\` | Fallback log locations | Write |
| `%LOCALAPPDATA%\ai.orcasheets.OrcaSheets\EBWebView\` | WebView2 profile/cache | Read/write (created by WebView2) |
| User-chosen project folders and the files the user opens (CSV/TSV/Parquet/XLSX) | Data | Read; write for exports |

Recommendations: exclude `%APPDATA%\OrcaSheets\orca_ocean\` and the two `.db` files from roaming-profile sync / backup and from real-time AV scanning (large columnar files, heavy random I/O). Folder Redirection of `AppData\Roaming` to a network share is supported but slow for large datasets.

### 3.4 Registry

| Key | Purpose | Written by |
|---|---|---|
| `HKCU\Software\Classes\orcasheets` (URL protocol `orcasheets://`) | Deep-link return from the browser after Google sign-in, and licence activation links | App at every start (failure is non-fatal but breaks Google sign-in) |
| `HKCU\Software\Classes\.csv/.tsv/.parquet/.xlsx…` associations | "Open with OrcaSheets" | Installer |
| Uninstall / product keys | Standard installer entries | Installer |

No HKLM writes at run time. Reads: `HKCU\…\Internet Settings` (proxy).

### 3.5 Browser and protocol handler

Google sign-in works like this: the app opens `https://orcasheets.io/auth?token=<device token>` in the default browser (via `ShellExecute`); the user signs in with Google on `auth.orcasheets.ai`; the page redirects to `orcasheets://auth?token=<licence>` which Windows routes back to the running OrcaSheets instance.

| Control | Setting |
|---|---|
| Default browser | A browser must be available to the user (not kiosk-blocked) |
| Edge / Chrome policy `URLAllowlist` / `URLBlocklist` | Allow `orcasheets.io`, `auth.orcasheets.ai`, `accounts.google.com`, and the scheme `orcasheets://` |
| Edge / Chrome policy `AutoLaunchProtocolsFromOrigins` | Recommended: `{"protocol":"orcasheets","allowed_origins":["https://auth.orcasheets.ai","https://orcasheets.io"]}` so the user is not prompted every time |
| Custom-protocol launch (`orcasheets://`) | Must not be blocked by the browser policy or by an "unknown protocol" EDR rule |

If the browser flow cannot be allowed, users can still sign in with e-mail (§2.4): no browser or protocol handler is involved, only HTTPS to `api.orcasheets.ai` and an inbound e-mail.

### 3.6 macOS equivalents (for completeness)

- Fingerprint via `ioreg` and `sysctl` (no PowerShell). Allow `OrcaSheets.app` to spawn `/bin/sh`, `/usr/sbin/ioreg`, `/usr/sbin/sysctl`, `/usr/bin/sw_vers`.
- App is notarised and signed with a Developer ID; Gatekeeper/MDM allow rule on Team ID.
- Data in `~/Library/Application Support/OrcaSheets/`; logs in `~/Library/Logs/OrcaSheets/`.
- Protocol handler registered from the app bundle (`Info.plist`), no registry equivalent.

## 4. Scenario matrix

| Scenario | Network needed | Local permissions needed | Symptom when blocked |
|---|---|---|---|
| App launch | none | Executables allowed (§3.2); WebView2 present; `%APPDATA%\OrcaSheets` writable; PowerShell spawn allowed (health check only: non-fatal) | Nothing appears, or a brief window that closes. Check §6 log locations. |
| Continue with Google | `orcasheets.io`, `auth.orcasheets.ai`, Google (browser); `api.orcasheets.ai` (app) | PowerShell spawn (§3.1); default browser; `orcasheets://` handler (§3.5) | If PowerShell is blocked: sign-in cannot start and the app reports the blocked prerequisite. If browser/protocol is blocked: the browser page opens but the app never activates. |
| Sign in with email | `api.orcasheets.ai`; mail delivery from `subscriber@orcasheets.com` | PowerShell spawn (§3.1) | If PowerShell is blocked: error message, sign-in cannot complete. If HTTPS is blocked: error message after the request times out (the activation e-mail is never sent). |
| Continue as guest | `api.orcasheets.ai` | PowerShell spawn | Error as above |
| Paste activation key | none | PowerShell spawn (the key is checked against the device fingerprint) | "Invalid Activation Key" even for a valid key |
| Licence renewal on start (already activated) | `api.orcasheets.ai` | PowerShell spawn | Falls back to the sign-in screen |
| Open CSV / Excel / Parquet, filters, pivots, joins, charts, Recipes | none | Read access to the files; `background_sql.exe` allowed to run | Fully offline; heavy queries fail if the sidecar is blocked |
| AI chat / SQL generation / Recipe generation | `api.orcasheets.ai`, `gateway.ai.cloudflare.com` | - | Error message in chat |
| Chat mode | `chat-mode.orcasheets.ai` | - | Blank view |
| Publish / share Dashboard | S3 `ap-south-1`, `dashboards.orcasheets.io` | - | Publish fails |
| Connectors | Per §2.2 | Loopback listener for Google OAuth | Connector-specific error |
| Auto-update | GitHub Releases / update manifest hosts | Write to install dir (per-user) or elevation prompt (per-machine) | Silent: app keeps running the installed version |
| Telemetry | `logs.ap-south-1.amazonaws.com` | - | Silent fallback to `orca_logs\app.log` |

## 5. What the app sends: for privacy review

Device fingerprint sent with every sign-in / licence call (as a short-lived signed token):

| Field | Value | Purpose |
|---|---|---|
| `sub` | SHA-256 hash of (BIOS/board UUID + CPU model string). The raw UUID never leaves the device. | Bind licence to device |
| `os_type`, `os_version` | e.g. `windows`, `10.0.22631` | Support/compatibility |
| `cpu_count`, `memory_bytes` | Logical CPUs, RAM in bytes | Sizing/support |
| `app_version` | e.g. `26.9.2` | Support |
| e-mail | The address the user types (e-mail flow) or their Google account e-mail (Google flow) | Account identity |

**Not collected:** hostname, Windows user name, MAC address, serial number, file contents, file names, query results. Customer data never leaves the laptop unless the user explicitly publishes a Dashboard or uses an AI feature (AI features send the schema and the user's question, not the rows, unless the user asks the AI about specific values in chat).

**Telemetry** (only when the licence has cloud logging on, default on): error messages and UI event names with app/OS version and the hashed device id. It can be disabled per organisation on request.

## 6. Troubleshooting checklist for IT

**Start here:** from the next OrcaSheets release the app checks its own prerequisites at launch. If anything is blocked, the sign-in screen shows a dialog **"OrcaSheets needs a few things enabled on this computer"** listing each blocked item with the exact change required. **Copy details for IT** puts the full report (blocked items, technical detail, required domains) on the clipboard: ask the user to paste it into the ticket. **Check again** re-runs the probes after a policy change without restarting.

Run the following as the affected user on the affected laptop if the dialog does not appear or you need to verify independently.

1. **Is the executable allowed to run?**

   ```powershell
   Get-AppLockerPolicy -Effective | Test-AppLockerPolicy -Path "C:\Program Files\OrcaSheets\OrcaSheets.exe","C:\Program Files\OrcaSheets\background_sql.exe"
   ```

   (adjust path for a per-user install). Check Event Viewer → Applications and Services Logs → Microsoft → Windows → AppLocker and → CodeIntegrity for blocks.

2. **Is WebView2 installed?**

   ```powershell
   Get-ItemProperty "HKLM:\SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}"
   ```

   should return a `pv` version.

3. **Can the app's PowerShell probes run?** From a normal (non-elevated) PowerShell:

   ```powershell
   (Get-CimInstance -ClassName Win32_ComputerSystemProduct).UUID
   (Get-CimInstance -ClassName Win32_Processor).Name
   ```

   must print values. Then check that the EDR does not block `OrcaSheets.exe` → `powershell.exe` (look for the block event in the EDR console).

4. **Can the app reach the API?**

   ```
   curl.exe -sS -o NUL -w "%{http_code}\n" https://api.orcasheets.ai/v1/terms_and_conditions
   ```

   → expect `200`. Any TLS error means the inspection CA is not trusted; a hang means the proxy requires authentication or the domain is not bypassed.

5. **Is the `orcasheets://` handler registered?**

   ```powershell
   Get-Item "HKCU:\Software\Classes\orcasheets\shell\open\command"
   ```

   should point at `OrcaSheets.exe "%1"`. Test:

   ```powershell
   Start-Process "orcasheets://auth?token=test"
   ```

   should bring OrcaSheets to the front.

6. **Collect logs:** `%APPDATA%\OrcaSheets\orca_logs\app.log`, `%LOCALAPPDATA%\OrcaSheets\Logs\app.log`, `%TEMP%\orcasheets_logs\app.log`. At start the app writes a `Device ID health check` line: `PASSED` or a per-command diagnosis naming the blocked probe.

7. **App closes without a log line:** look in Event Viewer → Windows Logs → Application for `Application Error` entries naming `OrcaSheets.exe` and share them with OrcaSheets support together with the files from step 6.

## Related pages

- [Troubleshooting](/docs/troubleshooting)
- [Local-first Security](/docs/local-first-security)
- [Access Control & SSO](/docs/access-control-sso)
- [Connection Problems](/docs/connection-problems)
- [Onboarding Guide](/docs/onboarding-guide)