Skip to Content

Add Samva to Vercel

Install Samva from Vercel to give your agent a mailbox. Samva adds its API key and mailbox ID to your projects and can deliver messages to your app.

Add a mailbox to the Vercel projects that run your agent. Samva writes the variables your code needs, so you skip creating a key and copying it into each project.

An organization owner or admin installs it. You choose the workspace, the mailbox, and the projects. Nothing changes in a project until you select Install.

What Samva adds

Samva sets these variables on each project you choose, for Production, Preview, and Development.

VariableWhat it holds
SAMVA_API_KEYA key that reads and writes the mailbox you chose. Every message it sends waits for a person to approve it.
SAMVA_MAILBOX_IDThe ID of that mailbox.
SAMVA_WEBHOOK_SECRETThe secret that verifies the messages Samva sends to your app. Set only when you enter a receiving URL.

The key reaches only the chosen mailbox. A person approves each message it sends in Needs you. See Review mailbox actions.

Install

  1. In the dashboard, open Integrations, choose Vercel, then choose Add to Vercel.
  2. In Vercel, choose the account or team that owns your projects and approve the install.
  3. Back in Samva, sign in if asked. Choose the workspace that should own the mailbox.
  4. Choose a mailbox, or create one on your workspace's included address.
  5. Choose up to 25 projects.
  6. Optionally set Receive messages at. Leave it empty to skip receiving messages.
  7. Review what Samva writes, then select Install. Samva returns you to Vercel.

Redeploy a project to pick up the new variables.

Receive messages

When you set Receive messages at, Samva creates a webhook for the chosen mailbox and sends it the mailbox's events. The field starts with /eve/v1/samva on the project's production URL, the path the Eve and Chat SDK adapters listen on. Replace it with any HTTPS URL you control.

Verify each request with SAMVA_WEBHOOK_SECRET and the @samva/webhooks verifier.

Build the agent

Install the package for your framework and the project has what it needs:

  • Eve: mount @samva/eve, which receives messages at /eve/v1/samva.
  • Vercel AI SDK: give the agent samvaTools from @samva/ai-sdk.

Remove Samva from a project

Remove the integration in Vercel. Samva turns off the keys it created for that install and removes its webhook. Rotating an installed key keeps the install's mark, so the replacement stops too. Your mailbox and its messages stay.

An installed key shows Vercel in Developers → API keys. One install makes one key, shared by every project you chose. Revoke it there to stop all of them without removing the install.

If an install fails

Each step says what failed. Choose Try again with the same selections: Samva reuses the key and secret it already made, so a second attempt never creates a duplicate.

MessageWhat to do
This install belongs to another workspaceChoose the workspace you started from, or start again with Add to Vercel.
Vercel could not verify this installThe approval expired. Start again with Add to Vercel.
Your plan limit was reachedRevoke an API key you no longer use, or change plans, then try again.

Add a mailbox to an existing install

Samva is one integration in Vercel, shared with automatic DNS setup. If you already installed it, open the integration in Vercel and choose Configure. Samva opens the same page, and you add a mailbox to more projects without approving a new install.

Use Vercel for DNS too

The same integration sets up DNS records for domains that Vercel hosts. See automatic DNS setup. Removing Samva from Vercel turns off the keys it created and disconnects that DNS connection until you reconnect it.

Related documentation

On this page