Deploying

Vercel

aixyz has first-class Vercel support using the Build Output API v3.

bun run build
vercel deploy

The build automatically detects the Vercel environment via VERCEL=1 and outputs a Vercel serverless function using Bun Runtime. The agent URL is auto-detected from Vercel environment variables.

`vercel.json`

Every aixyz project includes a vercel.json:

vercel.json

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": null,
  "buildCommand": "bun run build",
  "bunVersion": "1.x"
}

No need to pass --vercel — the flag is automatically detected during Vercel builds. Set OPENAI_API_KEY and any payment environment variables in the Vercel dashboard under Settings → Environment Variables.

Standalone (Bun Runtime)

For direct deployment on Bun-compatible hosts (DigitalOcean, Railway, Fly.io, etc.):

aixyz build
bun .aixyz/output/server.js

The build outputs a single bundled file at .aixyz/output/server.js.

Environment Variables

Set these before running:

export PORT=3000
export OPENAI_API_KEY=sk-...
bun .aixyz/output/server.js

Docker

Using the standalone build:

Dockerfile

FROM oven/bun:1.3.9
WORKDIR /app
COPY . .
RUN bun install
RUN bun run build
CMD ["bun", ".aixyz/output/server.js"]

Build and run:

docker build -t my-agent .
docker run -p 3000:3000 \
  -e OPENAI_API_KEY=sk-... \
  -e PORT=3000 \
  my-agent

Never bake API keys into Docker images. Pass them as environment variables at runtime.

Set the url field in aixyz.config.ts manually for Docker deployments since Vercel environment variables won’t be available.

Build Output Formats

Format	Flag	Output Path	Description
Standalone	(default)	`.aixyz/output/server.js`	Single-file bundle, run with `bun`
Vercel	`VERCEL=1` or `--output vercel`	`.vercel/output/`	Build Output API v3 for serverless
Executable	`--output executable`	`.aixyz/output/server`	Self-contained binary, no Bun runtime required

Verifying Your Deployment

After deploying, verify your agent is accessible:

# Check the agent card
curl https://your-agent.example.com/.well-known/agent-card.json

# Test the A2A endpoint
curl -X POST https://your-agent.example.com/agent \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tasks/send",
    "id": "1",
    "params": {
      "id": "task-1",
      "message": {
        "role": "user",
        "parts": [{"type": "text", "text": "Hello"}]
      }
    }
  }'

Getting Started

CLI

Config

File-system layout

Functions

Protocols

Vercel

`vercel.json`

Standalone (Bun Runtime)

Environment Variables

Docker

Build Output Formats

Verifying Your Deployment

​Vercel

​vercel.json

​Standalone (Bun Runtime)

​Environment Variables

​Docker

​Build Output Formats

​Verifying Your Deployment

Vercel

`vercel.json`

Standalone (Bun Runtime)

Environment Variables

Docker

Build Output Formats

Verifying Your Deployment