Setting up AI Gateway and Vercel Sandbox

May 7, 2026 · View on GitHub

deepsec uses two Vercel products. Most people only need the first.

Product	When you need it
AI Gateway	Always — for `process` and `revalidate`. One token covers both Claude and Codex; the gateway adds provider failover, observability, and zero data retention on top.
Vercel Sandbox	Only for `deepsec sandbox process` (distributed scans across microVMs). Skip it if you're running locally.

Both have a free tier suitable for evaluation. Real scans on production codebases will exceed the free tier — see Costs and credits below.

AI Gateway

Where you're running	Use this
Anywhere	API key (Option A)
Local + already linked to a Vercel project (`.vercel/project.json` exists)	OIDC token (Option B)
Inside `deepsec sandbox …`	OIDC token (automatic — same token authenticates both)

Option A: API key

Open the AI Gateway API Keys page.
Click Create key and follow the prompts.
Copy the key (vck_…). Keys never expire unless you revoke them.

In your scanning workspace's .env.local:

AI_GATEWAY_API_KEY=vck_…

Option B: OIDC token

If you're already running Vercel Sandbox, this is automatic — the same vercel env pull that authenticates the sandbox also authenticates the gateway. Otherwise:

# In your scanning workspace:
npx vercel link              # link this directory to a Vercel project
npx vercel env pull          # writes VERCEL_OIDC_TOKEN to .env.local

deepsec auto-refreshes the token when it's near expiry (via @vercel/oidc), but the underlying refresh requires .vercel/project.json in the workspace — re-run vercel env pull if refresh fails or you've moved the directory.

Verify

Run a small scan to confirm the credential works:

pnpm deepsec scan --limit 20         # cheap, no AI calls
pnpm deepsec process --limit 5       # exercises the gateway

If the second command fails with Missing AI credentials or a 401, see Troubleshooting.

How it works

deepsec expands whichever credential it finds (the API key first, the OIDC token as fallback) at startup into the four vars the agent SDKs read (ANTHROPIC_AUTH_TOKEN, OPENAI_API_KEY, ANTHROPIC_BASE_URL, OPENAI_BASE_URL), so a single credential covers both Codex (--agent codex, the default) and Claude (--agent claude).

Any of those four vars you set explicitly takes precedence over the expansion — useful for mixing direct Anthropic with gateway-routed OpenAI, etc.

Costs and credits

The AI Gateway uses pay-as-you-go pricing with zero markup on provider rates. Every Vercel team gets $5/month free credit for evaluation. Full scans on real codebases will exhaust that — top up before kicking off a long run.

Top up credits — opens the AI dashboard with the top-up modal pre-selected.
Auto top-up — set a threshold; the gateway charges automatically when the balance dips below it.
Pricing reference — model-by-model rates.

Rough budget for a process pass with Claude Opus (default settings):

Files	Approx cost
100	$25–60
500	$130–300
2,000	$500–1200

Run --limit 50 first to calibrate before a full pass. See getting-started.md for the full cost guide.

When credits run out

If process or revalidate halts because the gateway balance is exhausted (or because a direct provider key ran out), deepsec stops gracefully — no further batches launch, in-flight batches are cancelled, the file lock state is preserved. The CLI prints a remediation message with the right top-up URL.

After topping up, re-run the same command. It picks up exactly where it stopped — files already analyzed are skipped, only the unfinished ones get re-investigated.

Subscriptions (Claude Pro / ChatGPT Plus)

If claude or codex is logged in on this machine, non-sandbox runs (process, revalidate, triage) can fall back to that subscription session — no API key needed:

claude login    # for --agent claude
codex login     # for --agent codex

Subscriptions are useful for evaluating deepsec but generally do not have enough headroom for full repo scans. The Claude weekly / 5-hour and ChatGPT Plus quotas trip well before a real codebase is finished. Switch to the gateway (or a direct provider key) once you're past evaluation.

BYOK and direct providers

If you have your own Anthropic / OpenAI agreement, two options:

Through the gateway (recommended) — configure Bring Your Own Key (BYOK) at the team level. No gateway markup, with failover and observability on top.

Bypass the gateway entirely — set the explicit base URL + token pairs in .env.local:

# Anthropic direct
ANTHROPIC_AUTH_TOKEN=sk-ant-…
ANTHROPIC_BASE_URL=https://api.anthropic.com

