Deploy to Vercel

Step 1: Create a GitHub repository for your project

If you do not have an Inkeep project already, follow these steps to create one. Then push your project to a repository on GitHub.

Step 2: Create a Postgres Database

Create a Postgres database on the Vercel Marketplace or directly at Neon.

Step 3: Create a Doltgres Database

Create a Doltgres database at DoltHub.

Step 4: Configure Database Connection

Set your database connection string as an environment variable:

# Doltgres Database
INKEEP_AGENTS_MANAGE_DATABASE_URL=
# Postgres Database
INKEEP_AGENTS_RUN_DATABASE_URL=

Step 5: Create a Vercel account

Step 6: Create a Vercel project for Manage API

Vercel New Project - Manage API

Note

The Framework Preset should be "Hono" and the Root Directory should be apps/manage-api.

Required environment variables for Manage API:

ENVIRONMENT=production

INKEEP_AGENTS_MANAGE_API_BYPASS_SECRET=

# Doltgres Database
INKEEP_AGENTS_MANAGE_DATABASE_URL=
# Postgres Database
INKEEP_AGENTS_RUN_DATABASE_URL=

NANGO_SECRET_KEY=
NANGO_SERVER_URL=https://api.nango.dev

Environment Variable	Value
`ENVIRONMENT`	`production`
`INKEEP_AGENTS_MANAGE_API_BYPASS_SECRET`	Run `openssl rand -hex 32` in your terminal to generate this value. Save this value for `INKEEP_AGENTS_MANAGE_API_BYPASS_SECRET` in Step 7.
`INKEEP_AGENTS_MANAGE_DATABASE_URL`	Doltgres connection string from Step 3 (e.g., `postgresql://user:password@host:5432/database`)
`INKEEP_AGENTS_RUN_DATABASE_URL`	Postgres connection string from Step 4 (e.g., `postgresql://user:password@host:5433/database`)
`NANGO_SECRET_KEY`	Nango secret key from your Nango Cloud account. Note: Local Nango setup won't work with Vercel deployments.
`NANGO_SERVER_URL`	`https://api.nango.dev`

Step 7: Create a Vercel project for Run API

Vercel New Project - Run API

Note

The Framework Preset should be "Hono" and the Root Directory should be apps/run-api.

Required environment variables for Run API:

ENVIRONMENT=production

ANTHROPIC_API_KEY=
OPENAI_API_KEY=
GOOGLE_GENERATIVE_AI_API_KEY=

INKEEP_AGENTS_RUN_API_BYPASS_SECRET=

# Postgres Database
INKEEP_AGENTS_RUN_DATABASE_URL=

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ingest.us.signoz.cloud:443/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS=signoz-ingestion-key=<your-ingestion-key>

NANGO_SECRET_KEY=
NANGO_SERVER_URL=https://api.nango.dev

INKEEP_AGENTS_JWT_SIGNING_SECRET=

Environment Variable	Value
`ENVIRONMENT`	`production`
`ANTHROPIC_API_KEY`	Your Anthropic API key
`OPENAI_API_KEY`	Your OpenAI API key
`GOOGLE_GENERATIVE_AI_API_KEY`	Your Google Gemini API key
`INKEEP_AGENTS_RUN_API_BYPASS_SECRET`	Run `openssl rand -hex 32` in your terminal to generate this value. Save this value for `INKEEP_AGENTS_RUN_API_BYPASS_SECRET` in Step 7.
`INKEEP_AGENTS_RUN_DATABASE_URL`	Postgres connection string from Step 3 (e.g., `postgresql://user:password@host:5432/database`)
`NANGO_SECRET_KEY`	Nango secret key from your Nango Cloud account. Note: Local Nango setup won't work with Vercel deployments.
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	`https://ingest.us.signoz.cloud:443/v1/traces`
`OTEL_EXPORTER_OTLP_TRACES_HEADERS`	`signoz-ingestion-key=<your-ingestion-key>`. Use the instructions from SigNoz Cloud Setup to configure your ingestion key. Note: Local SigNoz setup won't work with Vercel deployments.
`NANGO_SERVER_URL`	`https://api.nango.dev`
`INKEEP_AGENTS_JWT_SIGNING_SECRET`	Run `openssl rand -hex 32` in your terminal to generate this value. Save this value for `INKEEP_AGENTS_JWT_SIGNING_SECRET` in Step 7.

