Pixeltable Cloud

Pixeltable Cloud is in Limited Beta. Email [email protected] if you are interested.

The Quickstart 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

Install Pixeltable and sign in

Python 3.11+ on Linux, macOS, or Windows. pxt login, pxt whoami, and pxt key require Pixeltable 0.7.10 or later.

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.

pxt org create NAME

pxt org create provisions your first database, main, and switches your pxt login session to the new organization.

Prepare the application and Cloud target

In a new directory, run:

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:

[[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.

Upload the project, create tables, and start the service

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:

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/<service>. The control plane host is separate. Do not hardcode either hostname.

Insert a row and check the result

The generated app.py defines a docs table with a computed title_upper column. Insert a row from Python:

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.

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, RAG.

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. After pxt login, create a key from the CLI:

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 are in preview. You can also create a key under API Keys in the Cloud 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:

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. 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:

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. CLI secret commands.

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.

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

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.

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).
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=:

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.

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`

Request an account

Cloud is in Limited Beta.

Book a demo

Talk through a Cloud deployment.

Getting started

Tools

How to

Resources

First deployment

Get an API key

Call the hosted service

Add provider secrets

What the database runs

What to run after a change

Operate it

Media on the home bucket

Local vs Cloud

Request an account

Book a demo

​First deployment

​Get an API key

​Call the hosted service

​Add provider secrets

​What the database runs

​What to run after a change

​Operate it

​Media on the home bucket

​Local vs Cloud

Request an account

Book a demo

First deployment

Get an API key

Call the hosted service

Add provider secrets

What the database runs

What to run after a change

Operate it

Media on the home bucket

Local vs Cloud