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.
| Variable | What it holds |
|---|---|
SAMVA_API_KEY | A key that reads and writes the mailbox you chose. Every message it sends waits for a person to approve it. |
SAMVA_MAILBOX_ID | The ID of that mailbox. |
SAMVA_WEBHOOK_SECRET | The 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
- In the dashboard, open Integrations, choose Vercel, then choose Add to Vercel.
- In Vercel, choose the account or team that owns your projects and approve the install.
- Back in Samva, sign in if asked. Choose the workspace that should own the mailbox.
- Choose a mailbox, or create one on your workspace's included address.
- Choose up to 25 projects.
- Optionally set Receive messages at. Leave it empty to skip receiving messages.
- 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
samvaToolsfrom@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.
| Message | What to do |
|---|---|
| This install belongs to another workspace | Choose the workspace you started from, or start again with Add to Vercel. |
| Vercel could not verify this install | The approval expired. Start again with Add to Vercel. |
| Your plan limit was reached | Revoke 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.