Simple. Fast. Human.

Appearance

Environment Variables ​

⚠️ BREAKING CHANGE — Tina4 v3.12.0

Every framework env var now requires the TINA4_ prefix. The legacy un-prefixed names (DATABASE_URL, SECRET, SMTP_HOST, HOST_NAME, etc.) no longer work. Setting them at startup makes the framework refuse to boot with a list of renames.

Run tina4 env --migrate to rewrite your existing .env automatically, or rename manually using the table below. The runtime guard prints the same mapping if it detects legacy names.

Conventional names stay un-prefixed: PORT, HOST, NODE_ENV, RACK_ENV, RUBY_ENV, ENVIRONMENT. These are runtime/PaaS conventions, not framework config.

Tina4 Python is configured through environment variables, read from .env at the project root. Every variable has a sensible default — most projects set three or four values and leave the rest alone.

This chapter lists every variable the Python framework reads, grouped by subsystem. Start with the minimum-config examples at the end, then come back here when you need to tune something specific.

Core Server ​

VariableDefaultDescription
HOST0.0.0.0Bind address. 0.0.0.0 listens on every interface. 127.0.0.1 restricts to localhost.
TINA4_HOST(inherits HOST)Explicit Tina4-specific bind address override. Takes precedence over HOST when both are set.
PORT7146HTTP server port. The Rust CLI prefers TINA4_PORT but falls back to PORT.
TINA4_PORT(inherits PORT)Explicit Tina4-specific port override. Takes precedence over PORT when both are set.
TINA4_HOST_NAMElocalhost:7146Fully-qualified host used in generated absolute URLs (Swagger, OAuth redirects, emails).
TINA4_DEBUGfalseMaster debug toggle. Enables Swagger UI, dev dashboard, live reload, template dump filter, error overlay. Never set to true in production.
TINA4_ENVdevelopmentRuntime environment label. Values like development, staging, production control dev-only features.
TINA4_ENV_FILE.envAlternative .env path. Read at boot before any other framework config — point at .env.staging or .env.production to switch the whole config tree.
TINA4_SUPPRESSfalseSuppresses the framework startup banner. Useful in CI runs or systemd units where stdout is parsed by another process.
TINA4_HEALTH_PATH/__healthURL for the built-in liveness/readiness endpoint. The legacy /health path is kept as an alias.
TINA4_NO_BROWSERfalseStops tina4 serve from opening your browser on every restart. Recommended during active development.
TINA4_OPEN_BROWSERtrueAlternative flag — set to false to prevent the browser opening on start.
TINA4_NO_RELOADfalseDisables the dev hot-reload signal from the Rust CLI. Use when you want a stable server for debugging.
TINA4_DEV_POLL_INTERVAL1.0Seconds between dev-mode mtime polls. Lower for faster reload, higher to reduce CPU.
TINA4_PUBLIC_DIRsrc/publicDirectory served as static files under /.

Secrets and Authentication ​

VariableDefaultDescription
TINA4_SECRETtina4-default-secretJWT signing secret. Must be long, random, and unique per environment. Never commit.
TINA4_TOKEN_LIMIT60JWT token lifetime in minutes.
TINA4_TOKEN_EXPIRES_IN(inherits TOKEN_LIMIT)Alias for TINA4_TOKEN_LIMIT.
TINA4_API_KEY(empty)Static API key used by Auth.validate_api_key() as a fallback to JWT.
TINA4_API_KEY(empty)Legacy alias for TINA4_API_KEY.

Database ​

VariableDefaultDescription
TINA4_DATABASE_URLsqlite:///data/app.dbConnection URL. Scheme selects the driver: sqlite, postgres, mysql, firebird.
TINA4_DATABASE_USERNAME(empty)Overrides the username embedded in TINA4_DATABASE_URL.
TINA4_DATABASE_PASSWORD(empty)Overrides the password embedded in TINA4_DATABASE_URL.
TINA4_DATABASE_FIREBIRD_PATH(empty)Overrides the database path/alias parsed from TINA4_DATABASE_URL for Firebird. Useful for Windows backslash paths and split-config setups.
TINA4_DB_CACHEfalseEnables in-memory query-result caching for read queries.
TINA4_DB_CACHE_TTL60Query cache TTL in seconds when TINA4_DB_CACHE=true.
TINA4_DB_POOL0Default pool size for Database(url) when the caller doesn't pass pool= explicitly. 0 disables pooling and uses a single connection. Set to a positive integer (e.g. 4) to enable round-robin connection pooling.
TINA4_ORM_PLURAL_TABLE_NAMEStrueWhen true, the ORM pluralises class names into table names (User → users). Set false to keep them singular.