Step 8: Create a Vercel project for Manage UI

Vercel New Project - Manage UI

Note

The Framework Preset should be "Next.js" and the Root Directory should be apps/manage-ui.

Required environment variables for Manage UI:

ENVIRONMENT=production

PUBLIC_INKEEP_AGENTS_RUN_API_URL=
PUBLIC_INKEEP_AGENTS_RUN_API_BYPASS_SECRET=

PUBLIC_INKEEP_AGENTS_MANAGE_API_URL=
INKEEP_AGENTS_MANAGE_API_URL=
INKEEP_AGENTS_MANAGE_API_BYPASS_SECRET=

PUBLIC_SIGNOZ_URL=https://<your-organization>.signoz.cloud
SIGNOZ_API_KEY=

PUBLIC_NANGO_SERVER_URL=https://api.nango.dev
PUBLIC_NANGO_CONNECT_BASE_URL=https://connect.nango.dev
NANGO_SECRET_KEY=

Environment Variable	Value
`ENVIRONMENT`	`production`
`PUBLIC_INKEEP_AGENTS_RUN_API_URL`	Your Vercel deployment URL for Run API
`PUBLIC_INKEEP_AGENTS_RUN_API_BYPASS_SECRET`	Your generated Run API bypass secret from Step 6
`PUBLIC_INKEEP_AGENTS_MANAGE_API_URL`	Your Vercel deployment URL for Manage API (skip if same as `INKEEP_AGENTS_MANAGE_API_URL`)
`INKEEP_AGENTS_MANAGE_API_URL`	Your Vercel deployment URL for Manage API
`INKEEP_AGENTS_MANAGE_API_BYPASS_SECRET`	Your generated Manage API bypass secret from Step 5
`PUBLIC_SIGNOZ_URL`	Use the instructions from SigNoz Cloud Setup to configure your SigNoz URL. Note: Local SigNoz setup won't work with Vercel deployments.
`SIGNOZ_API_KEY`	Use the instructions from SigNoz Cloud Setup to configure your SigNoz API key. Note: Local SigNoz setup won't work with Vercel deployments.
`NANGO_SECRET_KEY`	Nango secret key from your Nango Cloud account. Note: Local Nango setup won't work with Vercel deployments.
`PUBLIC_NANGO_SERVER_URL`	`https://api.nango.dev`
`PUBLIC_NANGO_CONNECT_BASE_URL`	`https://connect.nango.dev`

Step 9: Enable Vercel Authentication

To prevent anyone from being able to access the UI, we recommend enabling Vercel authentication for all deployments: Settings > Deployment Protection > Vercel Authentication > All Deployments.

Step 10: Create a Vercel project for your MCP server (optional)

Vercel New Project - MCP Server

Note

The Framework Preset should be "Next.js" and the Root Directory should be apps/mcp.

For more information on how to add MCP servers to your project, see Create MCP Servers.

Push your Agent

Step 1: Configure your root .env file

INKEEP_AGENTS_MANAGE_API_BYPASS_SECRET=
INKEEP_AGENTS_RUN_API_BYPASS_SECRET=

Step 2: Create a cloud configuration file

Create a new configuration file named inkeep-cloud.config.ts in your project's src directory, alongside your existing configuration file.

import { defineConfig } from "@inkeep/agents-cli/config";

const config = defineConfig({
  tenantId: "default",
  agentsManageApi: {
    url: "https://<your-manage-api-url>",
    apiKey: process.env.INKEEP_AGENTS_MANAGE_API_BYPASS_SECRET,
  },
  agentsRunApi: {
    url: "https://<your-run-api-url>",
    apiKey: process.env.INKEEP_AGENTS_RUN_API_BYPASS_SECRET,
  },
});

export default config;

Step 3: Push your Agent

cd /src/<your-project-directory>
inkeep push --config ../inkeep-cloud.config.ts

Pull your Agent

cd /src
inkeep pull --config inkeep-cloud.config.ts

Function Tools with Vercel Sandbox

When deploying to serverless environments like Vercel, you can configure function tools to execute in Vercel Sandbox MicroVMs instead of your Agent's runtime service. This is required for serverless platforms since child process spawning is restricted.

Why Use Vercel Sandbox?

