open-webui/terminals v0.4.0

on GitHub

Requires Open WebUI 0.13.4 or later.

0.4.0 brings terminal settings and sharing rules into one template, selected directly in Open WebUI. Previously, you had to check both the policy and the connection settings to know which workspace someone would get. Now that choice lives on the template.

For example, a team can use one Python template with a separate workspace for each person. Everyone keeps their own files, but you only maintain one set of settings. Change the image or resource limits once, and each workspace uses those settings the next time it starts.

When people need to work together, choose Chat scope: everyone allowed to continue that chat uses the same terminal and files. Previously, sharing a chat could still leave each person in a different terminal. Model scope keeps a workspace available across chats using the same model or preset. For two independent experiments, create two templates with scope None.

You can create, configure, and share these templates from WebUI's terminal selector. WebUI checks access, and Terminals manages the workspaces. Policies become templates as part of this change; the scope options below replace the old allocation flags.

Scopes

Each template has one scope. A workspace includes both the running terminal and its saved files.

New templates default to None. Choose User for separate personal files. Chat scope needs a saved chat; model scope needs a selected model. Missing information causes an error instead of opening a different workspace.

Model scope follows the model or preset selected in WebUI. Two presets using the same provider model get separate workspaces. Changing a preset's provider model keeps its workspace.

Terminal management

• Create, configure, and share terminals from WebUI. Each template has its own Use and Manage permissions. A new personal template is private until shared. Users also need access to its connection.
• Shared chats use their selected terminal. Collaborators can use it while the chat owner retains access to the template. Sharing a read-only snapshot does not allow terminal use.
• Stopped workspaces remain listed. The environment list includes stopped terminals whose files remain. Checking status or viewing the list does not start them.
• Renaming keeps the same files. A template's ID stays the same when its name changes. Image and other instance setting changes take effect when the terminal next starts. Delete its existing environments before changing scope or storage mode.

Restart, reset, and delete

Restart and reset do nothing for a workspace that has never been created. Deleting an already removed environment is safe to repeat. If deletion fails partway through, Terminals keeps records of what remains so you can retry.

Terminals tracks workspaces whether or not they have a reset schedule. Scheduled resets, image restrictions, resource limits, network profiles, security settings, idle cleanup, and maximum lifetime remain available.

Other changes

• The built-in admin UI has Templates and Environments. It includes create, configure, restart, reset, and delete actions. Name and scope have their own fields; advanced settings and reset schedules use JSON editors. The old bulk rollout and user-data screens are removed.
• Automations use the same scope choices. User uses the automation owner; Model uses its selected model; Chat uses the saved chat created for that run; None uses the template's shared workspace. Runs that create new chats get separate Chat workspaces. Channel automations without a saved chat cannot use Chat scope.
• New installations start without a default template. Create one before running commands. An old default policy can be migrated as an ordinary template that you can edit or delete.
• Raw Open Terminal connections and Tether devices keep their existing connection paths. The template changes apply to terminals managed by this service.
• Docker hosts now pull a newer :latest image. Before, Docker kept whichever image it first downloaded, so a host could stay on an old Open Terminal indefinitely. Terminals now checks the registry before starting a workspace from an image tagged :latest or untagged, at most once an hour per image, and uses the local copy if the registry can't be reached. Pinned tags are pulled only when missing. Set TERMINALS_IMAGE_PULL_POLICY to Always, IfNotPresent, or Never to choose one behavior for every image; it also applies to Kubernetes pods and operator-managed Terminals. Running workspaces keep their image until they restart.
• Kubernetes workspaces start again. Terminal and reset pods were created with an invalid field and failed on every start.

Breaking changes for administrators and integrations

Policies are now templates. Replace per_chat, per_automation, and connection-level allocation settings with the template's data.scope. Templates are the items users select and share; there is no separate named-workspace resource or resolve request.

WebUI connects using the Terminals server key. It checks permissions and sends the verified user, chat, and model IDs. Terminals no longer asks WebUI to validate user tokens. Remove TERMINALS_OPEN_WEBUI_URL and TERMINALS_TOKEN_CACHE_TTL from your settings. WebUI user JWTs no longer authorize managed terminal requests.

Execution uses headers instead of policy-prefixed URLs. Stop using /p/{policy_id}/.... HTTP and WebSocket requests use X-Terminal-Template-Id and X-User-Id, plus X-Terminal-Chat-Id or X-Terminal-Model-Id when required. /openapi.json uses the same server key and verified user/chat/model context as execution, and uses the selected instance. Caller-selected X-Terminal-Context-Id values are rejected. Scope is read from the current template on each request; clients do not send or store a scope override.

Saved selections use template:<connection-id>:<encoded-template-id>. Update saved selections and permissions together. Reusing an old display name does not reconnect them.

The API changes are:

There is no replacement for bulk idle-only refresh or whole-user cleanup. The status response also drops active terminal and WebSocket counts, and the global idle and maximum-lifetime settings. Update clients that read these fields.

Environment APIs sit below /api/v1/terminals/templates/{id}:

Supply the user, chat, or model IDs needed by the template. Terminals uses the stored scope to choose the workspace; callers do not choose a instance address.

