Configuration

Every environment variable Artifacts reads, grouped by area. During local development these come from the monorepo .env file; in production, provide the same variables through your platform’s secret store.

Copy .env.example to .env to start from working local defaults — see the quickstart.

Core URLs

Variable	Used by	Purpose
`PUBLIC_APP_URL`	API, web	Browser-visible app origin
`NEXT_PUBLIC_APP_URL`	Web	Optional public app URL exposed to browser code
`NEXT_PUBLIC_DOCS_URL`	Web	Browser-visible docs URL; defaults to `https://docs.hostartifacts.dev`
`MINTLIFY_DOCS_URL`	Web	Mintlify origin that Next.js proxies from `/docs`
`INTERNAL_API_URL`	Web	Hono API origin used by Next.js rewrites
`BETTER_AUTH_URL`	Auth	Canonical auth base URL
`BETTER_AUTH_TRUSTED_ORIGINS`	Auth	Extra comma-separated auth origins

Local defaults:

PUBLIC_APP_URL="http://localhost:3000"
NEXT_PUBLIC_APP_URL="http://localhost:3000"
NEXT_PUBLIC_DOCS_URL="https://docs.hostartifacts.dev"
MINTLIFY_DOCS_URL="http://127.0.0.1:3002"
BETTER_AUTH_URL="http://localhost:3000"
INTERNAL_API_URL="http://127.0.0.1:3001"

Database

Variable	Purpose
`DATABASE_URL`	Postgres connection string for Drizzle and Better Auth

Run migrations with:

bun run db:migrate

Generate migrations after schema changes:

bun run db:generate

Authentication

Variable	Purpose
`BETTER_AUTH_SECRET`	Better Auth signing secret
`GOOGLE_CLIENT_ID`	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	Google OAuth client secret

For MCP OAuth, BETTER_AUTH_URL and PUBLIC_APP_URL should match the origin MCP clients can open in a browser.

Storage

Artifacts uses S3-compatible storage.

Variable	Purpose
`S3_ENDPOINT`	S3-compatible endpoint, such as R2
`S3_BUCKET`	Bucket name
`S3_REGION`	Storage region
`S3_ACCESS_KEY_ID`	Access key
`S3_SECRET_ACCESS_KEY`	Secret key

Source objects use keys shaped like:

users/{ownerUserId}/artifacts/{artifactId}/versions/{versionNumber}/source-{attemptId}

Billing

Billing uses Dodo Payments.

Variable	Purpose
`DODO_PAYMENTS_API_KEY`	Dodo API key
`DODO_PAYMENTS_WEBHOOK_SECRET`	Webhook signature secret
`DODO_BUILDER_PRODUCT_ID`	Product ID for the Pro plan
`DODO_STUDIO_PRODUCT_ID`	Product ID for the Team plan
`ENABLE_BILLING_CRON`	Set to `true` on the API service only (never web) to record daily storage usage. A Postgres advisory lock keeps it safe across multiple API replicas.
`BILLING_CRON_INTERVAL_MS`	Optional scheduler interval override for dev/test
`BILLING_CRON_SECRET`	Bearer secret for internal storage snapshot route

Billing meters:

Meter	Unit
`artifact.storage_gb_days`	GB-days
`artifact.delivery_gb`	GB
`artifact.version_write`	writes

CLI

Variable	Purpose
`AGENT_ARTIFACTS_BASE_URL`	API base URL
`AGENT_ARTIFACTS_WEB_URL`	Web URL for browser login
`AGENT_ARTIFACTS_TOKEN`	Bearer token
`AGENT_ARTIFACTS_FORMAT`	`json` or `text`
`AGENT_ARTIFACTS_NO_INPUT`	Set to `1` for non-interactive mode
`AGENT_ARTIFACTS_DEBUG`	Set to `1` for stack traces

Credentials from browser login are stored as a single file with mode 0600:

~/.config/agent-artifacts/credentials.json

This file holds the bearer token plus the resolved service URLs, so the CLI stays signed in across runs without an OS keyring or D-Bus session. Override the location with AGENT_ARTIFACTS_CONFIG_DIR. Run artifacts status to inspect the current auth state without a network call, or artifacts logout to delete the file.

Observability

Variable	Used by	Purpose
`BETTER_STACK_SOURCE_TOKEN`	API	Server-side API logs
`BETTER_STACK_INGESTING_URL`	API	API log ingest host
`BETTER_STACK_WEB_SOURCE_TOKEN`	Web server	Next.js server-side logs
`NEXT_PUBLIC_BETTER_STACK_SOURCE_TOKEN`	Web browser	Browser logs through proxy
`NEXT_PUBLIC_BETTER_STACK_INGESTING_URL`	Web browser	Browser ingest host and CSP connect source
`LOG_IP_SALT`	API	Salt for hashed client IPs
`TRUST_PROXY`	API	Enable trusted proxy client IP extraction

Production Notes

Set TRUST_PROXY=true only behind a trusted reverse proxy.
Configure exactly one API instance or external scheduler to record billing storage snapshots.
Keep auth, Dodo, S3, and API key secrets out of source control.
Ensure PUBLIC_APP_URL, BETTER_AUTH_URL, and OAuth redirect URLs all agree.

Interfaces

Operations

Core URLs

Database

Authentication

Storage

Billing

CLI

Observability

Production Notes

​Core URLs

​Database

​Authentication

​Storage

​Billing

​CLI

​Observability

​Production Notes

Core URLs

Database

Authentication

Storage

Billing

CLI

Observability

Production Notes