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

# Self-Hosting Configuration Reference

> Complete environment variable reference for self-hosted AppBlips. Configure your LLM provider, rate limits, and AI mode for user-generated apps.

All configuration for a self-hosted AppBlips instance lives in a single `.env` file in the project root. Copy `.env.example` to `.env` to get started, then fill in the values for your setup. Variables fall into five groups: the required LLM provider for the builder, optional LLM tuning, optional rate limiting, the AI mode for apps your users generate, and the relay provider settings used when you choose to fund app AI yourself.

## Required: LLM Provider

These three variables power the AppBlips builder — the AI that turns your descriptions into working apps. All three must be set before AppBlips will start successfully.

<ParamField body="APPBLIPS_LLM_BASE_URL" type="string" required>
  The base URL of an OpenAI-compatible chat completions API. Use `https://api.openai.com/v1` for OpenAI, or substitute any compatible provider's endpoint.
</ParamField>

<ParamField body="APPBLIPS_LLM_API_KEY" type="string" required>
  Your API key for the builder LLM provider. This value is read server-side only and is never exposed to the browser.
</ParamField>

<ParamField body="APPBLIPS_LLM_MODEL" type="string" required>
  The model name to use for building apps — for example, `gpt-4o`. The model must be available at the endpoint you specified in `APPBLIPS_LLM_BASE_URL`.
</ParamField>

## Optional: LLM Tuning

These variables let you constrain or adjust the builder's AI responses. Leave them blank to use provider defaults (except temperature, which defaults to `0.2`).

<ParamField body="APPBLIPS_LLM_MAX_TOKENS" type="number">
  Maximum number of tokens the builder LLM may return in a single response. Useful for controlling costs on providers that bill per token.
</ParamField>

<ParamField body="APPBLIPS_LLM_TEMPERATURE" type="number">
  Sampling temperature for builder responses. Lower values produce more predictable output; higher values produce more varied results. Defaults to `0.2`. Users can also adjust reasoning effort per-request in the in-app Settings modal — that setting is independent of this one.
</ParamField>

## Optional: Rate Limiting

AppBlips includes a built-in rate limiter on `/api/chat` to help prevent runaway usage from spending your AI budget unexpectedly.

<ParamField body="APPBLIPS_CHAT_RATE_LIMIT_MAX" type="number">
  Maximum number of requests allowed per window per user. Defaults to `60`.
</ParamField>

<ParamField body="APPBLIPS_CHAT_RATE_LIMIT_WINDOW_SECONDS" type="number">
  Length of the rate-limit window in seconds. Defaults to `300` (five minutes).
</ParamField>

<Note>
  Rate limit counts are tracked in memory within a single server process. Restarting the server resets all counters. Treat this as a speed bump against accidental overuse, not a hard billing cap.
</Note>

## Generated-App AI Mode

When users build an app that uses `blip.ai.text(...)`, that app needs its own AI connection. These two variables control how that connection works.

<ParamField body="APPBLIPS_GENERATED_AI_MODE" type="string">
  Controls how generated apps get access to AI. Accepts one of two values:

  * `byok` *(default)* — each person using a finished app enters their own provider endpoint, model, and API key directly in that app. Your server is never involved.
  * `relay` — your server proxies all generated-app AI requests using the `APPBLIPS_APP_LLM_*` variables below. You pay for generated-app AI on behalf of your users.
</ParamField>

<ParamField body="APPBLIPS_APP_AI_RELAY_URL" type="string">
  The URL embedded in generated apps when pointing them at the relay. Defaults to `/api/app-ai/chat`, which works for apps served from the same origin as AppBlips. Set an absolute `https://` URL if you host exported apps on a different domain.
</ParamField>

<Warning>
  `APPBLIPS_GENERATED_AI_MODE` and `APPBLIPS_APP_AI_RELAY_URL` are baked into the client bundle at build time, not read at runtime. If you change either value, you must rebuild the image — a plain container restart will not pick up the new values. Run `docker compose up --build` to apply the change.
</Warning>

## Relay Provider (when `APPBLIPS_GENERATED_AI_MODE=relay`)

When you set `APPBLIPS_GENERATED_AI_MODE=relay`, configure a separate LLM provider for generated-app AI here. These credentials are kept server-side and are never sent to the browser.