CORS ​

VariableDefaultDescription
TINA4_CORS_ORIGINS*Comma-separated allowed origins. Lock down to real domains in production.
TINA4_CORS_MAX_AGE600Preflight cache lifetime in seconds.

Routing ​

VariableDefaultDescription
TINA4_TRAILING_SLASH_REDIRECTfalseWhen truthy, requests to /foo/ are 301-redirected to /foo so search engines and clients only see one canonical URL per route. The root / is exempt.

Security Headers ​

VariableDefaultDescription
TINA4_CSPdefault-src 'self'Content-Security-Policy header.
TINA4_CSRFtrueCSRF token validation on POST/PUT/PATCH/DELETE.
TINA4_HSTS(empty/off)Strict-Transport-Security max-age in seconds. Set 31536000 in production with HTTPS.
TINA4_FRAME_OPTIONSDENYX-Frame-Options header.
TINA4_REFERRER_POLICYstrict-origin-when-cross-originReferrer-Policy header.

Rate Limiting ​

VariableDefaultDescription
TINA4_RATE_LIMIT100Maximum requests per window per IP. Set 0 to disable.
TINA4_RATE_WINDOW60Rate-limit window in seconds.

Sessions ​

VariableDefaultDescription
TINA4_SESSION_BACKENDfileStorage backend. Options: file, redis, valkey, mongo, database.
TINA4_SESSION_TTL1800Session expiry in seconds (30 minutes).
TINA4_SESSION_SAMESITELaxSameSite cookie attribute. Options: Strict, Lax, None.
TINA4_SESSION_PATHdata/sessionsFilesystem path for the file backend.
TINA4_SESSION_NAMEtina4_sessionName of the session cookie sent to the browser.
TINA4_SESSION_HTTPONLYtrueSets the HttpOnly cookie attribute so JavaScript on the page cannot read the session ID.
TINA4_SESSION_SECUREfalseSets the Secure cookie attribute so the session cookie is only sent over HTTPS. Turn on in production.

Redis/Valkey session backend ​

VariableDefaultDescription
TINA4_SESSION_REDIS_HOSTlocalhostRedis host.
TINA4_SESSION_REDIS_PORT6379Redis port.
TINA4_SESSION_REDIS_PASSWORD(none)Redis auth password.
TINA4_SESSION_REDIS_DB0Redis database number.
TINA4_SESSION_VALKEY_HOSTlocalhostValkey host.
TINA4_SESSION_VALKEY_PORT6379Valkey port.
TINA4_SESSION_VALKEY_PASSWORD(none)Valkey auth password.
TINA4_SESSION_VALKEY_DB0Valkey database number.

MongoDB session backend ​

VariableDefaultDescription
TINA4_SESSION_MONGO_URLmongodb://localhost:27017MongoDB connection string.
TINA4_SESSION_MONGO_DBtina4MongoDB database name.
TINA4_SESSION_MONGO_COLLECTIONsessionsMongoDB collection name.

Templates ​

VariableDefaultDescription
TINA4_TEMPLATE_CACHE_TTL0Frond template compile-cache TTL in seconds. 0 keeps compiled templates in memory permanently — set to a positive value if you want the engine to recompile after N seconds (rarely needed; tina4 serve invalidates the cache automatically on file change).

Cache ​

VariableDefaultDescription
TINA4_CACHE_BACKENDmemoryResponse cache backend. Options: memory, file, redis.
TINA4_CACHE_DIRdata/cacheCache directory for the file backend.
TINA4_CACHE_TTL60Default cache TTL in seconds.
TINA4_CACHE_MAX_ENTRIES1000Maximum cache entries. Oldest entries evicted first.
TINA4_CACHE_URLredis://localhost:6379Connection URL for remote cache backends.

Queues ​

VariableDefaultDescription
TINA4_QUEUE_BACKENDliteQueue backend. Options: lite (file-based), kafka, rabbitmq, mongo, database.
TINA4_QUEUE_PATHdata/queueFilesystem path for the lite backend.
TINA4_QUEUE_URL(none)Connection URL for remote backends.

Kafka queue backend ​

VariableDefaultDescription
TINA4_KAFKA_BROKERSlocalhost:9092Comma-separated broker list.
TINA4_KAFKA_GROUP_IDtina4_consumer_groupKafka consumer group ID.

RabbitMQ queue backend ​