When to use each provider:

Native - Use for traditional cloud deployments (VMs, Docker, Kubernetes), self-hosted servers, or local development
Vercel Sandbox - Required for serverless platforms (Vercel, AWS Lambda, etc.) or if you'd like to isolate tool executions

Setting Up Vercel Sandbox

Step 1: Get Vercel Credentials

You'll need three credentials from your Vercel account:

Vercel Token - Create an access token at vercel.com/account/tokens
Team ID - Find in your team settings at vercel.com/teams
Project ID - Find in your Vercel project settings

Step 2: Configure Sandbox in Your Application

Update your Run API to use Vercel Sandbox.

In the apps/run-api/src folder, create a sandbox.ts file:

const isProduction = process.env.ENVIRONMENT === "production";

export const sandboxConfig = isProduction
  ? {
      provider: "vercel",
      runtime: "node22", // or 'typescript'
      timeout: 60000, // 60 second timeout
      vcpus: 4, // Allocate 4 vCPUs
      teamId: process.env.SANDBOX_VERCEL_TEAM_ID!,
      projectId: process.env.SANDBOX_VERCEL_PROJECT_ID!,
      token: process.env.SANDBOX_VERCEL_TOKEN!,
    }
  : {
      provider: "native",
      runtime: "node22",
      timeout: 30000,
      vcpus: 2,
    };

Import it into your index.ts file:

import { sandboxConfig } from "./sandbox.ts";
// ...
const app: Hono = createExecutionApp({
  // ...
  sandboxConfig, // NEW
});

Step 3: Add Environment Variables to Run API

Add these environment variables in your Vercel project to your Run API app:

SANDBOX_VERCEL_TOKEN=your_vercel_access_token
SANDBOX_VERCEL_TEAM_ID=team_xxxxxxxxxx
SANDBOX_VERCEL_PROJECT_ID=prj_xxxxxxxxxx

"Failed to refresh OIDC token" error:

This occurs when you're not in a Vercel environment or you don't provide a Vercel access token
Solution: Use a Vercel access token from vercel.com/account/tokens

Function execution timeouts:

Increase the timeout value in sandbox configuration
Consider allocating more vcpus for resource-intensive functions
Check Vercel Sandbox limits for your plan

Dependency installation failures:

Ensure dependencies are compatible with Node.js 22
Check that package versions are specified correctly
Verify network access to npm registry

High costs:

Reduce vcpus allocation if functions don't need maximum resources
Optimize function code to execute faster
Consider caching results when possible

Use environment variables – Never hardcode credentials
Start with fewer vCPUs – Scale up only if needed
Set reasonable timeouts – Prevent runaway executions
Monitor usage – Track sandbox execution metrics in Vercel dashboard
Test thoroughly – Verify functions work in sandbox environment before deploying
Choose the right provider – Use native for VMs/Docker/K8s, Vercel Sandbox for serverless only

For more information on function tools, see:

Deployment Protection

The Inkeep Agent Framework provides health endpoints for Kubernetes-style probes and optional integration with Vercel Checks for automated deployment protection.

Health Endpoints

Two health endpoints are available for monitoring deployment readiness:

`/health` - Liveness Probe

A lightweight endpoint that returns immediately to indicate the service is running.

Response: HTTP 204 (No Content)
Use case: Kubernetes liveness probes, load balancer health checks
Latency: Sub-millisecond (no external calls)

curl -I https://your-api.vercel.app/health
# HTTP/2 204

`/ready` - Readiness Probe

A comprehensive endpoint that verifies database connectivity before serving traffic.

Response (healthy): HTTP 200 with JSON status
Response (unhealthy): HTTP 503 with RFC 7807 Problem Details
Use case: Kubernetes readiness probes, deployment verification

# Healthy response
curl https://your-api.vercel.app/ready
{
  "status": "ok",
  "manageDb": true,
  "runDb": true
}

# Unhealthy response (503 Service Unavailable)
{
  "type": "about:blank",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "One or more health checks failed",
  "checks": {
    "manageDb": false,
    "runDb": true
  }
}

Vercel Deployment Checks with GitHub Actions

Enable automated deployment protection using Vercel Deployment Checks combined with a GitHub Action. This approach blocks production deployments from being promoted until your health checks pass.

How It Works

