> ## Documentation Index
> Fetch the complete documentation index at: https://artifacts.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Environment variables for web, API, auth, storage, billing, CLI, and observability.

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.

<Tip>
  Copy `.env.example` to `.env` to start from working local defaults — see the [quickstart](/getting-started/quickstart).
</Tip>

## 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:

```bash theme={"theme":"github-dark"}
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:

```bash theme={"theme":"github-dark"}
bun run db:migrate
```

Generate migrations after schema changes:

```bash theme={"theme":"github-dark"}
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:

```text theme={"theme":"github-dark"}
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`:

```text theme={"theme":"github-dark"}
~/.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.