Terminals is a service you run next to Open WebUI that gives each person, chat, or model its own sandboxed computer, where a model can run commands, edit files, and show the results beside the chat. People make these computers from the chat, with the project already on them, and IT sets images, resources, and networks once. The post explains what Terminals is and how it works, what different teams do with it, and what an organization decides before rolling it out.
Terminals gives everyone on your team their own computer in Open WebUI. It's a service you run on your own servers, next to Open WebUI, that starts a separate, sandboxed computer for each person, chat, or model that needs one. People make these computers from the chat, and IT sets the limits once.
If you haven't used a computer in Open WebUI yet, here's what that means. A model in Open WebUI can work on a real computer. Give it a spreadsheet, and it writes and runs Python against the file. Give it a code repository, and it runs the tests, fixes what fails, and commits the change. You see each command, its output, and the files it changed beside the chat. What is Open Terminal, the computer your model works on in Open WebUI explains it in more depth.
Most teams start with one of these computers, and everyone shares it. Every file anyone makes is in everyone's file browser, and every program anyone starts runs next to everyone else's. Giving each person a machine of their own meant someone in IT setting one up for each of them. With Terminals, one setup gives each person, each chat, or each model its own machine, with the project already on it.
We'll explain what Terminals is, how it works, and what your team can do with it. If you're the one deciding whether to roll it out, What to decide before you roll it out covers who gets their own machine, what each person can reach, where the files live, what it costs to run, and who's allowed to make computers.
The short version #
- A computer from the chat. New terminal in the terminal menu makes a sandboxed Linux machine with the image, resources, and setup you choose.
- One for each person, chat, or model. One setup gives each of them its own machine and files, and people you share a chat with work in the same one.
- Ready when it starts. A setup script clones your project and installs its dependencies before the first command runs.
- Runs on your servers. Every machine is a container on your Docker host or Kubernetes cluster, and the files stay there.
- Limits you set once. Allowed images, CPU, memory, disk, networks, idle shutdown, and who can make computers.
Terminals 0.4.2 needs Open WebUI 0.13.4 or later. Setup scripts and start directories need Open Terminal 0.17.7 or later in the image, which the default image already has.
What Terminals is #
We make three pieces that give a model a computer, and they fit together.
| What it is | Use it when | License | |
|---|---|---|---|
| Open Terminal | One computer for your models. A program running in a container or on a server that lets a model run commands, manage files, and use a browser and desktop | A person or a small team can share one machine | Free and open source (MIT) |
| Terminals | A service that runs many Open Terminal computers for you, starting a separate one for each person, chat, or model that needs it | People need their own machines, and IT needs to manage them | Free for personal use. Organizations need an Enterprise License |
| Tether | Our desktop app that connects a person's own laptop to Open WebUI | The work already lives on someone's laptop | Free for personal use. Organizations need an Enterprise License |
In Open WebUI, all three look the same. They're machines in the terminal menu of the message input. Select one, and the model works on it, with a file browser, a terminal, a Git panel, and a desktop in tabs beside the chat.
Terminals is for the point where one shared machine stops being enough, and setting one up per person by hand is too much.
How it works #
Open WebUI → Terminals → a container for each person, chat, or model A terminal in Terminals is a set of instructions for making machines: the image, the resources, the network, the setup script, and who gets their own copy. When someone selects it and sends a message, Open WebUI checks that they have access, then tells Terminals who they are, which chat they're in, and which model they're using. Terminals picks the machine that matches, starts it if it isn't running, and passes the request on.
Each machine is a container running Open Terminal, on your Docker host or Kubernetes cluster. Its home folder is kept on your storage, so a machine can stop when nobody's using it and start again later with its files where they were.
Set up Terminals #
There are two ways to run it, and they don't change anything people see in Open WebUI.
| Docker | Kubernetes | |
|---|---|---|
| Use it when | One server is enough: a team, a pilot, or a lab | Many people, more than one machine, or a platform team already runs a cluster |
| Where computers run | Containers on the same server as Terminals | Pods spread across your nodes, including GPU nodes you pick with node selectors |
| Disk limits | Only with some storage drivers, and not on home folders | Each computer gets its own volume of a fixed size |
| Network rules | You pick a Docker network and add firewall rules | NetworkPolicies per computer |
| What Terminals needs | The Docker socket, which controls every container on that server | A service account, with no access to a Docker socket |
| Setup | Four commands, below | The operator and a deployment, below |
We'd start on Docker, and move to Kubernetes once one server isn't enough or your security team wants each computer fenced off. Templates and access are set up the same way in Open WebUI either way, but files don't move between the two by themselves.
You need Open WebUI 0.13.4 or later and an administrator account. Terminals is free for personal, non-commercial use. Using it in an organization requires an Open WebUI Enterprise License with Terminals access.
With Docker #
One docker run for Terminals, and the key it made
On the machine that runs Open WebUI, first put Terminals and Open WebUI on one network. This assumes your Open WebUI container is called open-webui; docker ps shows yours.
docker network create open-webui-terminals
docker network connect open-webui-terminals open-webuiThen start Terminals and print its key:
docker run -d --name open-webui-terminals --network open-webui-terminals --restart unless-stopped \
-e TERMINALS_API_KEY=$(openssl rand -hex 32) \
-e TERMINALS_DOCKER_NETWORK=open-webui-terminals \
-e TERMINALS_DOCKER_HOST_DATA_DIR=$HOME/open-webui-terminals/terminals \
-v $HOME/open-webui-terminals:/app/data \
-v /var/run/docker.sock:/var/run/docker.sock \
ghcr.io/open-webui/terminals:0.4.2
docker exec open-webui-terminals printenv TERMINALS_API_KEYYou'll paste that key into Open WebUI in a moment. Everyone's files are kept in open-webui-terminals in your home folder.
On Kubernetes #
Kubernetes is where we'd run Terminals for an organization. Each computer gets its own persistent volume with a size that's enforced, NetworkPolicies decide what each computer can reach, the computers spread across your nodes, and Terminals itself never touches a Docker socket. It runs on OpenShift too.
Terminals comes with an operator for this. From a checkout of the Terminals repository:
kubectl apply -f manifests/terminal-crd.yaml
kubectl apply -f manifests/operator-deployment.yaml
kubectl -n terminals create secret generic terminals --from-literal=api-key="$(openssl rand -hex 32)"Then deploy the ghcr.io/open-webui/terminals:0.4.2 image as the Terminals service, with these settings, a persistent volume at /app/data, and a Service on port 3000 that Open WebUI can reach:
env:
- name: TERMINALS_BACKEND
value: kubernetes-operator
- name: TERMINALS_KUBERNETES_NAMESPACE
value: terminals
- name: TERMINALS_API_KEY
valueFrom:
secretKeyRef:
name: terminals
key: api-keyThe Terminals README has the service account permissions, the direct kubernetes backend that needs no operator, and the OpenShift guide. In Open WebUI, use the Service's address, such as http://terminals.terminals.svc:3000, in the next step.
Connect it in Open WebUI #
Maya adds Terminals under Integrations, verifies it, gives the Engineering group access, and the terminal menu offers New terminal
- Click your name at the bottom of the sidebar and choose Admin Panel. Open Settings, then Integrations.
- Under Terminal, click the + next to Open Terminal.
- Enter a Name, such as "Team computers", and
http://open-webui-terminals:3000as the URL. Leave Auth on Bearer, and paste the key. - Click the circular arrows to verify. You'll see "Server connection verified", and the dialog says "Create and configure terminals from the terminal selector."
- Open Access and click Add Access. Give Read to the groups who should use computers, and Write to the people who should make them. Until you add someone, only administrators can.
- Click Save. The connection is on.
Make your first computer #
In a new chat, click the cloud button in the message input, then the + next to Terminals. Name it "Sandbox", click Create, and ask the model to do something on it, such as "Check which version of Python is installed." The computer starts with your first message, and the very first start takes longer while Docker downloads the image.
Pro tip, optional: a folder per project. Make a folder in the sidebar and, under Advanced, set its Default terminal. You can also set the Working directory, a Default Model, a System Prompt, and Knowledge there. Then choose Share from the folder's menu and add your team. Every new chat in that folder starts on that terminal, so nobody has to pick one, and with a per-User terminal each person still lands on their own copy. To share folders, people need the Folders Sharing permission, which administrators have and users don't by default.
Priya makes a Checkout folder with Checkout service as its default terminal and shares it with Engineering; Sam opens it, and his first message runs on his own copy
Set the limits #
Terminals reads its limits when it starts. To add some, remove the container with docker rm -f open-webui-terminals and run the docker run command again with more -e lines. Put the key you saved in place of $(openssl rand -hex 32), so Open WebUI can still connect. Everyone's files stay in open-webui-terminals in your home folder.
-e TERMINALS_MAX_CPU=2 \
-e TERMINALS_MAX_MEMORY=4Gi \
-e TERMINALS_IDLE_TIMEOUT_MINUTES=30 \
-e 'TERMINALS_ALLOWED_IMAGES=ghcr.io/open-webui/open-terminal:*' \What to decide before you roll it out explains which limits we'd set and why, and the Terminals README lists every setting.
If something doesn't work #
| What you see | What to check |
|---|---|
| Verify fails in Open WebUI | Terminals and Open WebUI aren't on the same network, or the URL uses localhost, which inside a container means the container itself. Use http://open-webui-terminals:3000 |
| There's no New terminal in the terminal menu | You need Write on the connection. Administrators have it |
| The first message on a new computer is slow | Docker is downloading the image. Later starts are quick |
| A setup script failed | Click the ⋯ next to the terminal and open System info for the end of its log |
| A computer's log says "No space left on device" | Docker's disk is full. docker system df shows what's using it |
| Files are gone after Terminals restarted | The -v $HOME/open-webui-terminals:/app/data line has to point at the same folder every time |
| Anything else | docker logs open-webui-terminals shows what Terminals is doing |
Make a computer from the chat #
We made it so people create these computers where they already work. Open the terminal menu in the message input, click New terminal, and fill in a name. Under Advanced, you can pick the image, CPU, memory, storage, network, environment variables, start directory, and setup script, or leave them on the server defaults your administrator set. Click Create, and it's in your terminal menu.
Priya makes Checkout service from the chat, with a machine for each person and a setup script that clones the project, and the model runs the tests on her new machine
Try it. Once your administrator has connected Terminals and given you Write access to it:
- Open the terminal menu in the message input and click New terminal.
- Enter a name. Leave Separate instances off for now.
- Click Create, then select the new terminal.
- Ask the model to do something on it:
Check which version of Python is installed, then write a script that prints the ten largest files in the home folder and run it.
The machine starts with the first thing you ask. The first start can take a minute while the image downloads.
One setup, a machine for each person, chat, or model #
Turn on Separate instances and choose what gets its own copy. Each copy is its own container, with its own files and running programs, and every copy uses the settings you gave the terminal.
| Separate instances | What you get | Good for |
|---|---|---|
| Off | One machine for everyone with access | A small group working on the same files |
| per User | Each person gets their own machine, kept across all their chats | Day-to-day work, such as each engineer's copy of a repository or each analyst's notebooks |
| per Chat | Each saved chat gets its own machine, shared by everyone who can reply in it | Experiments that shouldn't touch each other, and handing a task to a teammate |
| per Model | Each model gets its own machine, shared by every chat and person using it | A team assistant that keeps its scripts and outputs between uses |
This is the part we're most excited about. You set a terminal up once, the way a project needs it, and the copies take care of themselves. Change the image or the memory later, and every copy picks it up the next time it starts. Nobody files a ticket, and nobody's files land in someone else's folder.
Sam fixes the coupon rounding on his copy of Checkout service and all five tests pass, while Priya's copy still has its two failures
To change which copies a terminal makes, delete its instances first, because their files belong to the old choice.
Start every machine with the project on it #
The Setup script runs in the start directory each time a machine starts, before it's ready. Only the home folder is kept between restarts, so write the script so it's safe to run again:
test -d .git || git clone https://github.com/your-org/app .
npm installSet Start directory to ~/app, and every chat, shell, and command on that machine starts inside the project. The script runs in that folder, which is why it clones into .. Make the terminal a folder's Default terminal, under Advanced when you edit the folder from the sidebar, or a model's Default terminal in its settings, and new chats start there without anyone picking it.
To give everyone a coding agent too, set Image to ghcr.io/open-webui/open-terminal:agents, which comes with Claude Code and Codex, and add ANTHROPIC_API_KEY under Environment variables. Each person with a per-User copy then has Claude Code in the model picker, on their own machine, with nothing installed on their laptop.
If a setup script fails, the machine still starts. Click the ⋯ next to the terminal in the terminal menu and open System info to see that it failed, with its exit code and the end of its log.
Hand a chat to a teammate, machine and all #
With Separate instances per Chat, every conversation gets a clean machine. Share the chat with Allow replies, and the people you share it with work in that same machine. Your teammate opens the chat, sees every command the model ran and what came back, and their next message runs on the same files, exactly as you left them. Sub-agents work in the same machine as the chat that started them. A chat shared as a read-only snapshot gives nobody access to its machine.
Sam has the model write a refund script on a per-Chat machine and shares the chat with Priya, whose message runs it on the same machine
Try it.
- Make a terminal with Separate instances per Chat, and select it in a new chat.
- Send a first message. The machine for this chat starts with it.
- Open the chat menu, choose Share, click Add Access, and pick a teammate. Set Sharing mode to Allow replies.
- Your teammate opens the link and replies. Their commands run on the same machine.
Give a model a computer of its own #
Per Model gives a model one machine that stays with it. Make a custom model in Workspace > Models, give it instructions and knowledge, and set its Default terminal to a per-Model terminal. A weekly reporting assistant can then keep the scripts it wrote last month and run them again for whoever asks next. We told ours, in its instructions, to keep its scripts in ~/reports and check there before writing a new one. Everyone who uses the model shares its machine, so keep it for work the whole team should see.
The Weekly refunds model saves its script on its own machine in Priya's chat, then finds and runs it when Sam asks in his
Share a computer with your team #
A new terminal is private until you share it. Click the ⋯ next to it in the terminal menu, choose Terminal settings, and click Access to add people or groups. The label next to its name changes from Private to Shared. For a per-User terminal, each person you add gets their own copy.
What it looks like for your team #
The same terminal works very differently depending on what your team does all day. Find yours.
If you build software #
We use Terminals for the actual engineering on Open WebUI, and the way we work is simple. Most of it happens on one terminal the team shares, with Separate instances off, so everyone works in the same files and can pick up where someone else stopped. When one of us wants to try something without touching that machine, we make a throwaway terminal, use it, and delete it when we're done. It takes a name and a click, so starting over on a clean machine costs nothing.
That's where we'd start too. Make the shared terminal on the agents image, which comes with Claude Code and Codex, with ~/app as the start directory and a setup script that clones your repository and installs its dependencies. Add ANTHROPIC_API_KEY for Claude Code and a GH_TOKEN for the GitHub CLI, which the Git panel uses for issues and pull requests, and make it the default terminal of your team's folder.
Check out pull request 482, run the test suite, and tell me what the change does and anything it breaks.
Throwaway terminals are where coding agents earn their keep. Claude Code on a laptop can reach everything its owner can: SSH keys, browser sessions, every other repository. On a throwaway machine, it reaches that machine's files, the keys in its environment, and the network you gave it, and when you delete the terminal, all of it goes. That makes us much more comfortable letting an agent work through a long task without approving every step.
As the team grows, the same setup scales without anyone setting up machines. Turn on Separate instances per User, and each engineer gets their own copy, with the same repository, dependencies, and toolchain. A new engineer's first question can be about the code, not the setup:
Walk me through how a request reaches the database in this repository, and run the tests for that path.
If you work with data #
Analysts usually end up with copies of the same data on every laptop, or one shared machine where everyone's notebooks and half-finished outputs sit side by side. Make a per-User terminal on an image with your team's Python libraries instead. Your administrator can mount a shared, read-only data folder into the machines, with TERMINALS_DOCKER_MOUNTS on Docker or a volume in the terminal's pod settings on Kubernetes, and give the terminal a network without internet access for sensitive data.
Each analyst then has their own machine, the same data in the same place, and their own scripts and outputs. The model writes and runs the analysis on the real files, and the code it used stays on the machine for the next person to check.
Load the March orders in /mnt/data, find the ten customers whose monthly spend dropped the most since January, and make a chart I can paste into a slide.
If you run the same reports every week #
For a team that isn't writing code, the best fit is often a model with a computer of its own. Make a custom model for the job, such as the weekly sales summary, with the instructions and knowledge it needs, and give it a per-Model terminal. The first time, it writes the scripts to do the job. After that, whoever on the team asks next gets a model that already has those scripts on its machine, and it can update the spreadsheet in place, which you can open and fix beside the chat.
Here's this week's export. Update the summary sheet the way you did last week, and tell me what changed most.
If you teach a class #
Give every student the same machine for the course with a per-User terminal on an image that has the course's tools, and a setup script that downloads the starter files. Nobody spends the first lab installing things, and every student's work is kept apart. Schedule a reset in the Terminals admin UI for the end of term, and the files are cleared on that date. The image and the course stay ready for next year.
I'm getting an import error when I run lab3.py. Explain what it means and help me fix it without giving me the whole answer.
If you run IT for all of them #
Every one of these is a terminal on the same Terminals service, with its own image, limits, network, and access. The next section is for you.
What to decide before you roll it out #
Terminals puts real computers in the hands of everyone you give access to, and the models working for them. That's what makes it useful, and it's why these decisions are worth an hour before the first team starts.
Who gets their own machine #
We'd start from the work, not the setting.
| If you need | Choose | Keep in mind |
|---|---|---|
| People's work kept apart from their coworkers' | per User | Each person's copy uses memory and disk while it runs, so set limits |
| A clean slate for each task, and handoffs between people | per Chat | Files stay with the chat, so schedule resets if chats pile up |
| An assistant that remembers its work between people | per Model | Everyone using the model sees its files |
| A small group on the same files | Off | Everyone sees everything on it |
What each person can reach #
- Everything on their machine. Anyone with access to a terminal can run any command on it and read every file on it. That's the deal with a real computer, and it's why per-User and per-Chat copies matter.
- The environment variables. Keys you add under Environment variables can be read by anyone using the terminal. We'd use keys made for that purpose, with their own spending limits and permissions, never an administrator's.
- The network you give it. A machine can reach whatever its Docker network or Kubernetes cluster lets it reach, which usually includes the internet.
TERMINALS_NETWORK_PROFILESlets a terminal choose a named network, such as one with no internet access for sensitive data. A profile picks the Docker network or Kubernetes labels. Your firewall rules or NetworkPolicies do the blocking. - The images you allow.
TERMINALS_ALLOWED_IMAGESlimits which images people can choose, so every machine starts from something you've approved. - Not other people's machines. Separate instances are separate containers with separate files. The exception is the people you give Write access, below.
Two things protect the service itself. The Terminals API key controls every machine, and Terminals trusts Open WebUI to say who each request is for, so only Open WebUI should be able to reach it. The quick start binds it to localhost for that reason. And on Docker, Terminals starts machines through the Docker socket, which gives it control of every container on that host. We'd give it a host of its own, or run it on Kubernetes, where it has restricted security settings and an OpenShift guide.
Where the files live, and when they go away #
Each machine's home folder is kept on your storage. On Docker, that's a folder per machine under the data directory you mount. On Kubernetes, it's a persistent volume. Nothing is copied anywhere else.
| Action | What happens to the files |
|---|---|
| Stop, or idle shutdown | Kept. The machine starts again on next use |
| Restart | Kept. The machine starts with the terminal's current settings |
| Reset | Cleared for that machine |
| Delete an instance | The machine and its files are removed |
| Delete the terminal | Every copy and all their files are removed |
We'd put two things on your checklists. Deleting someone's Open WebUI account doesn't delete their machine's files, so add deleting their instances to offboarding. And back up the Terminals database and the terminal files together. For per-Chat terminals, a scheduled reset in the Terminals admin UI, such as weekly, clears old chats' files on a timetable.
The record of what the model did stays in Open WebUI. Every command it ran and its output are saved in the chat on your server, and administrators can open users' chats while ENABLE_ADMIN_CHAT_ACCESS is on, which it is by default.
What it costs to run #
A machine only exists once someone uses it, so nobody who never opens a terminal costs you anything. After that, three settings decide how much you run at once:
- A cap per machine.
TERMINALS_MAX_CPU,TERMINALS_MAX_MEMORY, andTERMINALS_MAX_STORAGEset the most any terminal can ask for. - Idle shutdown.
TERMINALS_IDLE_TIMEOUT_MINUTESstops machines nobody is using and keeps their files. It's off by default, and we'd turn it on. - A maximum lifetime.
TERMINALS_MAX_LIFETIME_MINUTESstops machines after a fixed time, even while in use, and the next request starts a fresh one with the same files.
With idle shutdown on, you size for the people working at the same time, not your headcount. As an example, if each per-User machine is capped at 4 GB of memory and 25 of your 200 people are active at once, plan for about 100 GB, not 800 GB.
Disk is the one that grows, because files are kept. On Kubernetes, each machine gets a volume of the size you set. On Docker, storage limits only apply with some storage drivers and don't cover the home folder, so watch the data directory.
Images change too. On Docker, machines using an image tagged latest check for a newer one at most once an hour. We'd pin a version tag, or set TERMINALS_IMAGE_PULL_POLICY, if image updates need to go through your change process.
Who can make computers #
Access is set on the Terminals connection in Open WebUI, in two levels:
- Read lets people use the terminals that are shared with them.
- Write lets people make terminals, and also see every terminal on the connection, stop, restart, and delete anyone's machine, and open its files.
On a small team that trusts each other, we'd give everyone Write, and people make what they need. In a larger organization, we'd give Write to a platform team or team leads, who make terminals and share them with their teams, and give everyone else Read.
Who needs a license #
Terminals is free for personal, non-commercial use. Using it in an organization requires an Open WebUI Enterprise License with Terminals access.
Look after running machines #
A terminal's Terminal settings list its Instances, including stopped ones. From each one's menu, people with Write access can Stop, Start, or Restart it, delete it with its files, open System info to see its CPU, memory, disk, and processes, and whether its setup script failed, or View files without selecting it in a chat. Restart keeps the files and picks up the terminal's current settings, which is how you roll a new image out to a machine that's already running. Terminals also has its own admin page, which lists every machine across all terminals and sets scheduled resets. Add -p 127.0.0.1:3100:3000 to the docker run command, open http://localhost:3100 on that machine, and paste the key into Server key.
Priya opens Checkout service's settings, sees a machine for her and one for Sam, checks Sam's in System info, and restarts it
How we'd roll it out #
- Start with one team and one terminal. Give it a setup script that clones a repository they work on every day, and share it with that team. A shared terminal is how we work on Open WebUI. Make it per User if the team's work should stay apart.
- Set the limits before the second team. Turn on idle shutdown, cap CPU and memory, and allow only the images you've approved.
- Decide who gets Write. Pick the people who'll make terminals for others, and give everyone else Read.
- Add per-Chat terminals for experiments. Schedule a reset so old chats' files don't pile up.
- Update your checklists. Add instance deletion to offboarding, and the Terminals database and files to your backups.
- Plan for Kubernetes if you'll outgrow one host. Terminals runs there and on OpenShift too, and people make terminals the same way in Open WebUI. Starting there saves moving files later.
Where to start #
Connect Terminals, make one per-User terminal with a setup script for a repository your team works on, and share it with that team. Each person then has their own computer with the project ready, and you set it up once. Tell us how it goes on the issue tracker.
The Open WebUI Team
AI on your terms.
Your models. Your data. Your infrastructure.




