Environment Variables

Xagent is configured through environment variables, typically in a .env file. The SaaS layer inherits all core xagent variables and adds billing configuration on top.

Core Configuration

Copy the example and adjust values for your environment:

cp example.env .env

Core variables cover the database connection, model provider credentials, authentication secrets, and the sandbox. See example.env in the xagent repository for the full list.

Local Browser Use (Self-Hosted, Optional)

A self-hosted deployment can let tasks control one visible window of a browser running on the same host as the backend, through a cua-driver process. Off by default and intended for a single-tenant, non-shared host — not for a multi-tenant cloud deployment.

XAGENT_NATIVE_BROWSER_ENABLED=false          # opt in explicitly
XAGENT_NATIVE_BROWSER_APP_NAME="Google Chrome"
XAGENT_BROWSER_CUA_DRIVER_COMMAND=cua-driver
XAGENT_BROWSER_CUA_DRIVER_SOCKET=
XAGENT_BROWSER_CUA_DRIVER_TIMEOUT_SECONDS=30
XAGENT_BROWSER_CUA_DRIVER_MAX_ELEMENTS=2000

Supported browsers: Google Chrome, Google Chrome Canary, Brave, Chromium, Microsoft Edge, and Vivaldi. A task binds to one exact browser window and never switches to a different one silently.

Billing (SaaS)

The SaaS layer needs Stripe credentials and the price ids for each paid plan and interval:

STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxx
STRIPE_PRICE_STARTER_MONTHLY=
STRIPE_PRICE_STARTER_YEARLY=
STRIPE_PRICE_BUSINESS_MONTHLY=
STRIPE_PRICE_BUSINESS_YEARLY=

Plan price ids are referenced from plans.yaml using ${ENV_VAR} syntax, so the same configuration works across staging and production by swapping the environment.

Next Steps

• Docker →
• Billing →