# OpenAI direct
OPENAI_API_KEY=sk-…
# (OPENAI_BASE_URL defaults to api.openai.com — only set it for proxies)

Mix freely — gateway for Claude, direct for OpenAI, etc. The explicit values always win over the AI_GATEWAY_API_KEY expansion.

Vercel Sandbox

Only needed for deepsec sandbox process (and deepsec sandbox-all). Skip this section if you're running everything locally.

deepsec supports both auth methods the Sandbox SDK accepts. Pick whichever fits your environment — no deepsec config beyond setting the right env vars in .env.local. Reference: Sandbox authentication.

Where you're running	Use this
Local development on your machine	OIDC token
Long-running CI, external infra, server-side cron	Access token
Deployed on Vercel	OIDC (automatic, nothing to set)

Option A: OIDC token

Recommended for local development. One command pair:

# In your scanning workspace:
npx vercel link              # link this directory to a Vercel project
npx vercel env pull          # writes VERCEL_OIDC_TOKEN to .env.local

The token expires after 12 hours; re-run vercel env pull when you hit auth errors. The Vercel project you link to is just the auth scope — it can be any project on your team.

If you go this route, you don't need a separate AI Gateway API key: the same OIDC token authenticates the gateway automatically.

Option B: access token (API key)

Use when OIDC isn't viable: external CI/CD, non-Vercel hosting, jobs that need to run unattended for longer than 12 hours, or any setup where running vercel env pull interactively isn't practical. Add three env vars to .env.local:

VERCEL_TOKEN=…               # https://vercel.com/account/tokens
VERCEL_TEAM_ID=team_…        # team Settings → Team ID
VERCEL_PROJECT_ID=prj_…      # any project's Settings → General → Project ID

The Sandbox SDK reads these directly from process.env at Sandbox.create() time. References:

You can keep both sets of env vars in .env.local. The SDK prefers VERCEL_OIDC_TOKEN when present and falls back to access-token mode otherwise — handy for using OIDC locally and the access-token path in scheduled CI runs without maintaining two configs.

Try a sandbox run

pnpm deepsec sandbox process --project-id my-app --sandboxes 4

If the sandbox can't authenticate, the spawn fails with the SDK's error. Re-run vercel env pull (OIDC) or double-check the three access-token vars.

Troubleshooting

Symptom	What it means	Fix
`Missing AI credentials for --agent claude` / `codex`	No credential present on this machine.	Set `AI_GATEWAY_API_KEY=vck_…` in `.env.local`, or run `claude login` / `codex login` to use a subscription.
`401 Unauthorized` from `process` / `revalidate`	Credential present but rejected.	OIDC: re-run `vercel env pull` (token may have expired — 12 h). API key: regenerate in the dashboard. Confirm `.env.local` is in the cwd deepsec runs from.
`✘ Stopped: Vercel AI Gateway credits exhausted`	Gateway balance is $0.	Top up, then re-run the same command — it resumes from where it stopped.
`✘ Stopped: Anthropic API credits exhausted`	Direct Anthropic account out of credits.	Top up at Anthropic Console, or switch to the gateway.
`✘ Stopped: OpenAI API quota exhausted`	Direct OpenAI account out of quota / payment method declined.	Top up in the OpenAI dashboard, or switch to the gateway.
`✘ Stopped: Claude Pro/Max subscription exhausted`	Hit the weekly / 5-hour subscription cap.	Switch to AI Gateway — subscriptions don't have enough headroom for full scans.
`✘ Stopped: ChatGPT subscription exhausted`	Hit the ChatGPT Plus / Pro quota.	Same — switch to the gateway.
Sandbox spawn fails with auth error	OIDC token expired (12 h) or access-token vars wrong.	Re-run `vercel env pull` (OIDC) or double-check `VERCEL_TOKEN` / `VERCEL_TEAM_ID` / `VERCEL_PROJECT_ID`.
Findings missing cost in the log	Pricing entry missing for a non-default Codex model.	See models.md.

After any quota / credit fix

process and revalidate resume on re-run — there's no recovery flag to set, no state to reset. Files already analyzed stay analyzed; only the unfinished ones get picked up. (Want to redo finished work? Use --reinvestigate for process or --force for revalidate.)