<ParamField body="APPBLIPS_APP_LLM_BASE_URL" type="string">
  Base URL of the OpenAI-compatible API to use for relay requests. Example: `https://api.openai.com/v1`.
</ParamField>

<ParamField body="APPBLIPS_APP_LLM_API_KEY" type="string">
  API key for the relay LLM provider. Kept on the server; never exposed to generated apps or their users.
</ParamField>

<ParamField body="APPBLIPS_APP_LLM_MODEL" type="string">
  Model name to use for relay requests. Example: `gpt-4o`.
</ParamField>

<ParamField body="APPBLIPS_APP_LLM_MAX_TOKENS" type="number">
  Maximum tokens per relay response. Leave blank to use the provider default.
</ParamField>

<ParamField body="APPBLIPS_APP_LLM_TEMPERATURE" type="number">
  Sampling temperature for relay responses. Defaults to `0.2`.
</ParamField>

<ParamField body="APPBLIPS_APP_LLM_REASONING_EFFORT" type="string">
  Operator-set reasoning effort for relay requests. Accepted values depend on your provider and model — for example, `none`, `low`, `medium`, or `high`. Defaults to `none`. This is a server-side operator setting; the per-user reasoning effort control in the app's Settings modal does not apply to relay calls.
</ParamField>

<ParamField body="APPBLIPS_APP_AI_ALLOWED_ORIGINS" type="string">
  Comma-separated list of exact origins permitted to call the relay from a different domain. For example: `https://myapp.example.com,https://other.example.com`. Same-origin callers are always allowed. Only add `null` if you intentionally want apps opened as local `file://` pages to reach your relay.
</ParamField>

<ParamField body="APPBLIPS_APP_AI_RATE_LIMIT_MAX" type="number">
  Per-IP rate limit on relay requests. Defaults to `20` requests per window.
</ParamField>

<ParamField body="APPBLIPS_APP_AI_RATE_LIMIT_WINDOW_SECONDS" type="number">
  Window length in seconds for the relay rate limit. Defaults to `60`.
</ParamField>

## Hosting Mode

<ParamField body="SELF_HOSTED_MODE" type="boolean">
  Controls whether AppBlips runs in self-hosted mode. Defaults to `true`, which enables single-user local operation with no sign-in, no cloud sync, and no deploy-to-public-URL feature. Set to `false` only if you are running the full hosted-mode stack — most self-hosters should leave this unset or set to `true`.
</ParamField>

## Complete `.env` Example

The following shows a minimal configuration (builder only, BYOK mode) and a full relay configuration side by side.

<CodeGroup>
  ```bash Minimal (BYOK) theme={null}
  # Builder — required
  APPBLIPS_LLM_BASE_URL=https://api.openai.com/v1
  APPBLIPS_LLM_API_KEY=sk-...
  APPBLIPS_LLM_MODEL=gpt-4o

  # Optional tuning
  APPBLIPS_LLM_TEMPERATURE=0.2
  APPBLIPS_LLM_MAX_TOKENS=

  # Optional rate limiting
  APPBLIPS_CHAT_RATE_LIMIT_MAX=60
  APPBLIPS_CHAT_RATE_LIMIT_WINDOW_SECONDS=300

  # Generated-app AI: users supply their own keys (default)
  APPBLIPS_GENERATED_AI_MODE=byok
  ```

  ```bash Relay Mode theme={null}
  # Builder — required
  APPBLIPS_LLM_BASE_URL=https://api.openai.com/v1
  APPBLIPS_LLM_API_KEY=sk-...
  APPBLIPS_LLM_MODEL=gpt-4o

  # Generated-app AI: server pays via relay
  APPBLIPS_GENERATED_AI_MODE=relay
  APPBLIPS_APP_AI_RELAY_URL=/api/app-ai/chat

  # Relay provider
  APPBLIPS_APP_LLM_BASE_URL=https://api.openai.com/v1
  APPBLIPS_APP_LLM_API_KEY=sk-...
  APPBLIPS_APP_LLM_MODEL=gpt-4o
  APPBLIPS_APP_LLM_REASONING_EFFORT=none

  # Relay access controls
  APPBLIPS_APP_AI_ALLOWED_ORIGINS=https://myapp.example.com
  APPBLIPS_APP_AI_RATE_LIMIT_MAX=20
  APPBLIPS_APP_AI_RATE_LIMIT_WINDOW_SECONDS=60
  ```
</CodeGroup>