Snowflake Native App Deployment Guide

Install Supaflow from Snowflake Marketplace and connect it to your Supaflow account through Snowsight. Your agent executes pipelines inside your Snowflake account; you configure connections, approve the agent, and monitor jobs in Supaflow.

Which setup flow does this guide cover?

These steps describe the OAuth-based Native App. It uses Snowsight configuration and browser consent; there is no Streamlit application to launch or manual token to copy. If your installation still shows the earlier Streamlit linking flow, contact support@supa-flow.io for upgrade guidance.

Prerequisites

• A Supaflow account. If you are new, create your account and complete account setup before starting browser consent. Use an organization administrator or the owner of your personal account to approve the agent.
• A Snowflake account that supports Snowpark Container Services and external access integrations. Use the paid account where you want the agent to run.
• A Snowflake role authorized to install the app and approve its requested privileges and integrations, such as ACCOUNTADMIN.

You do not need to create a controller datasource, run a separate service-user setup script, or generate an enrollment token before installing the Native App. A controller is optional for automatic resume.

Step 1: Install from Snowflake Marketplace

1. In Snowsight, open Marketplace and search for Supaflow.
2. Open the Supaflow listing and review its pricing and trial terms.
3. Choose Get and follow Snowflake's installation prompts.
4. Note the installed application's name. SQL examples in this guide use SUPAFLOW_NATIVE_APP; replace it with your installation's actual name.

Step 2: Review the Requested Privileges

Review the app's requested account privileges during installation. You can also check their status in the installed app's Permissions tab.

Privilege	Purpose
CREATE SECURITY INTEGRATION	Create the app-owned Supaflow OAuth connection
CREATE COMPUTE POOL	Create compute for the native agent
CREATE WAREHOUSE	Create the agent's query warehouse and support activity signaling
CREATE EXTERNAL ACCESS INTEGRATION	Connect to approved Supaflow, connector, source, and destination endpoints
EXECUTE TASK	Execute Snowflake tasks created by Supaflow
EXECUTE MANAGED TASK	Execute serverless Snowflake tasks
BIND SERVICE ENDPOINT	Expose service endpoints

Step 3: Enable Network Access

In the installed app's Configurations, find Step 1 — Required: Enable network access. During installation, Snowsight may show this under External connections instead.

1. Click Review to inspect the outbound endpoints.
2. Click Connect to approve the external access integration.
3. Wait for the connection to show Connected. This also prepares the app's Supaflow sign-in connection automatically.

The defaults cover Supaflow and common connector services. Add customer-specific hosts after installation using Add Custom Connector Network Access.

Complete both configuration steps

Snowsight may label configuration categories Optional. For Supaflow, both network access and Supaflow sign-in are required before the agent can start.

Step 4: Sign in to Supaflow with OAuth

Review the Sign-in Connection

1. Under External connections, review Security integrations.
2. Find Step 2 — Required: Sign in to Supaflow.
3. Review the production Supaflow authorization and token endpoints and the requested scopes: offline_access, user:org:read, supaflow:read, and supaflow:write.
4. Click Save. If the installation wizard shows Proceed to app, continue to the app and open Configurations.

The app registers its account-specific OAuth client automatically. You do not need to create an OAuth client or enter callback URLs yourself.

Complete Browser Consent

1. Under Authentication, find Step 2 — Required: Sign in to Supaflow.
2. Click Authenticate. Snowsight opens a dialog; click Authenticate there to open the Supaflow sign-in popup.
3. Sign in to the Supaflow account that should own this agent and select the intended organization or personal account. Approve the requested access.
4. Return to Snowsight and wait for the connection to show Configured.

An already configured connection displays Reauthenticate instead of Authenticate. Screenshots show a completed example, so button labels and status badges can differ during your first installation.

Successful authentication starts deployment automatically. Allow time for Snowflake to provision the compute pool and start the container. No manual Deploy Agent action is required.

Step 5: Approve the Agent in Supaflow

1. Open Supaflow Settings → Agents using the same account or organization selected during consent.
2. Find the newly registered native agent. Its identifier starts with supaflow-native-, and its initial status is Registered.
3. Click Approve and complete the confirmation.
4. Wait for Agent approved and connected and a Running status.

