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

Deploy to Vercel

Troubleshooting Functions

Best Practices

Troubleshooting Deployment Checks

On this page

Troubleshooting Functions

Best Practices

Troubleshooting Deployment Checks