> ## 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. # Pixeltable Cloud > Run the same application file against a hosted database Pixeltable Cloud is in Limited Beta. Email [contact@pixeltable.com](mailto:contact@pixeltable.com) if you are interested. The [Quickstart](/overview/quick-start) runs `app.py` locally. Here, the same application file creates tables and starts HTTP on a hosted database. A `pxt login` session is enough for the first deployment. You do not need an API key. ## First deployment Python 3.11+ on Linux, macOS, or Windows. `pxt login`, `pxt whoami`, and `pxt key` require Pixeltable 0.7.10 or later. ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}} python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -U 'pixeltable[serve]' pxt login pxt whoami pxt org list ``` `pxt login` shows a code to confirm in your browser. `pxt org list` prints each organization as `NAME id=...`. Use that name in place of `org` in the `pxt://org:main` commands below. If `pxt whoami` prints `No organization yet` while `pxt org list` shows one, upgrade with `pip install -U 'pixeltable[serve]'` and run `pxt login` again. If `pxt org list` prints `No orgs.`, create one. The name is unique across Pixeltable: lowercase letters, digits, and hyphens, starting and ending with a letter or digit, at most 29 characters. ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}} pxt org create NAME ``` `pxt org create` provisions your first database, `main`, and switches your `pxt login` session to the new organization. In a new directory, run: ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}} mkdir cloud-app && cd cloud-app pxt init pxt service example --out app.py ``` In a notebook, `!cd` does not carry over to the next command. Use `%cd cloud-app` instead, so that `pxt init` makes that directory the project root. `pxt service example` writes a working `app.py` with a `Docs` table and an `ingest` HTTP service. If you already completed the Quickstart, use that `app.py` instead. Add a hosted database entry for that `main` database to the `pixeltable.toml` that `pxt init` created. Replace `org` with your organization name: ```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}} [[pixeltable.database]] name = 'pxt://org:main' ``` Keep the local database entry that `pxt init` wrote. If your project has a `pyproject.toml`, `pxt init` adds its entry there instead. Use `[[tool.pixeltable.database]]` for the hosted entry. A new database is ready when `pxt db status pxt://org:main` shows `AVAILABLE`. Until then, `pxt db update` is refused. Run these commands from the project directory, in order: ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}} pxt db update pxt://org:main pxt schema update app.py pxt://org:main pxt service update app.py pxt://org:main pxt service list pxt://org:main ``` `pxt db update` and `pxt service update` ask for confirmation. Without a terminal to answer, as in a notebook or a script, add `-f`. The first `pxt db update` builds the image, which takes several minutes, and returns when the database is ready. `pxt org create` already provisioned `main`. `pxt db update` uploads the project onto that database and updates its image and size. It does not insert rows and does not start app endpoints. `pxt schema update` creates the tables. It does not start the endpoints. `pxt service update` starts hosted endpoints. Do not use `pxt service run` for Cloud. That command only starts endpoints in your local terminal. `pxt service list` prints the service URL and its routes. The host looks like `https://{org}-{db}.svc.pxt.run/`. The control plane host is separate. Do not hardcode either hostname. The generated `app.py` defines a `docs` table with a computed `title_upper` column. Insert a row from Python: ```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}} import pixeltable as pxt docs = pxt.get_table('pxt://org:main/docs') docs.insert(title='Hello', body='world') print(docs.select(docs.title, docs.title_upper).collect()) ``` The result includes `Hello` and `HELLO`. The insert computes `title_upper` on Cloud. A local file path on a Cloud table uploads the file. The table also appears in the [Cloud dashboard](https://www.pixeltable.com/dashboard). A Cloud table path uses the URI plus `/table`, such as `pxt.get_table('pxt://org:main/docs')`. A local table uses dotted `namespace.table`, such as `pxt.get_table('my_app.docs')`. Run `pxt schema diff app.py pxt://org:main` to see pending schema changes. The same file can define `pxt.Image`, `pxt.Video`, `pxt.Audio`, or `pxt.Document` columns: [media pipelines](/use-cases/media-processing), [RAG](/use-cases/multimodal-backend). ## Get an API key API keys are optional for the CLI and Python workflow above. Create one for CI, background jobs, or a backend that calls a hosted HTTP service. If a browser frontend needs that service, have it call your backend. Keep the key out of browser code. The CLI reads the key from `PIXELTABLE_API_KEY`, or from `api_key` in the `[pixeltable]` section of the Pixeltable config file. The environment variable wins. Either one takes precedence over a `pxt login` session. [Configuration](/platform/configuration). After `pxt login`, create a key from the CLI: ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}} pxt key create my-app ``` The CLI prints the secret once. `pxt key list` shows key names, and cannot show their secrets again. A key created without `--grant` acts as you. [Scoped service keys](/platform/cli#pxt-key) are in preview. You can also create a key under **API Keys** in the [Cloud dashboard](https://www.pixeltable.com/dashboard). ### Call the hosted service Get the service URL from `pxt service list pxt://org:main`. Put the key in your backend's environment and send it in the `X-api-key` header: ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}} export PIXELTABLE_API_KEY='your-key' SERVICE_URL='URL from pxt service list' curl -X POST "$SERVICE_URL/docs" \ -H "X-api-key: $PIXELTABLE_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"title": "Hello from HTTP", "body": "world"}' ``` Cloud checks `X-api-key` first. A request that also sends `Authorization: Bearer` is authenticated as the API key. For the TypeScript client, follow [Call from a TypeScript app server](/howto/deployment/serving#call-from-a-typescript-app-server). That client sends `X-api-key` and exports `computeTitle()` for the generated app's `/titles` route. ## Add provider secrets `PIXELTABLE_API_KEY` authenticates to Pixeltable Cloud. Provider keys, such as `OPENAI_API_KEY`, belong in Cloud **Secrets**. For a database that uses OpenAI: ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}} pxt secret set pxt://org:main OPENAI_API_KEY=your-provider-key pxt db restart pxt://org:main pxt service restart pxt://org:main/ingest ``` The restarts let running table and service processes read the new value. You can also set secrets in the [Cloud dashboard](https://www.pixeltable.com/dashboard). [CLI secret commands](/platform/cli#pxt-secret). ## What the database runs A hosted database runs two things that come from your project, and they move independently. * **The image** is the Python environment: your dependencies, the Python version, and any system packages. `pxt db update` rebuilds it only when that environment changed, which is the slow step. * **The project files** are your `app.py` and whatever else the entry selects. They are uploaded on their own, without a rebuild. So editing a UDF costs an upload, while adding a line to `pyproject.toml` costs a build. Both are `pxt db update`. It works out which happened. The image gets its packages from `uv.lock` or `requirements.txt`. Without either, `pxt db update` warns, and the image has Pixeltable only. That is enough for the generated `app.py`. List anything else `app.py` imports in one of those files. `[[pixeltable.database]]` in `pixeltable.toml` declares which files are selected, what the image includes, and the CPU, memory, disk, and worker counts. See the [cloud configuration reference](/platform/cli#cloud-configuration-reference). ## What to run after a change | You changed | Run | | - | - | | A UDF body, a route, any `.py` the entry selects | `pxt db update pxt://org:main`, then `pxt service update app.py pxt://org:main` to move running services onto it | | A column or a table in `app.py` | `pxt db update pxt://org:main`, then `pxt schema update app.py pxt://org:main`, then `pxt service update app.py pxt://org:main` | | A dependency, the Python version, a system package | `pxt db update pxt://org:main`: the image rebuilds | | `cpu`, `memory_mb`, `disk_gb`, or `workers` | `pxt db update pxt://org:main`: one resize, pods restart once | | A secret | `pxt secret set pxt://org:main KEY=...`, then `pxt db restart pxt://org:main` and `pxt service restart pxt://org:main/ingest` | | Nothing, but the last build failed | `pxt db build-image pxt://org:main` forces a rebuild | `pxt db diff pxt://org:main` prints what `update` would do without doing it. ## Operate it ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}} pxt db status pxt://org:main # state, resources, pods pxt db logs pxt://org:main # the database pod's log pxt service list pxt://org:main # the services running there, and their URLs pxt service logs pxt://org:main/ingest pxt db restart pxt://org:main # cycle the pods onto what they already run pxt db stop pxt://org:main # sleep: stops the pods, keeps the data pxt db start pxt://org:main # wake it again pxt db list # every hosted database you can reach ``` `pxt db delete pxt://org:db` deletes a database and its storage. The organization's default database, `main`, cannot be deleted. Full reference: [CLI](/platform/cli#cloud). ## Media on the home bucket Every Cloud database includes a managed Media Store at `pxtfs://org:main/home`. Hosted tables and services write there automatically. No `destination=`, no dest env vars. Set dest only for two cases: * **Local Pixeltable** writing into that same bucket: `pxt login` or `PIXELTABLE_API_KEY`, plus `PIXELTABLE_INPUT_MEDIA_DEST` / `PIXELTABLE_OUTPUT_MEDIA_DEST` (see [Cloud storage](/integrations/cloud-storage#pixeltable-cloud-home-bucket)). * **Your own bucket**: store `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (or GCS / Azure names) under **Secrets** or `pxt secret`, then point those dest env vars at `s3://`, `gs://`, or `wasbs://`. A single computed column can also set `destination=`: ```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}} import pixeltable as pxt TableModel = pxt.model_base() class Images(TableModel, name='images'): photo: pxt.Image thumbnail = pxt.Column( value=photo.resize((256, 256)), destination='s3://my-bucket/thumbnails', ) ``` Or set `db_input_media_dest` / `db_output_media_dest` on the database's `[[pixeltable.database]]` entry to change the default for inserted or computed media. Details: [Cloud storage](/integrations/cloud-storage#default-destinations). ## Local vs Cloud | | Local | Cloud | | - | - | - | | Hosted database | not needed | `pxt db update pxt://org:main` | | Tables | `pxt schema update app.py my_app` | `pxt schema update app.py pxt://org:main` | | HTTP | `pxt service update app.py my_app` | `pxt service update app.py pxt://org:main` | | Try a change | insert, `pxt dashboard`, `pxt schema diff app.py my_app` | insert from Python, `pxt schema diff app.py pxt://org:main` | | Media | local disk | `pxtfs://org:main/home` | Cloud is in Limited Beta. Talk through a Cloud deployment.