Hosting and deployment

Vercel integration

Ahena checks that your Vercel project matches ahena.config.ts: the right environment variables in production, preview and development, your domains attached, verified and pointing at Vercel, and a healthy latest production deployment. It creates plain variables and adds domains after you approve them. It never deploys, redeploys, reads build logs or decrypts a variable, and your app is served by Vercel directly.

BetaFull Vercel docs

What Ahena inspects

Read-only: inspecting and Doctor never change anything at Vercel.

The project: framework, root directory, Node.js version, git link and production aliases.
Environment variables by key, target, type and last update. Values are never decrypted or shown.
Domains on the project, their ownership verification and whether DNS points at Vercel.
The latest production deployment's state (READY, ERROR, BUILDING) and URL.

What Ahena configures

You declare what you want in ahena.config.ts; ahena plan shows each change with its classification before anything is applied.

Change	Classification	Notes
Create a plain environment variable for the environment's target	CONFIRMATION_REQUIRED	Production included. Takes effect on the next deployment; Ahena doesn't redeploy.
Update a plain variable that belongs to that target alone	CONFIRMATION_REQUIRED	A variable shared with other targets is left alone; Doctor gives the steps.
Add a domain to the project (production or a custom environment)	CONFIRMATION_REQUIRED	DNS records are a manual step: Doctor lists the exact records.
Ask Vercel to re-check a domain's ownership	SAFE	—
Set a sensitive variable from an Ahena secret	MANUAL	Ahena never puts secret values in a plan; Doctor prints the `ahena env reveal … \| vercel env add … --sensitive` command.

Refused outright:

Deleting projects, domains or environment variables, or removing a production domain.
Changing framework, build or output settings, root directory or Node.js version.
Decrypting variables, or a secret-looking variable with a value written in ahena.config.ts.
Creating, redeploying, promoting or rolling back deployments.

Generated code: Nothing: Vercel has no generated code.

How Ahena verifies

After every write, Ahena reads Vercel back. Each change ends in one of these states, and the plan's outcome says why:

VERIFIED: Ahena read the provider back and saw the desired state. The CLI shows ✓ only for VERIFIED.
APPLIED_UNVERIFIED: The provider accepted the change, but the re-read doesn't show it yet (after bounded polling), or the re-read failed.

After apply, Ahena lists the project's variables and domains again (every page) and re-plans. Plain variables are read back and compared; encrypted and sensitive ones are confirmed by existence only, because Ahena never decrypts them.

If a request may have reached Vercel but the answer was lost, Ahena re-reads before deciding: done, safe to retry, or “check before retrying”.

What Doctor diagnoses

Key checks from ahena doctor. Each finding says why it matters, where, the impact and whether Ahena can fix it. The full list is in the Vercel docs.

Check	What it means
`vercel.token / vercel.team`	The token is valid, not flagged as leaked, and scoped to the configured team.
`vercel.project`	The project is reachable; a token for another team sees 403 or 404.
`vercel.env.<key>`	Each declared variable exists for the target, including one set only in preview but not production, or the reverse.
`vercel.domain.<name> / .dns`	Domain attached and verified, and DNS points at Vercel; otherwise the exact records.
`vercel.deployment.production`	Latest production deployment is ready; an errored one is reported with its URL, no logs.
`vercel.env.redeploy`	Variables changed after the live production deployment: redeploy to use them.

More on findings, health and continuous checks: Doctor.

Approvals

Vercel changes here are classified CONFIRMATION_REQUIRED, SAFE and MANUAL. Every change is planned and shown as a diff first. Ahena itself enforces who can approve it:

SAFE changes are applied without asking.
In production, every other change needs approval in the Ahena dashboard, signed in, by an admin.
In other environments, CONFIRMATION_REQUIRED changes are approved in the CLI; BILLABLE and DESTRUCTIVE changes always need the dashboard.
MANUAL steps are never applied by Ahena.

--yes and --allow-billable don't replace a dashboard approval. See approvals for how it works and why the browser.

Manual steps

These are MANUAL: Ahena never does them. It lists them with the exact steps when they apply.

Set each secret variable from its Ahena secret with the command Doctor prints.
Add the TXT, A or CNAME records Doctor lists at your DNS provider.
Redeploy after variables change: Vercel applies them at build time.

Credentials and permissions

Name	Secret	Notes
`VERCEL_TOKEN`	Yes	An access token scoped to the project's team, with an expiration.
`VERCEL_TEAM_ID`	No	The team id (`team_…`); leave it out for a personal account.
`VERCEL_PROJECT`	No	Project name or id, offered from the token at connect.

Least privilege

Vercel tokens have no finer permissions than an account or a team, so Ahena checks authentication and the token's scope, not individual rights. Scope the token to the one team.
A token that can read but not write shows up as a 403 when a change is applied.

Each credential Ahena stores gets its own key and is envelope-encrypted, bound to the environment. See security.

Workflow example

Connect, check, plan, then apply. Placeholders (…) stand for your own values.

VERCEL_TOKEN=… ahena connect vercel -e production --set VERCEL_TEAM_ID=team_… --set VERCEL_PROJECT=leo

Connect a team-scoped token to production.

```
ahena doctor -e production
```
Check variables, domains, DNS and the latest production deployment.
```
ahena plan -e production
```
See the variables and domains Ahena would add.
```
ahena apply -e production
```
Approve in the dashboard, signed in; Ahena applies and reads each change back.

Verification status

Beta

Available in beta. Every capability is validated by Ahena's automated provider contract and conformance tests; verification against the real service is next.

How Vercel is tested

Tested against a simulated version of the Vercel REST API (same paths, team scoping, 403 for a token from another team, pagination, variable types), not yet against the real service.
A live scenario is ready: it creates one development-only variable on a throwaway project, verifies it, and cleans it up.

The providers overview explains Ahena's testing methodology and what has been verified for every provider.

Limitations

Sensitive variables are set by you: Ahena checks they exist but can't write secret values to Vercel.
Values of encrypted and sensitive variables are never compared, only their presence.
Shared team variables, deployment protection, git settings, redirects and rewrites aren't managed.

Disconnecting

ahena disconnect vercel removes the stored token (delete it in Vercel's token settings); projects, variables, domains and deployments are untouched.