Upgrading from Basic to Full-Featured (AI / App Builder)

Applies to: an existing Teable deployment (app + PostgreSQL + Redis) that wants to run the AI runtime -- sandboxes and app deployments -- on its own infrastructure. This covers both basic installs that never had these features and installs currently using the Vercel sandbox / Vercel app-deployment providers.

The version that matters

Teable versions are date-based release tags. The self-hosted AI runtime (the opensandbox sandbox provider and the docker-runtime app-deployment provider, including AI chat over the path-based proxy) is fully supported from

release.2026-07-14T12-24-39Z.2228

which is the version this repository revision is verified against.

How to check what you are running: your image tag is the version (e.g. ghcr.io/teableio/teable:release.2026-07-14T12-24-39Z.2228). If you run :latest, the version name is the release.* tag that shares latest's digest on ghcr -- docker/all-in-one/pin-image.sh --show resolves it for you.

Your Teable	What to do
older than release.2026-07-14T12-24-39Z.2228	Upgrade Teable first (a normal image upgrade -- your data is untouched), then follow this guide
that release or newer	Follow this guide directly

Three things upfront

1. Your data stays in place: your existing Teable, PostgreSQL, Redis, and attachments keep running as-is. Nothing is migrated to another system.
2. Same image: the Teable application image does not change beyond the version requirement above. Full-featured capabilities come from an Infra runtime attached alongside (sandboxes, App Runtime, object storage entry) plus a few connection environment variables.
3. Rollback is a config change, not a restore: at any point, removing the added environment variables and restarting puts you back exactly where you started -- seconds, no data involved. Apps and AI content created while the capabilities were on remain in the database (harmless to the basic edition). Only migrations explicitly marked irreversible in a release's versions.yaml require a pre-upgrade backup, and those guides say so at the top -- this one does not.

Prerequisites

• Teable at release.2026-07-14T12-24-39Z.2228 or later (see above).
• A machine capable of running the Infra stack (it can share the host with your existing app; reserve enough CPU/memory/disk -- see the resource sizing guidance published with each release).
• AI capabilities require a model provider (an API key or a self-hosted compatible service).

Steps

Each step ends with a checkpoint: what to expect, and how to get back to a working state if it does not hold. Your existing data is never rewritten at any step.

1. Start the Infra runtime

Start the Infra components (sandbox engine, Infra Service, Git Registry, MinIO, entry proxy) following docker/all-in-one/ in the deployment repository. If you already run the basic edition, you do not need the app/PostgreSQL/Redis included there -- only the Infra components and the entry.

Checkpoint: cd docker/all-in-one && ./doctor.sh is all green. Your running Teable has not been touched yet -- if anything is off here, fix the Infra stack first; there is nothing to roll back.

2. Record your current app config

One command, so rollback later is mechanical rather than from memory:

docker inspect teable --format '{{range .Config.Env}}{{println .}}{{end}}' > teable-env.before.txt

3. Inject connection environment variables into the existing app

Variable	Value	Notes
SANDBOX_PROVIDER	opensandbox	Enables sandbox capabilities
SANDBOX_OPENSANDBOX_RUNTIME	docker	Required; without it, every command inside sandboxes fails with operation not permitted
APP_DEPLOY_PROVIDER	docker-runtime	App Builder deploys to the local runtime
TEABLE_INFRA_API_URL	Infra entry address	Must be the entry with /v1 routing (the entry proxy), not the direct address of the Infra Service container
TEABLE_INFRA_API_KEY	The same key as the Infra stack	Generated by apply.sh into the Infra stack's .env
SANDBOX_JWT_SECRET	A newly generated random value (e.g. openssl rand -hex 32)	Required: the source code ships a publicly known default; without overriding it, all deployments share the same signing material
TEABLE_INFRA_BUCKET	teable-agent	AI/sandbox data plane
SANDBOX_OPENSANDBOX_IMAGE	The same value as in the Infra stack's .env	Sandbox agent image prefix (no tag): Teable pairs it with its own release tag and preheats that image via the Infra API on startup. China: use registry.cn-shenzhen.aliyuncs.com/teable/teable-sandbox-agent