Approval grants this agent access to your Supaflow account. Connector synchronization runs separately: an approved, connected agent does not by itself prove that every connector is ready. Check your connection tests and job results before running production workloads.

Step 6: Configure Connections and Run a Pipeline

Create a Native App Destination (Optional)

After approval, Supaflow offers Create Snowflake Destination. This creates a destination for the Native App's database and warehouse using SPCS OAuth.

1. Review the prefilled account, database, schema, warehouse, and authentication type.
2. Click Create Destination, or Skip to configure a different destination.
3. Test the connection and check that schema discovery completes successfully.

SPCS OAuth uses the running native agent's Snowflake session. This destination cannot replace a controller datasource used to resume that agent while it is stopped. See the Snowflake destination guide for other connection and authentication options.

Create a Source Connection

Add the data source you want to pull from:

1. Go to Sources in the sidebar
2. Click Create Source
3. Choose your source connector (e.g., Salesforce, HubSpot, PostgreSQL)
4. Configure the connection and test it

See the Sources documentation for connector-specific setup guides, or watch the video below:

Build Your First Pipeline

Choose your preferred way to configure the pipeline. Both paths use the same connections and execute on your native agent.

Option A: Build with ChatGPT or Claude

You can use Supaflow from ChatGPT or Claude. Before connecting a plugin, an account owner or organization administrator must enable API access and that AI application in Settings → API Keys → Permissions. These settings apply to the AI plugin connection; Native App enrollment does not require enabling API access or creating an API key. Follow the ChatGPT setup guide or Claude setup guide for the permission and connection steps.

After enabling those permissions, install the plugin, connect the same Supaflow account, and select your workspace. Configure credentials securely in Supaflow, not in chat.

Start with a read-only setup check:

Help me get started with Supaflow. Check my workspace and connections, and explain what I need before creating my first pipeline.

Once the connections are ready, ask your AI agent to help configure a pipeline. Review its source, destination, selected objects, and settings before running it.

Option B: Build in the Supaflow UI

Each destination automatically creates a project. With your source and destination ready, create a pipeline in the destination's project:

1. Go to Pipelines in the sidebar
2. Click + Create Pipeline
3. Select the project for your intended destination if prompted.
4. Walk through the 4-step wizard:
   • Choose Source -- Select the source datasource
   • Configure Pipeline -- Review and adjust sync/load/schema settings (project destination is pre-selected)
   • Choose Objects to Sync -- Select tables and fields
   • Review & Save -- Confirm details
5. Click Create Pipeline

See the Ingestion Pipelines documentation for detailed configuration options, or watch the video below:

Run and Verify Your First Sync

1. Open the pipeline and click Sync Now, or use its … → Sync Now menu from the Pipelines list.
2. Follow View activity in the confirmation, or open Activities.
3. Wait for a terminal result. A submitted or queued job is not a completed sync.
4. Open the run details and check the per-object results, row counts, and any warnings or errors. Confirm the expected tables and data in Snowflake.

If the run fails, inspect the affected object's error before retrying. See Troubleshooting for connector readiness and network issues.

Verification Checklist

After completing setup, verify:

• Native App -- Installed in the intended Snowflake account.
• Privileges -- All seven requested account privileges show Granted.
• Network access -- Step 1 — Required: Enable network access is Connected.
• OAuth -- Step 2 — Required: Sign in to Supaflow is Configured for the intended Supaflow account.
• Agent -- Approved and Running in that same Supaflow account or organization.
• Connections -- Source and destination tests and schema discovery succeed.
• Pipeline -- A sync completes successfully; inspect its job and object results.
• Optional controller -- If configured, it uses the correct account role and has the installed app's app_public grant.

---

Manage the Native Agent

Use a Snowsight SQL worksheet with a role that has access to the installed app. Replace SUPAFLOW_NATIVE_APP with your application's name:

Check status — reports whether the service is deployed and its state:

CALL SUPAFLOW_NATIVE_APP.core.get_agent_status();

Stop the agent — suspends the service, compute pool, and service warehouse:

CALL SUPAFLOW_NATIVE_APP.core.stop_agent();