Deployment Created: Vercel creates a production deployment but doesn't promote it yet
GitHub Action Runs: A workflow triggers when the deployment is ready and hits the /ready endpoint
Status Reported: The GitHub Action reports success/failure back to GitHub
Vercel Reads Status: Vercel reads the GitHub commit status and promotes the deployment only if checks pass

Step 1: Add the GitHub Action Workflow

The Inkeep Agent Framework includes a pre-configured workflow at .github/workflows/deployment-health-check.yml:

name: Deployment Health Check

on:
  deployment_status:

jobs:
  health-check:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - name: Wait for cold start
        run: sleep 10

      - name: Check /health endpoint (liveness)
        run: |
          curl -f -s -o /dev/null -w "%{http_code}" \
            "${{ github.event.deployment_status.target_url }}/health" \
            --retry 3 --retry-delay 5

      - name: Check /ready endpoint (readiness)
        run: |
          response=$(curl -f -s "${{ github.event.deployment_status.target_url }}/ready" \
            --retry 3 --retry-delay 5)
          echo "Response: $response"
          echo "$response" | jq -e '.status == "ok"'

Step 2: Enable Deployment Checks in Vercel

Ensure your project is connected to GitHub using Vercel for GitHub
Go to Project Settings > Deployment Checks
Click Add Checks and select the health-check job from your GitHub Actions
Production deployments will now wait for the health check to pass before being promoted

Step 3: Test the Integration

Push a change to your default branch
Vercel creates a production deployment
The GitHub Action runs and checks the /ready endpoint
Once the check passes, Vercel promotes the deployment to your production domains

GitHub Action not running:

Ensure the workflow file exists at .github/workflows/deployment-health-check.yml
Verify the workflow is enabled in your repository's Actions settings

Check not appearing in Vercel:

Verify your project is connected to GitHub via Vercel for GitHub
Ensure the check is selected in Project Settings > Deployment Checks

Health check fails but service is healthy:

The /ready endpoint checks database connectivity
Ensure database connection strings are correct in the deployment
Check database accessibility from the Vercel deployment region
Increase the cold start wait time if needed

Bypassing checks:

Use Force Promote from the deployment details page in Vercel

Staging and Production Deployment Strategy

This section explains how to configure Vercel for a staged deployment workflow where:

Pushes to main create staging (preview) deployments
GitHub releases trigger production deployments

This approach allows you to test changes on staging before promoting to production, with full control over production releases.

Deployment Flow Overview

┌──────────────────────────────────────────────────────────────────┐
│                     DEVELOPMENT WORKFLOW                         │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│   PR Created ──────► Vercel Preview Deployment                   │
│                      (pr-123-<project>.vercel.app)               │
│                                                                  │
│   PR Merged to main ──────► Vercel Preview Deployment (Staging)  │
│                             (main-<project>.vercel.app)          │
│                                                                  │
│   GitHub Release Published ──────► GitHub Action                 │
│                                    │                             │
│                                    ├──► Deploy to Preview        │
│                                    ├──► Wait for Checks          │
│                                    └──► Promote to Production    │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

Step 1: Disable Automatic Production Deployments

By default, Vercel deploys to production when you push to your production branch (usually main). To separate staging from production, disable automatic production deployments:

Go to Project Settings > Git in the Vercel Dashboard
Under Production Branch, change the value to _disabled_
Save your changes

Note

Setting the Production Branch to _disabled_ is a special Vercel value that prevents any branch from automatically triggering production deployments. All pushes, including to main, will create preview deployments instead.

After this configuration:

Pushes to main create preview deployments at main-<project>.vercel.app
Pushes to PR branches create preview deployments at <branch>-<project>.vercel.app
No branch triggers automatic production deployments

Step 2: Configure GitHub Actions for Production Releases

The Inkeep Agent Framework includes a workflow that deploys to production when you publish a GitHub release. This integrates with the existing changesets release flow.

The workflow file is located at .github/workflows/vercel-production.yml:

name: Deploy to Vercel Production

on:
  release:
    types: [published]

env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