Container names and file locations change. They now depend on the template and its scope, so chat and model workspaces no longer depend on who opened them first. Copy existing files to their new locations during migration. On Kubernetes, update the operator and CRDs too: the Terminal resource uses spec.templateId instead of spec.userId. Update custom manifests that create these resources.

Existing databases do not upgrade at server startup. Migrate them explicitly or use the fresh-installation route below. Fresh databases still initialize automatically. Reverting the image alone cannot undo a migration.

Moving to 0.4.0 manually

You do not need a migration script. Set up a fresh 0.4.0 installation, recreate your templates, and copy your files. A script can help with larger installations, but it is optional.

This route uses a new Terminals database. It keeps the files and settings you transfer, but starts new activity and reset histories. Keep your old installation and backups until you have checked the new one.

1. Make a list of what needs to move. Record policies, reset schedules, connection settings, permissions, and saved terminal selections. For each workspace, note its old user/chat/automation, file location, and intended new template and scope. Check actual container or pod mounts to find the files, including storage from stopped terminals. Export any needed files stored only inside a container before removing it.

2. Stop writes and back up. Restrict WebUI access, pause automations, and stop old terminal workloads and services. Make sure an operator cannot recreate them. Back up both databases, settings, and file storage. Stopping the Terminals service alone does not stop its containers or pods. Stop WebUI while taking its database backup too.

3. Start a separate 0.4.0 installation. Set TERMINALS_DATABASE_URL to a new, empty database. Keep the old database untouched; do not mark it as migrated. For Docker, choose a new TERMINALS_DOCKER_DATA_DIR and matching host path if needed. For Kubernetes, use separate destination storage and preferably a separate namespace, with the matching operator and CRDs. Start the matching WebUI version with access limited to migration administrators. Connect using the Terminals server key and remove the old JWT settings.

4. Recreate templates and access. Use New terminal in WebUI or the template API. Copy the old image, environment variables, resource limits, storage, network, and security settings. Preserve server defaults and who can access each connection and template. Creating a template through the Terminals admin API does not create WebUI permissions. Record the new IDs. Keep scheduled resets disabled until the files are copied and checked.

5. Prepare each new workspace. Open it with the correct existing user, saved chat, or model and run a harmless command. This creates its storage and tracking record. For Chat scope, select the template on the existing chat; making a new chat changes which workspace it uses. Get the instance id from GET /api/v1/terminals/templates/{id}/instance, supplying user_id and the relevant chat_id or model_id. This status request alone does not create a workspace. Record its storage mount. Use Restart to stop the terminal while keeping files, confirm it has stopped, block reconnections, and stop the new Terminals service during copying. Do not use Reset or Delete here.

6. Copy and check files. On Docker, copy the old home contents into .terminals/<instance-id> under the new data directory. Use the matching Docker-host directory if a host path override is configured. Include hidden files and preserve ownership, permissions, and symlinks. On Kubernetes, use temporary pods to copy between the old and new PVCs, with the source mounted read-only and the PVC access rules respected. Shared PVCs use .terminals/<instance-id>; for dedicated PVCs, use the new terminal's recorded home mount. Copy extra persistent mounts where needed. Compare file contents or checksums and file metadata before starting the terminal again.

7. Update saved terminal choices. Select the new templates in chats, automations, folders, model settings, and connection defaults. Update template permissions too. Use WebUI's controls where available. If a saved choice has no editor, update that specific record in a backed-up WebUI database while WebUI is stopped. Follow your old-to-new list; do not globally replace policy IDs. A matching name does not transfer saved selections or permissions.

8. Check before letting users back in. Test with the affected users. Confirm files are present, personal files stay private, shared chats use the same workspace, and models and automations use the right templates. Check that stopped workspaces remain listed and that saved choices no longer point to old workspaces. Restore reset schedules and resume automations after these checks. Keep the old files, databases, and your migration notes for rollback.

When choosing scopes, keep these cases in mind:

• Old personal workspaces: choose User, even if the old settings did not explicitly say “per user.” None would share the workspace with everyone who can use that template.
• Different files for people in the same chat: use the chat owner's files for the new shared chat workspace. Keep everyone else's files in separate private templates. Do not merge their folders.
• Old automation workspaces: create ordinary templates for them and select those templates in the automations.
• Different connection rules or shared folders: use separate templates where the old rules differ. If old workspaces used one folder, give each new workspace its own copy before allowing separate reset or deletion.

If you want to start with empty workspaces, skip copying old files and settings. Keep a backup, create the new templates and permissions, and still update WebUI's saved terminal choices.

Database migration command

terminals db upgrade applies schema migrations to fresh or empty databases. It does not copy files or rewrite WebUI data. Populated pre-0.4 databases are rejected before migration 004 changes their tables. Use the manual migration above, retaining the old database and storage.

Going back to the old version

Stop the new services and workloads. Restore the pre-migration WebUI database and settings, then run the old Terminals and WebUI versions against the retained old databases and storage. Restore the old operator and CRDs where needed.

Files changed after users start using 0.4.0 are not in the old backups; recover those changes separately if needed. Keep access restricted until migration checks pass so rollback is simpler.