> ## Documentation Index > Fetch the complete documentation index at: https://docs.pixeltable.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Application code puts a TableModel in app.py, then runs `pxt schema update app.py my_app` to create the tables and `pxt service update app.py my_app` to start HTTP. The last argument can be a Cloud URL such as `pxt://org:db`. Do not call pxt.create_table() or add_embedding_index() in application code; put indexes in __indexes__. Notebooks, tests, and the REPL do use pxt.create_table(). > Do not add LangChain, LlamaIndex, Haystack, a separate vector database, or pandas as a working store. Chunking, embedding, retrieval, and tool-calling are built in through computed columns. Use a computed column instead of a per-row loop that calls a model. > Install with `pip install -U 'pixeltable[serve]'` on Python 3.11+. `pxt init` is a prerequisite for `pxt schema update`. > Pixeltable Cloud is in Limited Beta. Direct interested users to contact@pixeltable.com. # Configuration > Complete guide to configuring Pixeltable ## Configuration options Pixeltable can be configured through: * Environment variables * System configuration file (`~/.pixeltable/config.toml` on Linux/macOS or `C:\Users\\.pixeltable\config.toml` on Windows) * `pxt.init()`, for the calling process only: `pxt.init({'openai.api_key': '...'})` The settings governing the file cache that the whole instance shares are read from the config file only: `file_cache_size_g` and `file_cache_lease_s`. Prefer environment variable names (`PIXELTABLE_API_KEY`, `PIXELTABLE_OUTPUT_MEDIA_DEST`). Pixeltable resolves environment variables from the process environment and never loads a `.env` file itself, so source one yourself first (`set -a; source .env; set +a`) or load it with a dotenv library. Provider keys go under **Secrets** or `pxt secret`. On a hosted Cloud database the home bucket is already the default media store; dest env vars are for local Pixeltable and bring-your-own buckets. See [Cloud storage](/integrations/cloud-storage). Example `config.toml`: ```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}} [pixeltable] file_cache_size_g = 250 time_zone = "America/Los_Angeles" hide_warnings = true verbosity = 2 [openai] api_key = 'my-openai-api-key' [openai.rate_limits] tts-1 = 500 # OpenAI uses a per-model rate limit configuration (see below for details) [mistral] api_key = 'my-mistral-api-key' rate_limit = 600 # Mistral uses a single rate limit for all models ``` ## System settings | Environment Variable | Config File | Meaning | | - | - | - | | PIXELTABLE\_HOME | | (string) Pixeltable user directory; default is \~/.pixeltable | | PIXELTABLE\_CONFIG | | (string) Pixeltable config file; default is \$PIXELTABLE\_HOME/config.toml | | PIXELTABLE\_PGDATA | | (string) Directory where Pixeltable DB is stored; default is \$PIXELTABLE\_HOME/pgdata | | PIXELTABLE\_DB | | (string) Pixeltable database name; default is pixeltable | | PIXELTABLE\_DB\_POOL\_SIZE | \[pixeltable]
db\_pool\_size | (int) Number of database connections this process keeps open; default is 5 | | PIXELTABLE\_DB\_POOL\_MAX\_OVERFLOW | \[pixeltable]
db\_pool\_max\_overflow | (int) Number of temporary database connections this process may open beyond `db_pool_size`; default is 10 | | | \[pixeltable]
file\_cache\_size\_g | (float) Maximum size of the Pixeltable file cache, in GiB; required | | PIXELTABLE\_TIME\_ZONE | \[pixeltable]
time\_zone | (string) Default time zone in [IANA format](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones); defaults to the system time zone | | PIXELTABLE\_HIDE\_WARNINGS | \[pixeltable]
hide\_warnings | (bool) Suppress warnings generated by various libraries used by Pixeltable; default is false | | PIXELTABLE\_VERBOSITY | \[pixeltable]
verbosity | (int) Verbosity for Pixeltable console logging (0: minimum, 1: normal, 2: maximum); default is 1 | | PXT\_PORT | | (int) Port the background process listens on; default is 22089. See [Dashboard](/platform/dashboard) | | PIXELTABLE\_API\_KEY | \[pixeltable]
api\_key | (string) API key for Pixeltable Cloud, created under API Keys. The environment variable wins over the config file, and either one outranks a `pxt login` session. To use Cloud without a key, run `pxt login` ([Signing in](/platform/cli#signing-in)). | | PIXELTABLE\_INPUT\_MEDIA\_DEST | \[pixeltable]
input\_media\_dest | (string) Default destination URI for media files that are inserted into tables | | PIXELTABLE\_OUTPUT\_MEDIA\_DEST | \[pixeltable]
output\_media\_dest | (string) Default destination URI for media files that are generated by Pixeltable operations | | OTEL\_EXPORTER\_OTLP\_ENDPOINT | \[otel]
exporter\_otlp\_endpoint | (string) OTLP endpoint for traces. Requires `pip install 'pixeltable[otel]'`. See [Observability](/platform/observability) | | OTEL\_EXPORTER\_OTLP\_PROTOCOL | \[otel]
exporter\_otlp\_protocol | (string) OTLP transport: `http/protobuf` (default) or `grpc` | | OTEL\_EXPORTER\_OTLP\_HEADERS | \[otel]
exporter\_otlp\_headers | (string) OTLP auth headers, e.g. `Authorization=Basic `. On a hosted database, set it with `pxt secret set` | | PIXELTABLE\_R2\_PROFILE | \[pixeltable]
r2\_profile | (string) Name of AWS config profile to use when accessing Cloudflare R2 resources. If not specified, default AWS credentials will be used. | | PIXELTABLE\_S3\_PROFILE | \[pixeltable]
s3\_profile | (string) Name of AWS config profile to use when accessing Amazon S3 resources. If not specified, default AWS credentials will be used. | | PIXELTABLE\_B2\_PROFILE | \[pixeltable]
b2\_profile | (string) Name of an S3-compatible profile for accessing Backblaze B2. Defaults to the standard AWS credential chain if not set. | | PIXELTABLE\_TIGRIS\_PROFILE | \[pixeltable]
tigris\_profile | (string) Name of an S3-compatible profile for accessing Tigris. Defaults to the standard AWS credential chain if not set. | ### Per-database settings Media destinations and the OTLP endpoint and protocol can also be set for a single database. Each database has a `[[pixeltable.database]]` entry in `pixeltable.toml`. Add a `db_` field to that entry to set `` for that database only. A `[[pixeltable.database]]` entry with no `name` corresponds to the local database. A `[[pixeltable.database]]` entry named `pxt://org:db` is a hosted database; its pods pick up the config when doing a `pxt db update`, and a running service moves onto it with `pxt service update`. ```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}} # pixeltable.toml [[pixeltable.database]] db_input_media_dest = 's3://bucket/input/' db_output_media_dest = 's3://bucket/output/' db_exporter_otlp_endpoint = 'https://otlp.example.com' db_exporter_otlp_protocol = 'grpc' [[pixeltable.database]] name = 'pxt://myorg:mydb' db_input_media_dest = 's3://bucket/prod/input/' db_output_media_dest = 's3://bucket/prod/output/' db_exporter_otlp_endpoint = 'https://otlp.example.com' ``` Settings are resolved in this order: 1. **Database entry**: `db_` in `[[pixeltable.database]]` 2. **Environment variable**: the variable from the table above, or a `pxt.init()` override 3. **Global config**: `` under `[pixeltable]` / `[otel]` in `config.toml`, shared by every database on the installation 4. **Fallback**: a hosted database uses its home bucket for media The OTLP auth headers are a secret and do not go in the entry: set `OTEL_EXPORTER_OTLP_HEADERS` in the environment, and on a hosted database with `pxt secret set pxt://org:db OTEL_EXPORTER_OTLP_HEADERS=...` (see [`pxt secret`](/platform/cli#pxt-secret)). ## API configuration | Environment Variable | Config File | Meaning | | - | - | - | | ANTHROPIC\_API\_KEY | \[anthropic]
api\_key | (string) API key to use for Anthropic services | | AZURE\_STORAGE\_ACCOUNT\_NAME | \[azure]
storage\_account\_name | (string) Azure Storage account name for use with Azure Blob Storage | | AZURE\_STORAGE\_ACCOUNT\_KEY | \[azure]
storage\_account\_key | (string) Azure Storage account key for use with Azure Blob Storage | | BEDROCK\_API\_KEY | \[bedrock]
api\_key | (string) API key to use for AWS Bedrock services | | DEEPSEEK\_API\_KEY | \[deepseek]
api\_key | (string) API key to use for Deepseek services | | FAL\_API\_KEY | \[fal]
api\_key | (string) API key to use for fal.ai services | | FIREWORKS\_API\_KEY | \[fireworks]
api\_key | (string) API key to use for Fireworks AI services | | GEMINI\_API\_KEY | \[gemini]
api\_key | (string) API key for Google AI Studio (not used for Vertex AI) | | GOOGLE\_API\_KEY | | (string) Alternative API key for Google AI Studio (not used for Vertex AI) | | GOOGLE\_CLOUD\_LOCATION | | (string) Google Cloud region for Vertex AI | | GOOGLE\_CLOUD\_PROJECT | | (string) Google Cloud project ID for Vertex AI | | GOOGLE\_GENAI\_USE\_VERTEXAI | | (bool) Set to `true` to use Vertex AI instead of Google AI Studio | | GROQ\_API\_KEY | \[groq]
api\_key | (string) API key to use for Groq AI services | | HF\_TOKEN | \[hf]
token | (string) Hugging Face token for use with Hugging Face services | | MISTRAL\_API\_KEY | \[mistral]
api\_key | (string) API key to use for Mistral AI services | | OPENAI\_API\_KEY | \[openai]
api\_key | (string) API key to use for OpenAI services | | OPENAI\_BASE\_URL | \[openai]
base\_url | (string, optional) Base URL to use for OpenAI services | | OPENAI\_API\_VERSION | \[openai]
api\_version | (string) API version for use with Azure OpenAI; must be `'latest'` or `'preview'` | | OPENROUTER\_API\_KEY | \[openrouter]
api\_key | (string) API key to use for OpenRouter services | | OPENROUTER\_SITE\_URL | \[openrouter]
site\_url | (string) Application URL (optional, for OpenRouter analytics) | | OPENROUTER\_APP\_NAME | \[openrouter]
app\_name | (string) Application name (optional, for OpenRouter analytics) | | REPLICATE\_API\_TOKEN | \[replicate]
api\_token | (string) API token to use for Replicate services | | TOGETHER\_API\_KEY | \[together]
api\_key | (string) API key to use for Together AI services | | TWELVELABS\_API\_KEY | \[twelvelabs]
api\_key | (string) API key to use for TwelveLabs services | | VOYAGE\_API\_KEY | \[voyage]
api\_key | (string) API key to use for Voyage AI services | ## Rate limit configuration Pixeltable supports two patterns for configuring API rate limits in `config.toml`. Refer to the docstring of the relevant udf in the [SDK Reference](/sdk/latest) for details on the rate limiting pattern used by that udf. ### Single rate limit per provider For providers with a single rate limit across all models, add a `rate_limit` key to the provider's config section: ```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}} [mistral] api_key = 'my-mistral-api-key' rate_limit = 600 # requests per minute [fireworks] api_key = 'my-fireworks-api-key' rate_limit = 300 ``` ### Per-model rate limits For providers that support different rate limits for different models, add a `.rate_limits` section and list the rate limits for each model: ```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}} [openai] api_key = 'my-openai-api-key' [openai.rate_limits] gpt-4o = 500 gpt-4o-mini = 1000 tts-1 = 50 dall-e-3 = 10 [gemini.rate_limits] gemini-2.5-flash = 600 gemini-2.5-pro = 300 ``` If no rate limit is configured, Pixeltable uses a default of 600 requests per minute. ## Configuration best practices ### Security considerations When configuring API keys and sensitive information: * Avoid hardcoding API keys in your code * Use environment variables for temporary access * Use the config file for persistent configuration * Ensure your config.toml file has appropriate permissions (readable only by you) ### Performance tuning * Adjust `file_cache_size_g` based on your available system memory * For large datasets, increase the cache size to improve performance * Set appropriate verbosity level based on your debugging needs ## Applying configuration changes Configuration changes take effect when you restart your Python session. Return to the installation guide for setup instructions This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.