Restart the app for the changes to take effect.

Checkpoint: the app container comes back healthy and the login page loads. If it does not: remove the variables you just added, restart, and you are back to step 2's state in seconds -- then compare your values against the table above (the two most common mistakes: TEABLE_INFRA_API_URL pointing at the bare Infra Service container instead of the entry, and a missing SANDBOX_OPENSANDBOX_RUNTIME=docker).

4. Verify the capabilities

• TEABLE_INFRA_API_URL is reachable from inside the app container (/v1 returns 401/200, not 404 or a timeout).
• Run the self-check from the deployment repository: cd docker/all-in-one && ./doctor.sh.
• Log in to Teable: create an App Builder application and open its preview; for AI capabilities, configure a model per the product documentation and verify.

Checkpoint: doctor all green + an App preview renders. If a specific check fails, the doctor output names the first layer to look at; the Common failures table below covers the rest.

5. Switch to your long-term configuration

Once verification passes, write the environment variables from step 3 into your permanent configuration (compose files / environment management) and include them in your backup and upgrade procedures.

Migrating from the Vercel providers

Warning -- the Vercel sandbox provider is hard-removed, and the order matters. As of release.2026-07-01T11-07-52Z.2082, the Vercel sandbox provider code is removed from the Teable app. Before upgrading to that release or any newer one, set SANDBOX_PROVIDER to opensandbox (or remove the variable entirely); otherwise the app container fails to start with Unknown sandbox provider type: vercel -- the provider is validated at boot, not when an AI session starts. Change the environment first, then upgrade the image.

If your Teable currently uses the Vercel sandbox and/or Vercel app-deployment providers, the switch is configuration-only and existing deployments keep running while you migrate:

1. Complete steps 1-4 above (the Infra runtime must be up and verified).

2. Set the provider variables on the app and restart:

   Variable	Old value	New value
   SANDBOX_PROVIDER	vercel	opensandbox
   APP_DEPLOY_PROVIDER	vercel (default)	docker-runtime

3. Sandboxes: nothing to migrate -- sandboxes are ephemeral sessions. Every session started after the restart runs on your own runtime. The sandbox snapshot feature was removed in the same release as the Vercel provider; no snapshot data carries over or needs to. Historical AI session workspaces are migrated automatically by the app (a one-shot legacy-compatibility import when the next session starts) -- users do not need to do anything.

4. App deployments: each deployment record remembers the provider it was created with, so existing Vercel-deployed apps keep running and stay manageable (status, stop) after the switch. Every new deploy or redeploy lands on your own runtime and is served at <app>.app.<your-domain>. To migrate an app: redeploy it from the App Builder, verify the new URL, then update any shared links or custom domains and retire the Vercel side at your own pace.

Rollback

1. Remove all environment variables injected in step 3 and restart the app (teable-env.before.txt from step 2 is your reference).
2. Shut down the Infra components (keeping the data volumes is up to you; if kept, the data is still there when you re-enable the capabilities).
3. Verify that basic functionality works.
4. Remember: Apps and AI data produced while the capabilities were enabled remain in the database (harmless to the basic edition).

Common failures

Symptom	First place to look
App container exits on boot with Unknown sandbox provider type: vercel	A leftover SANDBOX_PROVIDER=vercel; set it to opensandbox (or remove it) before upgrading
operation not permitted when creating a sandbox/App	SANDBOX_OPENSANDBOX_RUNTIME=docker is missing
Sandbox creation fails with Create sandbox failed	TEABLE_INFRA_API_URL points to the Infra Service container directly; it should point to the entry proxy
AI / App Builder entry does not appear	Version requirement not met, or license conditions not satisfied (see the product documentation)
Attachments/avatars return 404	The entry proxy is missing the public bucket path forwarding (check the entry proxy configuration shipped with the Infra stack)