.env Files
aixyz loads environment variables from .env files in the following order (later files take precedence):
.env — Shared defaults.env.local — Local overrides (gitignored).env.$(NODE_ENV) — e.g., .env.production.env.$(NODE_ENV).local — e.g., .env.production.local
This matches the loading order used by Next.js.
.env.local is always gitignored. Use it for API keys and secrets during development.
Common Variables
| Variable | Description |
|---|
OPENAI_API_KEY | OpenAI API key |
X402_PAY_TO | Default payment recipient address |
X402_NETWORK | Default payment network |
X402_FACILITATOR_URL | Custom x402 facilitator URL |
CDP_API_KEY_ID | Coinbase CDP key ID (switches to Coinbase facilitator) |
CDP_API_KEY_SECRET | Coinbase CDP key secret |
STRIPE_SECRET_KEY | Experimental Stripe adapter |
STRIPE_PRICE_CENTS | Stripe price in cents (default: 100) |
Using in Config
Reference environment variables directly in aixyz.config.ts:
import type { AixyzConfig } from "aixyz/config";
const config: AixyzConfig = {
name: "My Agent",
description: "...",
version: "0.1.0",
x402: {
payTo: process.env.X402_PAY_TO!,
network: process.env.X402_NETWORK!,
},
skills: [],
};
export default config;
Testing Environment
For tests, loadEnv from aixyz/test loads .env.test.local (where your OPENAI_API_KEY lives for tests). .env.local is ignored during testing:
import { loadEnv } from "aixyz/test";
describe("tests", () => {
loadEnv();
// process.env.OPENAI_API_KEY is now available
});
Built-in Environment Variables
The CLI automatically sets these environment variables based on the command:
| Variable | aixyz dev | aixyz build | Description |
|---|
NODE_ENV | "development" | "production" | Standard Node.js environment indicator, for compatibility with node packages |
AIXYZ_ENV | "development" | "production" | aixyz-specific environment indicator, mirrors NODE_ENV |
Build-Time Resolution
Environment variables referenced in aixyz.config.ts are resolved and baked into the bundle at build time. The config file itself is not included in the output — only the resolved values.