Start the agent — resumes the existing deployment. It does not install a newer image or re-enroll the agent:

CALL SUPAFLOW_NATIVE_APP.core.start_agent();

The app_admin application role includes app_public service-management permissions. An account role granted app_admin does not need an additional app_public grant to manage the service.

Identity, Storage, and Compute Costs

The agent uses a short-lived OTP automatically during enrollment. Its signing identity, keystore, and OpenPGP certificate are saved in app-owned Snowflake secrets. Healthy restarts reload the same identity and keys without another consent or enrollment step.

Each native agent has 64 GiB of encrypted block storage for connector libraries and runtime data. Suspending preserves that storage and the app's secrets. Storage charges continue while compute is suspended.

The service disables idle auto-suspension by default (AUTO_SUSPEND_SECS=0). Stop it explicitly when it is not needed. Snowflake compute and storage charges are separate from Supaflow usage charges; review the listing's pricing before deployment.

Optional: Configure a Controller for Automatic Resume

A controller datasource lets Supaflow resume the suspended native agent for queued work. It is not a prerequisite for OAuth installation or for the running agent to save its keys.

1. Create a separate Snowflake datasource with credentials usable outside the native agent, such as key-pair authentication. Follow the Snowflake destination guide for user, role, and connection setup. Do not use the Native App's SPCS OAuth destination as its controller.

2. Point the controller at the Snowflake account hosting this Native App and select the account role it should use.

3. In Snowsight, open the installed app's Access management and grant that account role the application's app_public role. Equivalent SQL, using your installed app and controller role names:

   GRANT APPLICATION ROLE SUPAFLOW_NATIVE_APP.app_public TO ROLE CONTROLLER_ROLE;

4. In Supaflow Settings → Agents, open the agent's menu, choose Change Controller, select the controller datasource, and click Set Controller.

The controller's Snowflake user must have and use the granted account role. Installing the app under another administrator role does not automatically provide access to the controller. The Agents guide covers controller selection and lifecycle actions.

Advanced: Add Custom Connector Network Access

You can add connector endpoints after installation, without reinstalling the agent or using Streamlit. Run the following steps in a Snowsight SQL worksheet as ACCOUNTADMIN, or an administrator with ownership of the integration and the required privileges to create network rules.

The external access integration is an account-level object. Network rules live in a database/schema in your account. Adding a rule to the agent's integration permits outbound connections for workloads using that integration; it does not change your account's inbound network policy.

1. Find the integration bound to this app. Replace SUPAFLOW_NATIVE_APP with your installed application's name:

   USE ROLE ACCOUNTADMIN;
   SHOW REFERENCES IN APPLICATION SUPAFLOW_NATIVE_APP;

   Find the SUPA_AGENT_EXTERNAL_ACCESS reference and copy its object_name. That is the integration to modify; its generated name may differ between installations. If it is unbound, complete Step 1 — Required: Enable network access in the app's Configurations first. Run DESCRIBE INTEGRATION with the bound integration name and record its entire ALLOWED_NETWORK_RULES list.

2. Create a customer-owned rule. These example object names and endpoints are placeholders; substitute a database/schema you manage and the exact public hostname and port from your connector configuration:

   CREATE DATABASE IF NOT EXISTS CUSTOMER_NETWORK;
   CREATE SCHEMA IF NOT EXISTS CUSTOMER_NETWORK.AGENT_EGRESS;
   CREATE NETWORK RULE CUSTOMER_NETWORK.AGENT_EGRESS.CONNECTOR_ENDPOINTS
     MODE = EGRESS
     TYPE = HOST_PORT
     VALUE_LIST = (
       'examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com:5439',
       'example-bucket.s3.us-east-1.amazonaws.com:443',
       's3.us-east-1.amazonaws.com:443',
       'sts.us-east-1.amazonaws.com:443'
     );

   Include only endpoints you use. Redshift defaults to port 5439; use its actual configured port. S3 examples illustrate bucket, regional API and role-assumption access; they are not required for every connector. Use hostname/port values, without https://, URL paths, credentials or tokens.

