Environment Variables

`.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:

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.

Getting Started

CLI

Config

File-system layout

Functions

Protocols

Environment Variables

`.env` Files

Common Variables

Using in Config

Testing Environment

Built-in Environment Variables

Build-Time Resolution

​.env Files

​Common Variables

​Using in Config

​Testing Environment

​Built-in Environment Variables

​Build-Time Resolution

`.env` Files

Common Variables

Using in Config

Testing Environment

Built-in Environment Variables

Build-Time Resolution