VariableDefaultDescription
TINA4_RABBITMQ_HOSTlocalhostRabbitMQ host.
TINA4_RABBITMQ_PORT5672RabbitMQ port.
TINA4_RABBITMQ_USERNAMEguestRabbitMQ username.
TINA4_RABBITMQ_PASSWORDguestRabbitMQ password.
TINA4_RABBITMQ_VHOST/RabbitMQ virtual host.

MongoDB queue backend ​

VariableDefaultDescription
TINA4_MONGO_URI(none)Full MongoDB connection string. Overrides host/port when set.
TINA4_MONGO_HOSTlocalhostMongoDB host.
TINA4_MONGO_PORT27017MongoDB port.
TINA4_MONGO_USERNAME(none)MongoDB username.
TINA4_MONGO_PASSWORD(none)MongoDB password.
TINA4_MONGO_DBtina4MongoDB database name.
TINA4_MONGO_COLLECTIONtina4_queueMongoDB collection name for jobs.

WebSocket ​

VariableDefaultDescription
TINA4_WS_BACKPLANE(none)Backplane type. Set redis for multi-instance broadcasts.
TINA4_WS_MAX_CONNECTIONS1000Maximum concurrent WebSocket connections.
TINA4_WS_MAX_FRAME_SIZE65536Maximum WebSocket frame size in bytes.

Email ​

VariableDefaultDescription
TINA4_MAIL_HOST(none)SMTP server hostname.
TINA4_MAIL_PORT587SMTP server port.
TINA4_MAIL_USERNAME(none)SMTP authentication username.
TINA4_MAIL_PASSWORD(none)SMTP authentication password.
TINA4_MAIL_FROM(none)Default sender email address.
TINA4_MAIL_FROM_NAME(none)Default sender display name.
TINA4_MAIL_ENCRYPTIONtlsConnection encryption. Options: tls, ssl, none.
TINA4_MAIL_IMAP_HOST(none)IMAP server for inbound mail.
TINA4_MAIL_IMAP_PORT993IMAP server port.
TINA4_MAIL_IMAP_ENCRYPTIONtlsIMAP transport encryption. Options: tls, starttls, none. Invalid values fall back to tls so a typo can't accidentally disable encryption.
TINA4_MAILBOX_DIRdata/mailboxDev mailbox directory. All outbound mail lands here when TINA4_DEBUG=true.

TINA4_MAIL_HOST, TINA4_MAIL_PORT, TINA4_MAIL_USERNAME, TINA4_MAIL_PASSWORD, TINA4_MAIL_FROM, TINA4_MAIL_FROM_NAME, TINA4_MAIL_IMAP_HOST, TINA4_MAIL_IMAP_PORT are accepted as legacy aliases. New projects should use the TINA4_MAIL_* names.

Logging ​

Logs default to stdout in text format. Set TINA4_LOG_OUTPUT=file plus TINA4_LOG_FILE=app.log to write to disk; the framework rotates at TINA4_LOG_ROTATE_SIZE bytes and keeps TINA4_LOG_ROTATE_KEEP backups (app.log.1 … app.log.N). Switch TINA4_LOG_FORMAT=json for one structured record per line — perfect for shipping to Loki, Datadog, or any JSON-aware log aggregator.

VariableDefaultDescription
TINA4_LOG_LEVELERRORMinimum log level written to files. Options: ALL, DEBUG, INFO, WARNING, ERROR.
TINA4_LOG_FILE(empty — stdout only)Path to a log file. Empty leaves logs on stdout. Relative paths are resolved against TINA4_LOG_DIR; absolute paths are used verbatim.
TINA4_LOG_DIRlogsDirectory for log files. Joined with TINA4_LOG_FILE when the latter is a relative path.
TINA4_LOG_FORMATtextOutput format. text writes the human-readable [INFO ] message form; json writes one structured JSON record per line.
TINA4_LOG_OUTPUTstdoutWhere logs go. Options: stdout, file, both.
TINA4_LOG_CRITICALfalseEnables the Log.critical(...) level above error. When off, calls to Log.critical() are silent no-ops.
TINA4_LOG_ROTATE_SIZE10485760Bytes per file before rotation (default 10 MB). 0 disables rotation entirely.
TINA4_LOG_ROTATE_KEEP5Number of rotated files to keep (app.log.1 … app.log.N). Older files are deleted on the next rotation.
TINA4_LOG_MAX_SIZE10485760Legacy alias for TINA4_LOG_ROTATE_SIZE. Per-file log size limit in bytes (10 MB). Rotated when exceeded.
TINA4_LOG_KEEP5Legacy alias for TINA4_LOG_ROTATE_KEEP. Number of rotated log files to retain.

Uploads ​

