Skip to content
Get packs

Guide · Agent skill

How to use the Protected Vercel Deployments agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

This guide explains the protected-vercel-deployments agent skill, a set of instructions that lets an AI agent open and inspect Vercel preview or production URLs that sit behind Vercel Authentication, SSO or Deployment Protection. It is for developers and teams who want an agent to test or review a protected deployment using agent-browser. By the end you will know how to install the skill, check your prerequisites, make a natural request that triggers it, and recognise when a human needs to act.

Protected Vercel Deploymentsvercel-labs/agent-browser · Apache-2.0

Quick start

  1. 1Download and unzip the skill. Download the ZIP from this page and unzip it so the protected-vercel-deployments folder with SKILL.md is in ~/.claude/skills/ or a project's .claude/skills/ folder. Alternatively, upload it in the Claude apps under Settings, Capabilities, Skills.
  2. 2Install the tools. Make sure agent-browser is available through npx or as an installed binary, and that the Vercel CLI is at or above the minimum version listed on this page.
  3. 3Sign in to Vercel. Run vc whoami to confirm your identity. If you are not signed in, run vc login yourself or set VERCEL_TOKEN.
  4. 4Ask for the protected URL. Give the agent the preview or production URL, along with the Vercel project name and team scope. The agent can then open the page with the short-lived token.
  5. 5Review the result. The agent takes a snapshot of the page and reports what it found. If access is blocked, follow its instructions, such as adding a Trusted Sources rule in the dashboard.

What the skill makes the agent do

Vercel can hide preview and production sites behind a login wall. When an agent opens such a URL, it gets redirected to a Vercel login page or receives a 401 or 403 response. This skill tells the agent how to get past that wall the intended way: it uses the signed-in developer's Vercel CLI identity to mint a short-lived OIDC token, then passes that token to a browser session so the agent can load and inspect the page.

If access is still blocked, the skill tells the agent to stop and ask a human to add a Trusted Sources rule in the Vercel dashboard. It does not make the site public or disable protection.

How to install the protected-vercel-deployments skill

Download the skill ZIP from this page. It contains a single file, SKILL.md. Unzip it so the skill folder sits in one of these locations:

  • Personal skills for all your projects: ~/.claude/skills/
  • Project-only skills: .claude/skills/ inside your project directory
  • Claude apps: open Settings, go to Capabilities, then Skills, and upload the skill there

Check the prerequisites before you start

The skill needs several tools and access rights. Check them first so the agent does not stop halfway through a task.

  • The agent-browser CLI, either through npx agent-browser or as an installed binary
  • A Vercel CLI at or above the minimum version listed on this skill page. Older versions can print the token to stderr, where it may leak into logs
  • An authenticated Vercel identity, either from vc login or a VERCEL_TOKEN environment variable
  • A Vercel project with Deployment Protection enabled, and access to the target team or scope
  • The skill runs scripts and uses the network
vc whoami vc --version

Open a protected preview with a short-lived token

For a preview in the same project as your local development identity, the skill mints a development OIDC token with the Vercel CLI and sends it as a header when the browser opens the page. The default Trusted Sources self-access rule usually makes extra configuration unnecessary.

Create a named browser session, set the target URL, project and scope, then open the page with the token. The header applies to the page and the scripts, styles, fonts and in-page requests that belong to that origin. Afterwards the agent takes a snapshot to inspect the page.

  • Set the project and scope explicitly. If they cannot be inferred safely, the agent asks you.
  • Never print the token, paste it into source code or save it in an environment file.
  • If the browser session is closed or restarted, the authenticated open command must be run again.
export AGENT_BROWSER_SESSION="$(agent-browser session id --scope worktree --prefix vercel-preview)" export VERCEL_PREVIEW_URL="https://my-app.vercel.app" export VERCEL_PROJECT="my-app" export VERCEL_SCOPE="my-team" ( TOKEN="$(vc project token "$VERCEL_PROJECT" --scope "$VERCEL_SCOPE")" test -n "$TOKEN" agent-browser open "$VERCEL_PREVIEW_URL" --headers \ "{\"x-vercel-trusted-oidc-idp-token\":\"$TOKEN\"}" ) agent-browser snapshot -i