jobs:
  deploy:
    name: Deploy to Production
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event.release.tag_name }}

      - name: Install Vercel CLI
        run: npm install -g vercel

      - name: Pull Vercel Environment
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}

      - name: Build
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}

      - name: Deploy Preview for Checks
        id: deploy
        run: |
          DEPLOYMENT_URL=$(vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }})
          echo "url=$DEPLOYMENT_URL" >> $GITHUB_OUTPUT
          echo "Deployed to: $DEPLOYMENT_URL"

      - name: Wait for Deployment Checks
        run: |
          echo "Waiting for Vercel deployment checks to complete..."
          vercel inspect ${{ steps.deploy.outputs.url }} --token=${{ secrets.VERCEL_TOKEN }} --wait

      - name: Promote to Production
        run: vercel promote ${{ steps.deploy.outputs.url }} --token=${{ secrets.VERCEL_TOKEN }}

Key features:

Triggered by GitHub releases: Uses release: types: [published] to deploy only when you explicitly publish a release
Uses the tagged commit: Checks out github.event.release.tag_name to ensure the exact release version is deployed
Deployment checks: Deploys to a preview URL first, waits for Vercel Checks to pass, then promotes to production
Vercel CLI: Uses vercel deploy --prebuilt for faster deployments with pre-built artifacts

Step 3: Configure Required Secrets

The GitHub Actions workflow requires three secrets to authenticate with Vercel. Add these to your GitHub repository:

Settings > Secrets and variables > Actions > New repository secret

Secret	Description	How to Obtain
`VERCEL_TOKEN`	API token for Vercel CLI authentication	Vercel Dashboard > Settings > Tokens - Create a new token with appropriate scope
`VERCEL_ORG_ID`	Your Vercel team/organization ID	Run `vercel link` in your project, then check `.vercel/project.json` for `orgId`
`VERCEL_PROJECT_ID`	Your Vercel project ID	Run `vercel link` in your project, then check `.vercel/project.json` for `projectId`

Note

After running vercel link, your .vercel/project.json will contain both IDs:

{
  "orgId": "team_xxxxxxxxxxxx",
  "projectId": "prj_xxxxxxxxxxxx"
}

Copy these values to your GitHub repository secrets. Do not commit this file to your repository if it contains sensitive project identifiers.

Step 4: Optional Staging Domain Configuration

For easier access to your staging environment, you can configure a custom domain that always points to your main branch deployments.

Go to Project Settings > Domains in the Vercel Dashboard
Click Add Domain
Enter your staging domain (e.g., staging.yourdomain.com)
Under Git Branch, select main
Save your changes

Vercel will automatically:

Route traffic for the staging domain to the latest main branch deployment
Provision an SSL certificate for the domain
Update the deployment whenever main is updated

Example domain configuration:

Domain	Branch	Purpose
`staging.yourdomain.com`	`main`	Staging environment for testing
`yourdomain.com`	Production	Production (deployed via GitHub releases)

Creating a Production Release

With this configuration, the production deployment flow is:

Merge PRs to main: Changes go to staging automatically
Test on staging: Verify changes at staging.yourdomain.com or main-<project>.vercel.app
Create a GitHub release: Use the changesets workflow or manually create a release
Automatic production deployment: The GitHub Action builds, verifies, and promotes to production

# Using changesets (recommended)
pnpm changeset
git add .
git commit -m "chore: version packages"
git push

# When the "Version Packages" PR is merged, the release workflow creates a GitHub release
# which triggers the production deployment

Main branch still deploying to production:

Verify Production Branch is set to disabled in Project Settings > Git
Check that you saved the changes in the Vercel Dashboard

GitHub Action not triggering:

Ensure the workflow file exists at .github/workflows/vercel-production.yml
Verify the release is published, not just a draft
Check GitHub Actions is enabled for your repository

Deployment fails with authentication error:

Verify all three secrets are configured: VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID
Check that the Vercel token has not expired
Ensure the token has permissions for the target project

Staging domain not updating:

Verify the domain is configured with Git Branch set to main
Check DNS propagation if recently configured
Ensure the deployment completed successfully

Promote step fails:

The vercel promote command requires the deployment URL from the previous step
Check that deployment checks passed before promotion
Verify the deployment wasn't cancelled or deleted

Deploy to Vercel

Troubleshooting Functions

Best Practices

Troubleshooting Deployment Checks

Troubleshooting Staging/Production Deployments

On this page

Troubleshooting Functions

Best Practices

Troubleshooting Deployment Checks

Troubleshooting Staging/Production Deployments