3. Attach the rule to the bound integration. Replace both angle-bracket placeholders below before executing. <ALL_CURRENT_RULES> means every existing rule returned by DESCRIBE INTEGRATION, as comma-separated, fully qualified identifiers. Keep those rules and append your new rule:

   ALTER EXTERNAL ACCESS INTEGRATION <BOUND_INTEGRATION_NAME>
     SET ALLOWED_NETWORK_RULES = (
       <ALL_CURRENT_RULES>,
       CUSTOMER_NETWORK.AGENT_EGRESS.CONNECTOR_ENDPOINTS
     );

   SET ALLOWED_NETWORK_RULES replaces the complete list; it does not append. Do not omit existing rules, replace/recreate the integration, change its secret permissions, or unbind the app reference to add an endpoint.

4. Verify and retry. Describe the integration again and confirm that all original rules and the customer rule are present. Retry the connector's connection test or schema refresh, then a pipeline run. Destination firewalls, credentials and permissions must also allow the connection. This procedure does not reinstall the agent or require new Supaflow OAuth consent.

For later endpoint changes, use ALTER NETWORK RULE ... SET VALUE_LIST = (...) on your customer rule and include its entire desired endpoint list. That command also replaces rather than appends. Keep a copy of your custom rule and integration rule list; check them after upgrades, network reconfiguration, or rerunning the wizard setup SQL. Preservation through those operations has not yet been verified.

Snowflake wildcards match one subdomain level only. Redshift endpoints with multiple variable subdomains need their exact hostname. Private endpoints need additional private connectivity setup. See Snowflake network rule documentation for supported hostname patterns and ports.

Keep S3 Access Specific to Your Workload

For customer S3 access, allow the bucket endpoint and region used by your connector. Add the regional STS endpoint when using role assumption; do not allow every AWS region solely to connect one bucket. Redshift may also need S3 access for staging, in addition to its database hostname and port.

The Native App's default S3 coverage includes the global bucket pattern and regional bucket/API endpoints for us-east-1, us-east-2, us-west-2, eu-west-1, and eu-central-1. Add customer-owned rules for other regions or endpoint shapes.

Keep the existing Supaflow defaults when attaching your custom rule. Snowflake internal-stage uploads and downloads can need S3 endpoints even when you have no S3 datasource. Do not remove those endpoints without verifying the affected Snowflake load and unload operations.

Snowflake schema refreshes can also download query-result chunks from S3. Run the following in the datasource's Snowflake account, which may differ from the account hosting the Native App:

SELECT CURRENT_ACCOUNT(), CURRENT_REGION();

SELECT value:host::STRING AS host, value:port::INTEGER AS port
FROM TABLE(FLATTEN(INPUT => PARSE_JSON(SYSTEM$ALLOWLIST())))
WHERE value:type::STRING = 'STAGE';

Compare these hosts with the bound integration's rules. Keep the actual region and hostname spelling, including s3.<region> versus s3-<region>. If a refresh fails downloading chunks, follow the troubleshooting steps below.

For reference, see inspecting application references, altering external access integrations, and updating network rules.

---

Troubleshooting

OAuth popup does not complete

Allow the popup opened by Snowsight. Sign in to Supaflow, choose the intended account or organization, approve consent, and return to Snowsight. Check that network access is Connected and the sign-in security integration is reviewed before retrying authentication.

If the agent appears in another Supaflow account, check which account you chose during consent. Do not switch the app's backend or tenant on an enrolled service; contact support for help with an incorrect enrollment.

Agent has not appeared, or is still Registered

A Registered agent needs approval in Supaflow Settings → Agents. If no agent appears, confirm the Supaflow account selected during consent, then check the service and compute pool in Snowsight:

CALL SUPAFLOW_NATIVE_APP.core.get_agent_status();
SHOW COMPUTE POOLS LIKE 'SUPAFLOW_NATIVE_APP_POOL';
SELECT SYSTEM$GET_SERVICE_STATUS('SUPAFLOW_NATIVE_APP.SUPA_AGENT_SERVICES.SUPAFLOW_AGENT_SERVICE');

Replace the app and pool names for your installation. A newly provisioned pool can take several minutes to become active. The container may remain pending while Snowflake schedules it or prepares its storage and image.