What to do when access is blocked

Some cases need a change to access control, which only an authorised person can make. A local token reaches Preview deployments by default, but reaching protected Production from a local token needs a Trusted Sources rule. The same is true for a caller in another project or team, or when the target project's self-access rules were customised.

The only supported place to add that rule is the dashboard: an authorised human opens the project's Settings, then Deployment Protection, then Trusted Sources, and adds only the required caller and environment mapping. The agent should give you the exact rule and wait for you to confirm it is saved before retrying.

  • Redirect to vercel.com/login: Deployment Protection did not accept the request.
  • TRUSTED_SOURCES_ENVIRONMENT_MISMATCH: the token is valid but cannot reach the target environment.
  • Application 401 or 403 after protection passes: the app's own login is the problem, so debug it separately.
  • Application 404 on a deliberately missing route: the request got past protection and reached the app.

Safety notes: scripts, network and credentials

The skill runs shell commands and sends requests over the network, so review what it will run before you approve it. It is designed to avoid exposing secrets, but the bypass option deserves particular care.

The skill tells the agent not to use Deployment Protection Exceptions to unblock itself, because those make the domain public. The static-secret fallback, Protection Bypass for Automation, changes access control and needs explicit authorisation. A bypass secret is powerful if mishandled, and a saved browser state that contains the resulting cookie should be treated as a credential too.

  • Do not share OIDC tokens, bypass secrets, authenticated URLs or saved browser state in logs, screenshots or source files.
  • Use the static fallback only when OIDC is not viable, and create a dedicated secret so it can be rotated separately.
  • Use the skill only on deployments you are authorised to test.

What people use it for

  • Have an agent click through a protected preview deployment and report layout or console problems before a code review.
  • Ask an agent to check that a staging site loads and that its main flows work after a deploy.
  • Have an agent inspect a protected Vercel preview to confirm a pull request's visible changes.
  • Automate routine checks on protected staging URLs that a team uses with agent-browser.

Frequently asked questions

How do I install the protected Vercel deployments agent skill?

Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for all your projects, or into .claude/skills/ inside one project. You can also upload it in the Claude apps under Settings, Capabilities, Skills.

Is the protected-vercel-deployments skill free?

This page does not state pricing or licence terms for the skill itself. The source repository is listed under the Apache-2.0 licence, so check that licence for the terms that apply to the code.

What do I need to use this skill?

You need the agent-browser CLI, a Vercel CLI at or above the minimum version listed on this page, an authenticated Vercel identity through vc login or VERCEL_TOKEN, and a Vercel project with Deployment Protection and access to its team or scope.

Why does my Vercel preview URL redirect to a login page?

Deployment Protection did not accept the request. Check that the token is being sent with the x-vercel-trusted-oidc-idp-token header, that the Vercel CLI is authenticated, and that the project and scope are correct.

Does this skill bypass Vercel password protection or make my site public?

No. The skill tells the agent not to disable Deployment Protection, make the deployment public or use Deployment Protection Exceptions to unblock itself. Adding a Trusted Sources rule is done by a human in the Vercel dashboard.

How is this different from Protection Bypass for Automation?

The skill's main path uses a short-lived OIDC token from your Vercel CLI identity. Protection Bypass for Automation uses a static secret, which the skill treats as a fallback that needs explicit authorisation because it changes access control.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you want an agent to test or review a Vercel preview or production deployment that sits behind Vercel Authentication, SSO or Deployment Protection, and you can sign in with the Vercel CLI. Pick something else if the site is already public, since the skill adds nothing there, or if you need to give access to outsiders, because that requires a Vercel rule change rather than an agent workaround.

Download the skill