Settings are defined with defineSettings((env) => ({ … })) in src/settings.ts. See
Settings for how they are resolved. Keys are UPPER_SNAKE_CASE, like
Django; option objects passed to adapters and classes are camelCase.
Each package adds its keys to the GhuriSettings interface through declaration merging, so
your editor knows about a key as soon as the package that reads it is installed.
npx ghuri diffsettings prints the settings that differ from the defaults.
Signs sessions, CSRF tokens, password reset tokens and signed cookies. Required unless DEBUG is true. Set with wrangler secret put or the environment.
DEBUG
boolean
false
Detailed error pages with stack traces, startup system checks. Never true in production.
ALLOWED_HOSTS
string[]
['*']
Host header values the site will serve. A leading dot matches subdomains (.example.com). Enforced by the app on every request (400). With DEBUG and [], localhost, 127.0.0.1 and [::1] are allowed.
INSTALLED_APPS
Array<AppConfigClass | AppConfig>
required
Apps in the project, in order. Order matters for ready() calls and command overrides.
The first hashes new passwords; all are accepted when checking. Hashes are upgraded on login when the first hasher changes. Pass instances to configure them: new PBKDF2PasswordHasher({ iterations: 600_000 }).
Run by createsuperuser, changepassword and validatePassword(). Built-ins: MinimumLengthValidator, CommonPasswordValidator, NumericPasswordValidator, UserAttributeSimilarityValidator.
SECRET_KEY_FALLBACKS
string[]
[]
Old secret keys still accepted for signatures, session hashes and reset tokens, for key rotation.
LOGIN_URL
string
'/accounts/login/'
Where loginRequired redirects anonymous users.
LOGIN_REDIRECT_URL
string
'/accounts/profile/'
Default redirect after login.
LOGOUT_REDIRECT_URL
string | null
null
Redirect after logout.
PASSWORD_RESET_TIMEOUT
number (seconds)
259200 (three days)
How long a password reset link stays valid.
REMOTE_USER_HEADER
string
'Remote-User'
Header read by RemoteUserMiddleware.
PBKDF2PasswordHasher produces Django-compatible pbkdf2_sha256$<iterations>$<salt>$<hash>
strings, so users imported from a Django database can log in unchanged.
Used by views that do not set authenticationClasses. The default trusts the user set by AuthenticationMiddleware and enforces CSRF like DRF’s SessionAuthentication.
DEFAULT_PERMISSION_CLASSES
[AllowAny]
Used by views that do not set permissionClasses.
DEFAULT_RENDERER_CLASSES
[JSONRenderer, BrowsableAPIRenderer]
Response formats.
DEFAULT_PARSER_CLASSES
[JSONParser, FormParser, MultiPartParser]
Request body formats.
DEFAULT_PAGINATION_CLASS
null
Pagination for list views.
PAGE_SIZE
null
Page size for the default paginator.
DEFAULT_FILTER_BACKENDS
[]
Filter backends for generic views.
DEFAULT_THROTTLE_CLASSES
[]
Throttles applied to every API view.
DEFAULT_THROTTLE_RATES
{ user: null, anon: null }
Rates by scope, e.g. { anon: '100/day', user: '1000/day' }.
THROTTLE_CACHE
'default'
CACHES alias that stores throttle history.
NUM_PROXIES
null
Proxies in front of the app, for client IP detection in throttles.
DEFAULT_CONTENT_NEGOTIATION_CLASS
DefaultContentNegotiation
Picks the renderer and parser.
DEFAULT_METADATA_CLASS
SimpleMetadata
Answers OPTIONS requests.
DEFAULT_SCHEMA_CLASS
AutoSchema
OpenAPI schema generation.
EXCEPTION_HANDLER
exceptionHandler
Turns exceptions into API responses.
UNAUTHENTICATED_USER / UNAUTHENTICATED_TOKEN
() => new AnonymousUser() / null
request.user / request.auth when nobody authenticated.
SEARCH_PARAM
'search'
Query parameter read by SearchFilter.
ORDERING_PARAM
'ordering'
Query parameter read by OrderingFilter.
NON_FIELD_ERRORS_KEY
'nonFieldErrors'
Key for errors not tied to a field (DRF uses 'non_field_errors'; set that for DRF-compatible clients).
Authentication classes (SessionAuthentication, TokenAuthentication, JWTAuthentication,
BasicAuthentication, RemoteUserAuthentication) are imported from @ghuri/auth/rest. See
REST framework.
Where the admin loads htmx from (a self-hosted copy for strict CSPs or offline intranets; false disables it), plus extra stylesheets and deferred scripts for every admin page.
Site titles are set on the AdminSite (admin.site.siteHeader = 'My blog'), not in settings.
See Admin reference.
Credentials and options per provider (anthropic, openai, workers-ai, ghuri-ai, …). headers is an object or a function of the run. See Provider headers and gateways.
MAX_STEPS
number
10
Maximum tool-call steps per agent run.
AUTHENTICATION_CLASSES
AuthenticationClass[]
REST_FRAMEWORK.DEFAULT_AUTHENTICATION_CLASSES
Authentication for the chat and MCP endpoints.
PERMISSION_CLASSES
PermissionClass[]
[IsAuthenticated]
Permissions for agents that do not set permissionClasses.
QUEUE_BINDING
string
'AGENTS_QUEUE'
Queue producer binding used by agent.enqueue(). See Background tasks.
TRACE_RUNS
boolean | { messages?: boolean }
false
Save a Run row per agent run (model, usage, tool calls, outcome, duration); { messages: true } also stores prompts and answers. See Run traces.
STRICT_TOOL_INPUT
boolean
false
Check tool arguments against their schemas before tools run, for agents that don’t set strictToolInput. See Shaping tools.
CONVERSATION_MODEL
string
'agents.Conversation'
The conversation model (swappable, like AUTH_USER_MODEL), e.g. a tenant-scoped one. Set it before the first migrate. See Your own conversation model.
Largest multipart body in bytes, files included; larger → 413, checked against Content-Length before reading.
UPLOAD_MAX_FILES
number
10
Most files in one multipart request; more → 413.
UPLOAD_CSRF_PREVENTION
boolean
true
Anonymous multipart requests must send a preflight-forcing header (GraphQL-Require-Preflight, Apollo-Require-Preflight, X-Apollo-Operation-Name, the CSRF header or Authorization).
GraphQLView.asView({ … }) options override these per view. See GraphQL.
const pageSize = setting('PAGE_SIZE', 20)// with a fallback
Both need a Ghuri context: inside a request, a cron or queue handler, a command, or a test that
called app.setup(env). With only a Hono context at hand, settingsFor(c) returns the request’s
settings or undefined. Custom keys are allowed; declare them for type checking: