Skip to content

Getting Started with Customer-Managed Prefect

Welcome to your customer-managed Prefect instance. This guide will help you set up your local environment and deploy your first workflow to your instance.

Prerequisites

Before you begin, ensure you have:

  • An active account on your customer-managed Prefect instance
  • Python 3.10 or newer installed

Step 1: Install Prefect

Install the Prefect package: 

pip install prefect

Check the releases page in the documentation to see which version of Prefect is supported with your customer-managed instance. If you need to install a specific version, you can do so with: 

pip install "prefect<3.6.6"

Replace 3.6.6 with the appropriate version for your instance.

Step 2: Create a Prefect Profile

Prefect profiles allow you to manage multiple configurations. Create a new profile for your customer-managed instance: 

prefect profile create profile-name

Replace profile-name with a descriptive name for your instance (for example, my-company or staging).

Step 3: Configure Your Instance URLs

Configure the profile with your customer-managed instance's URLs. Set the UI and API endpoints: 

prefect config set PREFECT_CLOUD_UI_URL=https://customer-instance-ui-url.dev
prefect config set PREFECT_CLOUD_API_URL=https://customer-instance-api-url.dev

Replace the URLs with your actual instance URLs. Your instance administrator can provide these if you don't have them.

Step 4: Generate and Configure Your API Key

Navigate to your settings in the Prefect UI and generate an API key. Then authenticate with your instance: 

prefect cloud login -k <API_KEY>

Replace <API_KEY> with the API key from your settings. You'll see a confirmation message when authentication is successful.

Work Pools

Customer-managed Prefect cannot use managed execution work pool options. Before deploying flows, ensure you have access to a work pool.

If you don't have one configured, contact your instance administrator or see the docs on configuring your own work pool.

Next: Create Your First Workflow

Now that you're set up, follow the Prefect Quickstart guide to create and deploy your first workflow. The quickstart covers:

  • Writing your first flow with @flow and @task decorators
  • Running flows locally to test them
  • Deploying flows to your instance
  • Scheduling workflows to run automatically

The main difference is that your flows will run on your customer-managed instance instead of Prefect Cloud, and you'll deploy to your organization's self-hosted work pool.

Common Tasks

Once you're ready, here are some common workflows:

Troubleshooting

If you encounter issues:

  • Verify your instance URLs are correct and accessible
  • Ensure your API key is valid (regenerate it in your settings if needed)
  • View your current configuration: prefect config view
  • Confirm that a work pool is available and configured for your deployments

For more help, refer to the full Prefect documentation or contact your instance administrator.