VariableDefaultDescription
TINA4_MAX_UPLOAD_SIZE10485760Maximum multipart upload size in bytes (10 MB).

Localisation ​

VariableDefaultDescription
TINA4_LOCALEenDefault locale for the I18n module.
TINA4_LOCALE_DIRsrc/localeDirectory containing locale JSON files.

Services (background tasks) ​

VariableDefaultDescription
TINA4_SERVICE_DIRsrc/servicesDirectory scanned for service classes.

AI and MCP Tooling ​

The dashboard AI chat and the framework's RAG-based code search both default to a local qwen2.5-coder model served via Ollama. Nothing leaves your machine unless you point TINA4_AI_URL at a remote endpoint.

VariableDefaultDescription
TINA4_AI_URLhttp://localhost:11434OpenAI-compatible HTTP endpoint for the chat/completion model. Ollama by default; can point at any compatible provider (vLLM, LM Studio, an OpenAI proxy).
TINA4_AI_MODELqwen2.5-coderModel identifier the endpoint should serve.
TINA4_RAG_URL(inherits TINA4_AI_URL)Embedding endpoint for the framework RAG index. Override only if embeddings live on a different host.
TINA4_AI_MODELnomic-embed-textEmbedding model used to index tina4_python/ and src/.
TINA4_NO_AI_PORTfalseDisables the MCP port listener in dev mode.
TINA4_MCP_REMOTEfalseAllow the MCP server to bind on non-localhost interfaces. Never enable in production.
TINA4_OVERRIDE_CLIENTfalseAllow the framework to start without the Rust CLI (tina4 serve). Used in Docker images and CI runners; bypasses SCSS compilation, the file watcher, and live reload.

Swagger / OpenAPI ​

VariableDefaultDescription
TINA4_SWAGGER_TITLETina4 APIOpenAPI spec title.
TINA4_SWAGGER_DESCRIPTION(empty)OpenAPI spec description.
TINA4_SWAGGER_VERSION1.0.0OpenAPI spec version.
TINA4_SWAGGER_ENABLED(inherits TINA4_DEBUG)Toggle the Swagger UI on or off independently of debug mode. Set true in production to keep API docs available without enabling the rest of the dev surface.
TINA4_SWAGGER_CONTACT_EMAIL(empty)Contact email rendered in the OpenAPI spec's info.contact.email field.
TINA4_SWAGGER_LICENSE(empty)License name in the OpenAPI spec's info.license.name field (e.g. MIT, Apache-2.0).

GraphQL ​

VariableDefaultDescription
TINA4_GRAPHQL_ENDPOINT/graphqlURL path the GraphQL handler is mounted on. POST serves queries, GET serves the GraphiQL IDE.
TINA4_GRAPHQL_AUTO_SCHEMAtrueWhen true, the framework auto-builds the GraphQL schema from every registered ORM model on boot. Set false if you want to define the schema manually with gql.schema.add_type(...).

MCP (Model Context Protocol) ​

VariableDefaultDescription
TINA4_MCP(inherits TINA4_DEBUG)Toggle the built-in MCP dev-tools server. Set explicitly to keep the MCP endpoint exposed in a debug-disabled deployment (e.g. for a remote AI assistant).
TINA4_MCP_PORT(framework port + 2000)TCP port for the MCP server. The default offset keeps it clear of both the main server (default 7145) and the AI test port (+1000).

Minimal .env for Development ​

bash
TINA4_DEBUG=true
TINA4_LOG_LEVEL=DEBUG
TINA4_NO_BROWSER=true

Debug mode lights up the Swagger UI, the dev dashboard, detailed error pages, and live reload. Keeping the browser flag on stops a new tab opening every time you save a file.

Minimal .env for Production ​

bash
TINA4_SECRET=your-long-random-secret-here
TINA4_DATABASE_URL=postgresql://user:password@db-host:5432/myapp
TINA4_CORS_ORIGINS=https://myapp.com,https://www.myapp.com
TINA4_HSTS=31536000
TINA4_MAIL_HOST=smtp.example.com
TINA4_MAIL_PORT=587
TINA4_MAIL_USERNAME=noreply@myapp.com
TINA4_MAIL_PASSWORD=your-smtp-password
TINA4_MAIL_FROM=noreply@myapp.com

No TINA4_DEBUG. It defaults to false, which is what you want in production. Set a real secret, a real database, locked-down CORS origins, HSTS, and SMTP credentials if you send email. Everything else has a production-appropriate default.

Sponsored with 🩵 by Code InfinityCode Infinity

MIT Licensed | Copyright 2007 - present Tina4