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 Turso Database

Create a Turso database on Vercel Marketplace or directly at Turso Cloud.

Step 3: Save your Turso Database URL and Auth Token

Create a token for your database, and then save the URL and token created.

TURSO_DATABASE_URL=
TURSO_AUTH_TOKEN=

Step 4: Create a Vercel account

Step 5: 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=

TURSO_DATABASE_URL=
TURSO_AUTH_TOKEN=

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.
`TURSO_DATABASE_URL`	Turso database URL you saved from Step 3
`TURSO_AUTH_TOKEN`	Turso auth token you saved from Step 3
`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 6: 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=

TURSO_DATABASE_URL=
TURSO_AUTH_TOKEN=

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.
`TURSO_DATABASE_URL`	Turso database URL you saved from Step 3
`TURSO_AUTH_TOKEN`	Turso auth token you saved from Step 3
`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 7: 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 8: 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 9: 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:

Deploy to Vercel

Troubleshooting Functions

Best Practices

On this page

Troubleshooting Functions

Best Practices