OAuth is Configured, but an existing service is Suspended

Authentication does not recreate or resume an existing service. Resume it with:

CALL SUPAFLOW_NATIVE_APP.core.start_agent();

Controller cannot resume the service

Check its Snowflake account, selected account role, and the installed app's app_public role grant. For key-pair authentication, verify that the controller's private key matches the public key registered on its Snowflake user. See Configure a Controller.

Agent is Running, but jobs fail

Check the job's details and per-object errors in Supaflow. Agent registration and approval can succeed before connector synchronization finishes. Check connector availability, datasource credentials, endpoint permissions, and the source and destination connection tests.

For container startup logs, replace the app name and run:

SELECT SYSTEM$GET_SERVICE_LOGS('SUPAFLOW_NATIVE_APP.SUPA_AGENT_SERVICES.SUPAFLOW_AGENT_SERVICE', 0, 'supaflow-agent', 100);

Keep logs containing credentials, signed URLs, or tokens private when contacting support.

Schema refresh fails downloading Snowflake result chunks

A connection test can pass while a larger refresh reports Max retry reached for the download of chunk#0, a null HTTP response, or a fallback to JDBC metadata. Query-result downloads may use a separate S3 host. These errors alone do not establish which host is blocked.

1. Identify the actual host. Record the datasource, refresh job and affected schemas. Run SYSTEM$ALLOWLIST() in the datasource's account, not simply the SPCS hosting account. Check the agent logs for the chunk-download hostname. If it is absent, contact Supaflow support for a temporary JDBC DEBUG capture. Signed download URLs and tokens must stay in private logs; copy only the hostname and port into a rule.
2. Add a customer-owned rule. Follow Add Custom Connector Network Access. Use the exact observed host, for example example-stage-bucket.s3.us-east-2.amazonaws.com:443. A global S3 wildcard does not cover every regional hostname. Attach your rule to the integration returned by SHOW REFERENCES IN APPLICATION, preserving every existing rule.
3. Verify the effective configuration. Describe both your rule and the bound integration. Confirm the host/port and original rules are still present. Use ALTER for updates; do not drop/recreate the integration, replace the app's original rule, change secret permissions, or modify its OAuth security integration.
4. Run a fresh refresh and check its final result. Let the current job finish before submitting another. Require a successful terminal status, no failed schemas, and populated objects for the schemas that previously failed. If the issue affected staging, verify a pipeline load too. An early warning or a successful connection test is not sufficient evidence.

The customer-rule procedure has been validated on a running Native App service without reinstalling, restarting the agent, recreating the integration, or repeating OAuth consent. Keep your custom rule for the endpoints you need, and check its attachment after upgrades or network reconfiguration.

Temporary JDBC DEBUG logging should be disabled after collecting evidence. Console log retrieval can truncate large captures; support can recover the complete persisted log. Preserve the service's block volume and key secrets while troubleshooting.

---

Remove or Reinstall the App

1. In Supaflow, use Deactivate Agent. If datasource or linked-account credentials use this agent's private encryption key, complete the offered migration to system encryption before deactivation.

2. After migration and deactivation finish, uninstall the app in Snowsight, or run the following as its owner using the actual installed app name:

   DROP APPLICATION SUPAFLOW_NATIVE_APP CASCADE;

Native App deactivation in Supaflow does not drop its Snowflake service. Uninstalling removes app-owned services, block storage, secrets, compute pools, and warehouses. Do not uninstall before migrating credentials that still need those keys. Customer-owned network rules and integrations can remain; remove those separately only after checking that no other workloads use them.

---

Related Pages

• Sources -- Source connector setup guides (Salesforce, HubSpot, PostgreSQL, and more)
• Destinations -- Destination connector setup guides
• Snowflake Destination -- Snowflake destination configuration reference
• Ingestion Pipelines -- Create and configure data ingestion pipelines
• Activation Pipelines -- Push transformed data back to SaaS applications
• Orchestrations -- Combine ingestion, transformation, and activation into scheduled flows
• Schedules -- Configure pipeline and orchestration schedules
• Activities -- Monitor job runs and sync history
• Agents -- Agent management reference

---

Support

Need help? Contact us at support@supa-flow.io