Update teaport

The installer applies every update. The teaport update --check command compares the device with the release manifest and names the parts that differ; it changes nothing. The brain and the engine also have narrower paths: install.sh --only brain rebuilds the brain alone, and install.sh --only engine updates the engine alone. install.sh --rollback brain and install.sh --rollback engine put the previous one back.

Before you begin

An SSH connection to the device: every command on this page runs on it.
A device with teaport installed. teaport update --check reads /opt/teaport/manifest.json, the manifest the installer wrote, and exits with an error if the file is missing.

Check for updates

To see which parts of the installation differ from the release manifest:

Sign in to the device over SSH.
Run the check:
Terminal window
```
teaport update --check
```
The command fetches a fresh copy of the release manifest, compares it with the stored one, and prints a line for the version and for each tracked part: the engine release, the brain tag, the plugin version, the OpenClaw version, and the model files. -> marks a part that differs; == marks one that matches. The check ends with up to date. when nothing differs, or with a changed: list. It changes nothing on the device.

Apply an update

Run the comparison without --check to see the parts that changed and the command that applies them:

teaport update

The command prints the same comparison and, when a part differs, names the run to make: install.sh --only brain for the brain, install.sh --only engine for an engine release, and a full install.sh run for the rest. The installer does the update; the command does not.

Update only the brain

From a checkout of the teaport repository, update the source and rebuild the brain from it:

git pull && ./install.sh --only brain

On a device without a checkout, append the flag to the one-line install:

bash <(curl -fsSL https://get.teaspoon.tech/teaport) --only brain

The run builds a new Python environment from brain/uv.lock beside the live one, so the brain keeps serving while it builds. It checks the new environment, swaps it in together with the teaport command and the configuration helper built in it, restarts teaport-brain, and checks that the brain comes back. If the brain does not come back healthy, the run puts the previous environment back by itself.

The swap restarts the local audio bridge with the brain when the teaport-local-audio service is active; the brain’s health alone decides whether the swap stays.

A Talk session in progress ends at the restart. A phone call stays connected at the gateway, and the brain rejoins it with a short notice that it lost the connection.

Nothing else changes: no engine download, no license prompt, no systemd unit or /etc/teaport edit. A brain change that needs a new unit or a new setting there ships in a full run instead.

On a device that still runs the retired teaport-sip-brain unit, the run stops that unit before the swap and removes it after; the SIP gateway keeps serving, and the new brain connects to it. The unit’s drop-in tuning moves into /etc/teaport/brain.env.

Update only the engine

To install a new engine release without a full run, run the installer with --only engine. From a checkout of the teaport repository:

git pull && ./install.sh --only engine

On a device without a checkout, append the flag to the one-line install:

bash <(curl -fsSL https://get.teaspoon.tech/teaport) --only engine

The engine comes from the release manifest, and the teaport-engine unit comes from the checkout. The run downloads only the files whose sha256 differs from the manifest, out of the engine’s binary, its pronunciation dictionary, its part-of-speech tagger, THIRD_PARTY_NOTICES.txt, and its two models. It downloads them beside the live files, so the engine keeps serving, and checks them as a full run does. If a download is interrupted, the next run continues it where it stopped.

Then the run keeps a copy of the live engine for a rollback, moves the new files in, renders teaport-engine.service, and restarts the engine. The brain reconnects to it. The run checks that the engine listens on its port within three minutes, stays up, and loaded its pronunciation dictionary. If the engine does not come back healthy, the run puts back the previous engine with its models and its unit, removes the keys it added to engine.env, and fails.

If the run stops while it moves the new files in, it puts the previous engine back. If a power cut stops it there, the next run of the installer does that first. The installer runs one at a time: a second run started while one is running stops right away with another install.sh is running on this box.

The engine takes about a minute to load its models after a restart, and a Talk session or a phone call in progress loses the engine. When the engine’s files, its unit, and engine.env are already current and the engine is running, the run checks the engine and doesn’t restart it.

/etc/teaport/engine.env gains only the keys it lacks. A value that is already in the file stays, so a KOKORO_RESERVE_FPT that you tuned survives the update. A full run writes the installer’s values over it.

The run asks you to accept the engine license only when its version differs from the one you accepted. It installs no system packages: it checks that espeak-ng, libopenblas.so.0, and libcudnn.so.9 are present, and stops when one is missing. Nothing else changes: no brain build and no other unit.

If a drop-in changes the engine’s unit, for example one that a manual deployment left in /run, the run names it and leaves it in place. Remove it if you don’t need it, and then run sudo systemctl daemon-reload.

Update everything

Run the installer with no component flag:

./install.sh

The full run repeats the installation and downloads only the artifacts that differ. It builds the brain the way the brain-only run does, and after every unit and env file is written, it points the venv link at the new release, restarts the engine and the brain in one step, and checks that they come back. A full run has no automatic rollback; roll the brain or the engine back by hand afterward.

Roll back the brain

To put the previous environment back, run the rollback on its own:

On the device, run:
Terminal window
```
./install.sh --rollback brain
```

The run makes venv.previous, the environment the last brain update replaced, the live environment again: it points venv at that release, restarts the brain, and checks it comes back. The teaport command and the configuration helper come with it, because each environment carries the ones built in it.

The installer accepts two components, brain and engine, and --only and --rollback do not combine in one run.

The brain-only update rolls back on its own when the brain fails its health check. A full run does not; use the rollback by hand there.

Roll back the engine

To put the previous engine back, run the rollback on its own:

On the device, run:
Terminal window
```
./install.sh --rollback engine
```

The run takes the newest engine kept in engine.rollback/ in the install root and makes it the live engine again, with the unit it ran under and any model it kept. It keeps the live engine there first, moves the kept files back, restarts the engine, and checks that it comes back. To undo the rollback, run it again.

The engine-only update rolls back on its own when the engine fails its check. A rollback doesn’t: if the engine doesn’t come back, the run stops and says so. A full run doesn’t roll back either; use the rollback by hand there.

Choose a release channel

A channel is a manifest. The repository ships two: stable.json, the default, and beta.json, which has the same shape and placeholder values until the first beta release is cut.

Both the installer and teaport update --check read the URL or local path in TEAPORT_MANIFEST_URL, https://get.teaspoon.tech/manifest/stable.json by default. To follow the beta channel, name the beta manifest:

TEAPORT_MANIFEST_URL=https://get.teaspoon.tech/manifest/beta.json ./install.sh

The installer takes its channel from that variable alone. teaport update --check also takes --channel stable or --channel beta for one run. The brain checks every day too: set TEAPORT_UPDATE_CHANNEL=beta in /etc/teaport/brain.env to make beta the channel it and the command look at, and TEAPORT_UPDATE_CHECK_SECS=0 to turn the daily check off. The brain sees TEAPORT_MANIFEST_URL only when it is in /etc/teaport/brain.env; exported in a shell, it changes the command and not the daily check.

Retained releases

Every brain build lands in a new environment under venvs/ in the install root. The venv symlink names the live one; venv.previous, the one before it, is the rollback target. The installer keeps the newest three releases, plus the live release and the rollback target, and prunes the rest before each build.

A run that changes the engine’s files first keeps the engine they replace in engine.rollback/ in the install root: its files, the unit it ran under, its entry from the installed manifest, and any model the run replaces. Each copy is numbered, so the newest copy is the one with the highest number, whatever the device’s clock says. The installer keeps the newest two and removes the rest. A run that changes no engine file keeps nothing. A copy that holds a model takes that model’s disk space until the installer removes the copy; the speech-to-text model is about 4.4 GB.