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, and 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.
Connection 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_CACHE
false
Enables in-memory query-result caching for read queries.
TINA4_DB_CACHE_TTL
60
Query cache TTL in seconds when TINA4_DB_CACHE=true.
TINA4_DB_POOL
0
Default 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_NAMES
true
When true, the ORM pluralises class names into table names (User → users). Set false to keep them singular.
Frond 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).
Response cache backend. Options: memory, file, redis, valkey, memcached, mongodb, database. Falls back to file if the configured backend is unreachable.
TINA4_CACHE_DIR
data/cache
Cache directory for the file backend.
TINA4_CACHE_TTL
60
Default cache TTL in seconds.
TINA4_CACHE_MAX_ENTRIES
1000
Maximum cache entries. Oldest entries evicted first.
TINA4_CACHE_URL
redis://localhost:6379
Connection URL for remote cache backends. For database, falls back to TINA4_DATABASE_URL when unset.
TINA4_CACHE_USERNAME
(none)
Username for the cache backend. May also be embedded in TINA4_CACHE_URL.
TINA4_CACHE_PASSWORD
(none)
Password for the cache backend. May also be embedded in TINA4_CACHE_URL (e.g. redis://:pass@host). Memcached is unauthenticated.
IMAP transport encryption. Options: tls, starttls, none. Invalid values fall back to tls so a typo can't accidentally disable encryption.
TINA4_MAILBOX_DIR
data/mailbox
Dev 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.
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.
Variable
Default
Description
TINA4_LOG_LEVEL
ERROR
Minimum 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_DIR
logs
Directory for log files. Joined with TINA4_LOG_FILE when the latter is a relative path.
TINA4_LOG_FORMAT
text
Output format. text writes the human-readable [INFO ] message form; json writes one structured JSON record per line.
TINA4_LOG_OUTPUT
stdout
Where logs go. Options: stdout, file, both.
TINA4_LOG_CRITICAL
false
Enables the Log.critical(...) level above error. When off, calls to Log.critical() are silent no-ops.
TINA4_LOG_ROTATE_SIZE
10485760
Bytes per file before rotation (default 10 MB). 0 disables rotation entirely.
TINA4_LOG_ROTATE_KEEP
5
Number of rotated files to keep (app.log.1 ... app.log.N). Older files are deleted on the next rotation.
TINA4_LOG_MAX_SIZE
10485760
Legacy alias for TINA4_LOG_ROTATE_SIZE. Per-file log size limit in bytes (10 MB). Rotated when exceeded.
TINA4_LOG_KEEP
5
Legacy alias for TINA4_LOG_ROTATE_KEEP. Number of rotated log files to retain.
The app-facing Ai client and the developer dashboard share the TINA4_AI_* namespace. The client supports local OpenAI-compatible servers, OpenAI, and Anthropic. See Chapter 40: AI Client for code examples.
Variable
Default
Description
TINA4_AI_PROVIDER
local
Provider used by the app-facing client: local, openai, or anthropic.
TINA4_AI_URL
Provider-specific
Base URL or full endpoint. Local defaults to http://localhost:11437; OpenAI and Anthropic use their public API bases.
TINA4_AI_MODEL
Provider-specific
Default model. Local uses llama3.2, OpenAI uses gpt-4o-mini, and Anthropic uses claude-3-5-haiku-latest.
TINA4_AI_KEY
(none)
Required before an OpenAI or Anthropic request. Local requests need no key.
TINA4_AI_TIMEOUT
60
Total request deadline in seconds, including retries and response reads.
TINA4_AI_CONNECT_TIMEOUT
10
Connection-establishment deadline in seconds.
TINA4_AI_MAX_RETRIES
2
Retries before output for connection failures, HTTP 429, and HTTP 5xx.
TINA4_EMBED_URL
(inherits TINA4_AI_URL)
Optional embedding base URL or full endpoint.
TINA4_RAG_URL
http://localhost:11438
RAG service used by the developer dashboard.
TINA4_RAG_TOPK
4
Number of RAG matches returned per query.
TINA4_VISION_URL
http://localhost:11437/api/chat
Vision endpoint used by developer tools, not the app-facing AI client.
TINA4_IMAGE_URL
http://localhost:11437/api/generate
Image endpoint used by developer tools, not the app-facing AI client.
TINA4_SUPERVISOR_URL
http://localhost:9999
Rust supervisor URL used by developer tools.
TINA4_MCP_REMOTE
false
Allows MCP to bind beyond localhost. Do not enable it on a public production interface.
TINA4_NO_AI_PORT
false
Disables the developer AI port listener.
TINA4_OVERRIDE_CLIENT
false
Lets the framework start without the Rust client in containers and CI.
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).
URL path the GraphQL handler is mounted on. POST serves queries, GET serves the GraphiQL IDE.
TINA4_GRAPHQL_AUTO_SCHEMA
true
When 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(...).
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).
The tables above list every knob. These are the setups most apps actually reach for, ready to paste into .env. Each block sets only what the feature needs. Everything else keeps its default.
One URL points the ORM, the migrations, and the query builder at Postgres. Credentials can ride in the URL or sit in their own variables, which keeps the password out of your shell history.
The response cache and the cross-request query cache both speak to the same Redis. Point them at it and every instance shares one cache, invalidated globally on every write.
The file backend is fine for a single server. Move sessions to Redis the moment you run more than one instance, so a user stays logged in whichever instance answers the next request.
The dashboard AI talks to a local model through Ollama by default, so nothing leaves your machine. Point the URLs elsewhere only when you run the hosted Tina4 AI services.
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.
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.
