Deploy flows to any Node.js platform

Genkit has built-in integrations that help you deploy your flows to Cloud Functions for Firebase and Google Cloud Run, but you can also deploy your flows to any platform that can serve an Express.js app, whether it’s a cloud service or self-hosted.

This page, as an example, walks you through the process of deploying the default sample flow.

Before you begin

• Node.js 20+: Confirm that your environment is using Node.js version 20 or higher (node --version).
• You should be familiar with Genkit’s concept of flows.

1. Set up your project

1. Create a directory for the project:

   export GENKIT_PROJECT_HOME=~/tmp/genkit-express-project
   
   mkdir -p $GENKIT_PROJECT_HOME
   cd $GENKIT_PROJECT_HOME
   mkdir src

2. Initialize a Node.js project:

   npm init -y

3. Install Genkit and necessary dependencies:

   npm install --save genkit @genkit-ai/googleai
   npm install --save-dev typescript tsx
   npm install -g genkit-cli

2. Configure your Genkit app

1. Set up a sample flow and server:

   In src/index.ts, define a sample flow and configure the flow server:

   import { genkit, z } from 'genkit';
   import { googleAI } from '@genkit-ai/googleai';
   import { startFlowServer } from '@genkit-ai/express';
   
   const ai = genkit({
     plugins: [googleAI()],
     model: googleAI.model('gemini-2.5-flash'),
   });
   
   const helloFlow = ai.defineFlow(
     {
       name: 'helloFlow',
       inputSchema: z.object({ name: z.string() }),
       outputSchema: z.object({ greeting: z.string() }),
     },
     async (input) => {
       const { text } = await ai.generate('Say hello to ${input.name}');
       return { greeting: text };
     },
   );
   
   startFlowServer({
     flows: [helloFlow],
   });

   There are also some optional parameters for startFlowServer you can specify:

   • port: the network port to listen on. If unspecified, the server listens on the port defined in the PORT environment variable, and if PORT is not set, defaults to 3400.
   • cors: the flow server’s CORS policy. If you will be accessing these endpoints from a web application, you likely need to specify this.
   • pathPrefix: an optional path prefix to add before your flow endpoints.
   • jsonParserOptions: options to pass to Express’s JSON body parser

2. Set up model provider credentials:

   Configure the required environment variables for your model provider. This guide uses the Gemini API from Google AI Studio as an example.

   Get an API key from Google AI Studio

   After you’ve created an API key, set the GEMINI_API_KEY environment variable to your key with the following command:

   export GEMINI_API_KEY=<your API key>

   Different providers for deployment will have different ways of securing your API key in their environment. For security, ensure that your API key is not publicly exposed.

3. Prepare your Node.js project for deployment

Add start and build scripts to package.json

To deploy a Node.js project, define start and build scripts in package.json. For a TypeScript project, these scripts will look like this:

"scripts": {
  "start": "node --watch lib/index.js",
  "build": "tsc"
},

Build and test locally

Run the build command, then start the server and test it locally to confirm it works as expected.

npm run build

npm start

In another terminal window, test the endpoint:

curl -X POST "http://127.0.0.1:3400/helloFlow" \
  -H "Content-Type: application/json" \
  -d '{"data": {"name": "Genkit"}}'

Optional: Start the Developer UI

You can use the Developer UI to test flows interactively during development:

genkit start -- npm run start

Navigate to http://localhost:4000/flows to test your flows in the UI.

4. Deploy the project

Once your project is configured and tested locally, you can deploy to any Node.js-compatible platform. Deployment steps vary by provider, but generally, you configure the following settings:

Setting	Value
Runtime	Node.js 20 or newer
Build command	npm run build
Start command	npm start
Environment variables	Set GEMINI_API_KEY=<your-api-key> and other necessary secrets.

The start command (npm start) should point to your compiled entry point, typically lib/index.js. Be sure to add all necessary environment variables for your deployment platform.

After deploying, you can use the provided service URL to invoke your flow as an HTTPS endpoint.

Call your flows from the client

In your client-side code (e.g., a web application, mobile app, or another service), you can call your deployed flows using the Genkit client library. This library provides functions for both non-streaming and streaming flow calls.

First, install the Genkit library:

npm install genkit

Then, you can use runFlow for non-streaming calls and streamFlow for streaming calls.

Non-streaming Flow Calls

For a non-streaming response, use the runFlow function. This is suitable for flows that return a single, complete output.

import { runFlow } from 'genkit/beta/client';

async function callHelloFlow() {
  try {
    const result = await runFlow({
      url: 'http://127.0.0.1:3400/helloFlow', // Replace with your deployed flow's URL
      input: { name: 'Genkit User' },
    });
    console.log('Non-streaming result:', result.greeting);
  } catch (error) {
    console.error('Error calling helloFlow:', error);
  }
}

callHelloFlow();

Streaming Flow Calls

For flows that are designed to stream responses (e.g., for real-time updates or long-running operations), use the streamFlow function.

import { streamFlow } from 'genkit/beta/client';

async function streamHelloFlow() {
  try {
    const result = streamFlow({
      url: 'http://127.0.0.1:3400/helloFlow', // Replace with your deployed flow's URL
      input: { name: 'Streaming User' },
    });

    // Process the stream chunks as they arrive
    for await (const chunk of result.stream) {
      console.log('Stream chunk:', chunk);
    }

    // Get the final complete response
    const finalOutput = await result.output;
    console.log('Final streaming output:', finalOutput.greeting);
  } catch (error) {
    console.error('Error streaming helloFlow:', error);
  }
}

streamHelloFlow();

Authentication (Optional)

If your deployed flow requires authentication, you can pass headers with your requests:

const result = await runFlow({
  url: 'http://127.0.0.1:3400/helloFlow', // Replace with your deployed flow's URL
  headers: {
    Authorization: 'Bearer your-token-here', // Replace with your actual token
  },
  input: { name: 'Authenticated User' },
});