> ## Documentation Index > Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt > Use this file to discover all available pages before exploring further. # Installation & Configuration > Step-by-step Snowflake Native App Installation & Configuration guide. *** ## **Installation** **Steps** **Snowflake Marketplace:** In the Snowflake Marketplace, browse to the Genesis Data Agents App. Click the ***“Try Now”*** button to begin the installation of the Genesis Data Agents App in your Snowflake account. > [!WARNING] > > Make sure that you have **ACCOUNTADMIN** as the role in your Snowflake Account. ![Snowflake Marketplace Native App Installation](https://mintcdn.com/genesiscomputing/7K5EJ-MQEqGiTdfs/1.png?fit=max\&auto=format\&n=7K5EJ-MQEqGiTdfs\&q=85\&s=a030543ababfbadab4d924676673402d) Click the ***"Start Trial"*** button to experience Genesis Data Agents **free for 30 days!** ![Genesis Data Agents Free For 30 Days](https://mintcdn.com/genesiscomputing/7K5EJ-MQEqGiTdfs/images/2.png?fit=max\&auto=format\&n=7K5EJ-MQEqGiTdfs\&q=85\&s=9a0077099256d48b2d58986bf7042846) **Installing the App:** The Genesis Data Agents app will now be installed in your Snowflake account. An email will be sent to the email address listed in the user profile of the Snowflake User installing the application. ![3 Pn](https://mintcdn.com/genesiscomputing/7K5EJ-MQEqGiTdfs/images/3.png?fit=max\&auto=format\&n=7K5EJ-MQEqGiTdfs\&q=85\&s=985b23314136ec92c46629d22523326b) **Installation Complete:** Once the installation has been completed successfully, Click the ***“Configure”*** button to open the app, which will launch in a new window. ![4 Pn](https://mintcdn.com/genesiscomputing/7K5EJ-MQEqGiTdfs/images/4.png?fit=max\&auto=format\&n=7K5EJ-MQEqGiTdfs\&q=85\&s=5ec5459f5fade8bb39582cffe4ff9d8e) ## **Configuration** Now that you have completed the installation, the next part is the service configuration. ![4 5 Pn](https://mintcdn.com/genesiscomputing/7K5EJ-MQEqGiTdfs/images/4.5.png?fit=max\&auto=format\&n=7K5EJ-MQEqGiTdfs\&q=85\&s=15e2e7f9c30692171186a86a7ae160c0) The first step is granting account privileges – click ***“Grant”*** and you should now see that all required privileges have been granted. ![Activating Genesis Data Agents](https://mintcdn.com/genesiscomputing/7K5EJ-MQEqGiTdfs/5.png?fit=max\&auto=format\&n=7K5EJ-MQEqGiTdfs\&q=85\&s=8ab87d624fb82bf7ff5621a84ac74dfb) Once you see ***“Granted” (highlighted in green)*** Click The ***“Activate”*** button that will appear on the left side. On a new installation, the activation process will create an X-Small virtual warehouse and a small Snowflake compute pool with `AUTO_RESUME=TRUE`, and the Genesis services will be started. To select a different service warehouse, follow [Custom warehouse setup](https://docs.genesiscomputing.com/docs/Setup/Setup-Custom-Warehouse.md). > [!NOTE] > > Activation starts the Genesis services but does not wait for them to report > ready. On a cold install, Snowflake must provision the pool node, pull the > image, and start the app; this can take about 15 minutes, so activation may > return while the service is still starting. Genesis reports a startup failure > if a service container already reports `FAILED`. During later service start > and restart operations, Genesis waits up to 15 minutes for service containers > to report ready. From release 1.19.97 the Native App also provisions a public `outposttunnel` endpoint on port `28088` for customer-run [Outposts](https://docs.genesiscomputing.com/docs/Setup/Outposts-Overview.md) to dial out to Genesis. Genesis serves it itself, with its own Outpost tunnel worker inside the Genesis container; the app ships no other image. Only the `APP_OUTPOST_TUNNEL` application role reaches the endpoint, and an Outpost's Snowflake service user holds nothing else. When `outpost.tunnel_endpoint_url` is unset, the generated Outpost install instructions look up this endpoint in Snowflake. If the lookup cannot see it or the Outpost must use another address, set `outpost.tunnel_endpoint_url` as described in [Outpost routing settings](https://docs.genesiscomputing.com/docs/Setup/Advanced-Settings.md#outpost-routing). An app older than 1.19.97 has no such endpoint, and its Outposts page shows them as unavailable. In SPCS, the worker listens on `127.0.0.1` and the pod's own addresses rather than every address, leaving Outpost-assigned `127.77.x.y` route addresses available on port `28088`. The app also provisions a `debuggenesis` endpoint: a support shell (Shell in a Box) that Genesis support can use, with your approval, to diagnose a problem inside the Genesis container. It is locked by default and stays locked until one of your Genesis admins unlocks it, as described in [Support shell access](#support-shell-access). Only the `APP_ADMIN` application role reaches the endpoint; `APP_PUBLIC` does not. Earlier versions granted the endpoint to every Genesis user and kept the shell's password in the app's `BOT_STORAGE` stage; after upgrading, the app deletes that password file every time it starts. To check progress while activation is still starting the service, run this in a Snowflake worksheet (replace the placeholder with the application database name): ```sql theme={null} CALL .CORE.GET_INSTALL_STATUS(); ``` The procedure returns the current install stage, progress estimate, ETA, available service details, and suggested SQL for stages that need consumer action, without waiting for Genesis to become ready. Unbound references are reported as optional and do not block activation or `READY`. Genesis refreshes its startup details every 15 seconds once its metadata connection is available. See the [install status procedure reference](https://docs.genesiscomputing.com/docs/Genesis-API/API-Reference.md#snowflake-native-app-install-status-procedure) for the result fields and stage behavior. To keep a Native App instance stopped until you explicitly start it, run `CORE.HIBERNATE_INSTANCE` in a Snowflake worksheet: ```sql theme={null} CALL .CORE.HIBERNATE_INSTANCE(''); ``` Replace `` with the installed app's database and `` with the schema containing its services (commonly `APP1`). The procedure disables auto-resume and suspends the services, then disables auto-resume and suspends their compute pool. Its result includes service and container details plus each service's compute pool, pool state, and `POOL_AUTO_RESUME` value. Unlike `CORE.STOP_APP_INSTANCE`, which only suspends the services and can be undone by a request, hibernation keeps the instance stopped until `CORE.START_APP_INSTANCE` is called. To start it again, use the instance schema, pool name, and warehouse configured for this deployment: ```sql theme={null} CALL .CORE.START_APP_INSTANCE('', '', ''); ``` When the Snowflake account and region support custom MCP servers, activation registers the Genesis service as `.APP1.GENESIS_MCP` and grants the application's `APP_PUBLIC` role usage on it. A Cortex Agent in the consumer account can reference this name under `mcp_servers` to use Genesis. The server is retained across re-activation, restarts, and app upgrades. If custom MCP servers are unsupported, activation and upgrades still complete without registering the endpoint. > [!NOTE] > > In Snowflake Native App / SPCS mode, Genesis sets `SF_SPCS_TOKEN_PATH` to `/dev/null/no_spcs_token` during startup. This disables the Snowflake Python connector's automatic reads from `/snowflake/session/spcs_token` for general outbound login requests, while the built-in system `Snowflake` connection still passes the SPCS token explicitly when Genesis needs it. User-created outbound Snowflake connections can therefore use their own saved credentials, including **Programmatic Access Token** and username/password modes, without inheriting the app's internal SPCS token. ## **Genesis Data Agents Application Set-Up** After the Genesis service has finished starting, click ***“Launch app”*** to configure your Genesis Data Agents application. ![Genesis App Launch](https://mintcdn.com/genesiscomputing/7K5EJ-MQEqGiTdfs/6.png?fit=max\&auto=format\&n=7K5EJ-MQEqGiTdfs\&q=85\&s=d1ab9bc8fa51c5e56c409b98ff55c989) Now you can launch the Genesis application. ![7 Pn](https://mintcdn.com/genesiscomputing/7K5EJ-MQEqGiTdfs/images/7.png?fit=max\&auto=format\&n=7K5EJ-MQEqGiTdfs\&q=85\&s=7c2e28753f6708d7b75483b3c8d4224c) ![](https://i0.wp.com/genesiscomputing.ai/wp-content/uploads/2024/05/Screenshot-2024-09-23-144827.png?resize=1024%2C535\&ssl=1) To grant custom Role access to use the Genesis application, run the following: Please copy and run this in your Snowflake worksheet. ``` GRANT APPLICATION ROLE GENESIS_DATA_AGENTS.APP_PUBLIC TO ROLE sysadmin; ``` ### Support shell access The support shell is for Genesis support, and only with your approval. Its login is locked at every start, and nobody can use it until one of your admins unlocks it: 1. Grant the `APP_ADMIN` application role to the Snowflake role your Genesis admins use (never to everyone), so they can reach the `debuggenesis` endpoint: ``` GRANT APPLICATION ROLE GENESIS_DATA_AGENTS.APP_ADMIN TO ROLE ; ``` 2. When Genesis support asks for access, a Genesis admin, signed in to Genesis, requests a challenge with `POST /api/admin/support-shell/challenge` and sends the returned `challenge` text to Genesis support. It is valid for 15 minutes and can be used once. 3. Genesis support signs the challenge and returns a short JSON body. 4. The admin sends that body to `POST /api/admin/support-shell/unlock`. The response contains the shell's user name and a one-time password, shown once and stored nowhere. The admin gives it to Genesis support over a private channel. 5. The shell locks itself again after 24 hours (set `unlock_hours`, 1 to 168, in the unlock body to change this), whenever the Genesis server restarts, or when the admin calls `POST /api/admin/support-shell/lock`. `GET /api/admin/support-shell` shows whether it is unlocked and until when. Only a person signed in with the Genesis admin role can request a challenge, unlock or lock the shell; Genesis agents, API tokens and app tokens are refused. Every request, unlock, refusal, lock and expiry is recorded in the admin audit log, without the password. ### Customer credentials for same-account connections For Snowflake PAT and Key Pair connections that log in inside the installed account, an administrator must opt the Native App install in to custom credentials once: ```sql theme={null} CALL GENESIS_DATA_AGENTS.CORE.ENABLE_CUSTOM_CREDENTIALS(); ``` This updates the Genesis service specification to allow customer-provided credentials and restarts the service (typically about 3–4 minutes). The opt-in persists across app upgrades. The procedure is granted to the app's `APP_PUBLIC` application role. To remove the opt-in and restart without custom credentials, run: ```sql theme={null} CALL GENESIS_DATA_AGENTS.CORE.DISABLE_CUSTOM_CREDENTIALS(); ``` Continue with the [connection setup guide](https://docs.genesiscomputing.com/docs/Setup/Connections.md#connect-inside-snowflake-spcs-same-account). ### (Optional) Additional Privileges, PrivateLink, and Cortex Cross-Region Inference **1. Granting the Genesis Data Agents app access to Snowflake objects.** You grant Genesis Data Agents access to Snowflake objects when Genesis needs to READ or WORK WITH data that exists outside its own application database. Grant the privilege on the object to the application. E.g. `GRANT USAGE ON DATABASE MYDB TO APPLICATION GENESIS_DATA_AGENTS;` `GRANT USAGE ON SCHEMA MYDB.SOURCE TO APPLICATION GENESIS_DATA_AGENTS;` `GRANT SELECT ON ALL TABLES IN SCHEMA MYDB.SOURCE TO APPLICATION GENESIS_DATA_AGENTS;` **2. PrivateLink** In the case that you are using Snowflake and PrivateLink, and have not yet set up PrivateLink to work with Snowpark Container Services, please refer to and follow the steps in this document [here](https://docs.snowflake.com/en/developer-guide/snowpark-container-services/private-connectivity#configure-public-endpoints-access). After configuring that private connectivity, see [Connections — PrivateLink](https://docs.genesiscomputing.com/docs/Setup/Connections.md#guided-post-save-setup) for how to select it on outbound connections. **3. Cortex Cross-Region Inference** Enable Cortex Cross-Region Inference (Recommended) **Required for:** Access to the latest models via Snowflake Cortex **Why:** The newest, most capable models may not be available in your Snowflake region yet **How:** In order to use the best models via Cortex (as recommended by Genesis), Snowflake users must enable Cortex Cross-Region Inference [here](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cross-region-inference). **Impact:** Allows Genesis to use the best available models regardless of your region **4. Embedded Tailscale (Private LLM Gateways)** Optional embedded Tailscale userspace networking lets SPCS instances join your tailnet and reach private LLM gateways (for example Tailscale Aperture) over WireGuard without kernel privileges. Existing deployments are unchanged until you enable tsnet access. In Genesis, open **Config → Secrets → Tailscale**, use the **Embedded Tailscale** card (click **Set up embedded Tailscale**), then follow the in-product steps: run the generated `CREATE SECRET` SQL with your own `tskey-auth-...` key as `ACCOUNTADMIN`, bind **Tailscale Auth Key Secret** and **Tailscale Control Plane External Access** in the Snowflake Configurations tab, click **Enable Tailscale**, then suspend/resume the service so the container reads the key at boot. At startup, the boot-config read uses the service's active warehouse, including its configured `QUERY_WAREHOUSE`. If `SNOWFLAKE_WAREHOUSE` is set, Genesis activates that warehouse instead; `GENESIS_XSMALL` is used only when no warehouse is active. This allows the Tailscale configuration to be read on the warehouse selected for the service without requiring `GENESIS_XSMALL` to be available. When your Tailscale auth material is an **OAuth-client auth key** or **OAuth client secret** used directly as `--auth-key` (instead of a standard pre-tagged reusable key), Tailscale requires `--advertise-tags` at connect time. On Native App (SPCS), set the tag in Genesis under **Config → Secrets → Tailscale** → expand **Tailscale ACL tags** (stored in `APP1.TSNET_ADVERTISE_TAGS` and read at container boot together with the auth key via `CORE.GET_TSNET_BOOT_CONFIG()` in one Snowflake round-trip). **Suspend/resume** the service after saving so `launch.sh` re-runs. For Helm, EKS, or other non-SPCS container deployments, you can set the tag with an environment variable instead. When both are present, the env var wins. | Variable | Required | Description | | - | - | - | | `GENESIS_TSNET_ADVERTISE_TAGS` | No | When set on the container, `container/launch.sh` passes `--advertise-tags="${GENESIS_TSNET_ADVERTISE_TAGS}"` to `tailscale up` (overrides the value from the SPCS boot-config read). When unset or empty everywhere, Genesis omits `--advertise-tags` so pre-tagged auth keys keep working unchanged. Example value: `tag:genesis-spcs`. | After enabling tsnet, suspend and resume the Genesis service so `launch.sh` re-runs, then confirm `/api/health` reports `"status": "healthy"` with a `tsnet` object where `"online": true`. If embedded Tailscale was previously configured but cannot connect at boot (missing auth key, unassociated references, or an expired key), Genesis still returns HTTP `200` with `"status": "degraded"` and a `degraded_reason` so the UI stays reachable while you recover — see [Embedded Tailscale troubleshooting](https://docs.genesiscomputing.com/docs/Setup/Secrets.md#troubleshooting-degraded-embedded-tailscale). ### Log sharing with Genesis > [!WARNING] > > Genesis Data Agents requires sharing the app's logs with Genesis. Sharing is > turned on when you install the app, and it cannot be turned off afterwards. Genesis uses the shared logs to support your install: to see why a service did not start, to find errors, and to fix problems without asking you to export logs. Snowflake calls this *event sharing*, and the app declares it as a required event definition. Snowsight shows it in the **Events and logs** section of the listing before you select **Get**. A SQL install must accept it with `AUTHORIZE_TELEMETRY_EVENT_SHARING = TRUE`: ```sql theme={null} CREATE APPLICATION GENESIS_DATA_AGENTS FROM LISTING '' AUTHORIZE_TELEMETRY_EVENT_SHARING = TRUE; ``` **What is shared.** Everything the app writes to your event table: the log lines the Genesis containers write at INFO level and above (startup and health messages, warnings, errors, and diagnostics such as the [wedge sentinel](#wedge-diagnostics-in-exported-logs)), and the Snowflake platform events and metrics recorded for the app's services. Application log lines can quote text the service was working on, such as part of a prompt, a SQL statement, or a tool result. **What Snowflake removes first.** Before anything leaves your account, Snowflake replaces your database and application names with hashes, and drops user names, role names, warehouse names, query IDs and session IDs. See Snowflake's [field categorization](https://docs.snowflake.com/en/developer-guide/native-apps/event-manage-provider) for the full list. **Where it goes.** Snowflake copies the shared events into a Genesis-owned Snowflake account in your own region; it does not move them across regions. Genesis gathers them in its Snowflake event account for support and operations. Events already shared cannot be recalled. For questions about retention, or to ask Genesis to delete shared logs, contact [support@genesiscomputing.ai](mailto:support@genesiscomputing.ai). **Your event table.** The same events are written to your account's active event table, and you pay for storing them there; Snowflake does not charge for the sharing itself. New Snowflake accounts use `SNOWFLAKE.TELEMETRY.EVENTS` by default. Check with `SHOW PARAMETERS LIKE 'EVENT_TABLE' IN ACCOUNT;`. **Installs from before this requirement.** Upgrading does not turn sharing on: Snowflake never enables a newly required definition during an upgrade. If you shared logs before, you still do. To check, run: ```sql theme={null} CALL GENESIS_DATA_AGENTS.CORE.GET_INSTALL_STATUS(); ``` `EVENT_SHARING_ENABLED` is `TRUE` when logs are shared. When it is `FALSE`, `EVENT_SHARING_SQL` gives the statement that turns sharing on, which a role with the `MANAGE EVENT SHARING` privilege (`ACCOUNTADMIN` has it) runs: ```sql theme={null} ALTER APPLICATION GENESIS_DATA_AGENTS SET AUTHORIZE_TELEMETRY_EVENT_SHARING = TRUE; ``` You can also turn it on in Snowsight (**Catalog » Apps**, select Genesis Data Agents, **Settings**, **Events and logs**), or from Genesis itself: on the **Logs** page, open the actions menu and select **Share Event Logs**. Once on, it cannot be turned off. Genesis also writes a warning to its own log at startup while logs are not shared. ### SPCS platform metrics The Genesis service enables Snowflake platform monitoring by default in Native App / SPCS deployments. The service spec collects the `system`, `system_limits`, `status`, `network`, and `storage` metric groups, providing platform-level service signals independently of application log output. No additional Genesis configuration is required. ### Wedge diagnostics in exported logs When the Genesis Python process hangs ("wedges"), in-process diagnostics such as `SYS_PRESSURE` and `LOOP_IDENTITY` stop at the same instant because they are emitted from inside that process. Starting with images that include GEN-2402, every SPCS container also runs an out-of-process **wedge sentinel** (`container/wedge_sentinel.py`, started from `container/launch.sh`) that keeps writing `WEDGE_SENTINEL` lines to container stdout on a fixed interval (default 60 s). Snowflake exports stdout and stderr to your account's event table via the service spec's `logExporters` configuration, so these lines are available to account administrators without interactive access to the container. Filter for lines containing `WEDGE_SENTINEL` in the event table or via `SYSTEM$GET_SERVICE_LOGS` for the Genesis service. Each line is a compact `key=value` snapshot of Genesis process state, optional embedded Tailscale activity, block-volume probe results, cgroup throttling counters, and node-level pressure — while the sentinel's own `seq` field should keep advancing even when Genesis is wedged. For the full field reference, environment variables (`GENESIS_WEDGE_SENTINEL_*`), and interpretation guide, see [Out-of-process wedge diagnostics](https://docs.genesiscomputing.com/docs/deployments/Docker/Genesis-Container-Distribution.md#out-of-process-wedge-diagnostics) in the container distribution guide (the sentinel ships in all Genesis container images, not only SPCS). Genesis Data Agents default to Cortex, utilizing only the models capable of agentic workflows, but we are model agnostic, so you can also choose to use other models [here](https://docs.genesiscomputing.com/docs/Setup/Set-Up-AI-Model) Congratulations! We’ve reached the end of Installation & Configuration. Proceed forth to [**Grant Data Access**](https://docs.genesiscomputing.com/docs/deployments/Snowflake-Native-App/Granting-Database-Access.md) to your Genesis Data Agents.