All articles

November 18, 2026 / 14 MINUTES READ

What is Open Terminal, the computer your model works on in Open WebUI

What is Open Terminal, the computer your model works on in Open WebUI
SUMMARY

Open Terminal is our free, open-source program that gives the model in Open WebUI a computer to work on: a shell, files, a browser, and a desktop on a machine you choose. The guide explains what the model can do with it and how it differs from the code interpreter, then walks through every step with a video: starting it with Docker, connecting it in Open WebUI, giving the model a job, using the files and terminal beside the chat, adding a coding agent such as Codex or Claude Code, and turning on approvals. It ends with fixes for the problems people hit most.

Open Terminal is a free, open-source program we built that gives the model in Open WebUI a computer to work on. You run it on a server, in a container, or on your own laptop, and connect it to Open WebUI. The model can then run commands, read and edit files, write and run code, and use a browser and a desktop on that machine, and you see each command, its output, and every file it changed beside the chat.

Without it, a model can only tell you what to do. With it, the model does the work and checks it. Ask it why a test fails, and it runs the test, reads the error, fixes the code, and runs the test again. Ask it to clean up a spreadsheet, and it opens the file, writes the script, and saves a new copy you can open next to the chat.

This guide explains what that means, then takes you from an empty server to a working setup, one step and one video at a time: starting Open Terminal, connecting it, giving the model its first job, adding a coding agent such as Codex or Claude Code, and choosing what needs your approval. If you get stuck, the last section covers the problems people hit most.

What the model can do with it #

Anything you'd do at a computer with a terminal, the model can now do for you, and show you how it did it. Some things we ask ours:

  • Answer questions about real files. "Which customers in this export haven't placed an order since March 1?" The model loads the file, writes the query, runs it, and saves the list as a spreadsheet you can open.
  • Fix and test code. "Find out why the build fails and fix it." It runs the build, reads the error, changes the code, runs the build again, and commits when it passes.
  • Check its work in a browser. "Start the site and tell me if the signup page looks right on a phone." It starts the server, opens the page, and looks at it.
  • Turn documents into other documents. "Convert these Word files to PDF and put them in one folder." The default image comes with LibreOffice.
  • Look after the machine. On one of our own PCs, we asked how much space was left on each drive. The answer started with a warning we hadn't noticed: the system drive was 96% full.

The files stay on the machine. The script the model wrote on Monday is still there on Friday, and so is the report it made, for you or, on a shared machine, for the next person who asks. Coding agents such as Codex and Claude Code can run on the same machine and show up in the model picker, which step 5 sets up.

How it's different from the code interpreter #

Open WebUI also has a code interpreter, and people often ask which one they need.

Code interpreterOpen Terminal
What runsPython codeAny command, in any language
WhereIn your browser, or on a Jupyter serverOn a machine you choose
SoftwareWhat that engine hasWhatever the machine has, and the model can install more
Browser and desktopNoYes
A machine a team shares, files includedNoYes
Coding agentsNoYes

The code interpreter is good for a quick calculation or a chart. Open Terminal is for work that needs a real machine: a repository, a folder of files, a program to install, or a result someone else will pick up later.

How it works #

Open Terminal is a small server that runs on the machine and offers it to Open WebUI over an HTTP API, protected by an API key. When you select a machine in a chat, Open WebUI gives the model tools for it: run a command, read a file, edit a file, search, use the browser. When the model calls one, Open WebUI's server sends the request to Open Terminal, and the result comes back into the chat.

Two things follow from that. Open WebUI's server, not your browser, has to be able to reach Open Terminal, which matters when you pick the address in step 2. And the model needs to be good at calling tools, because work on a computer is a long run of them. On our own hardware, we've used qwen3.8:27b in Ollama on one 24 GB GPU.

Set it up, step by step #

The videos follow a small made-up team at Larkspur, an outdoor-gear store: one person runs their Open WebUI, and a colleague uses it. We recorded every step on Open WebUI v0.13.4 with Open Terminal 0.17.20.

What you need #

  • An Open WebUI you're an administrator on.
  • A machine with Docker that Open WebUI's server can reach. We'd start on the same machine as Open WebUI, because it's the easiest to connect.
  • A few gigabytes of disk for the image, plus whatever files the model will work on.
  • A model that's good at calling tools.

1. Start Open Terminal #

On the machine, run this. Replace your-secret-key with a long random string first. openssl rand -hex 24 makes one.

Bash
docker run -d --name open-terminal --restart unless-stopped \
  -p 8000:8000 \
  -v open-terminal:/home/user \
  -e OPEN_TERMINAL_API_KEY=your-secret-key \
  ghcr.io/open-webui/open-terminal:latest

Maya starts Open Terminal on the server with one command, then checks that it answers

What each part does:

PartWhat it's for
-d --name open-terminalRuns it in the background, under a name you'll use later
--restart unless-stoppedStarts it again after a reboot
-p 8000:8000Makes its API reachable on port 8000
-v open-terminal:/home/userKeeps the machine's files in a Docker volume, so they survive updates and restarts
-e OPEN_TERMINAL_API_KEY=...The key Open WebUI will use. Anyone with it can run commands on the machine
ghcr.io/open-webui/open-terminal:latestThe full workstation image, with Python, Node.js, build tools, a browser, a desktop, and document tools

The first run downloads the image, which takes a few minutes. Then check that it answers:

$ curl localhost:8000/health

It prints {"status":"ok"}. If it doesn't yet, wait a few seconds and try again, or read docker logs open-terminal.

2. Connect it to Open WebUI #

First, work out the address Open WebUI's server will use to reach it:

Where Open WebUI runsAddress
Installed directly on the same machine, for example with piphttp://localhost:8000
In Docker on the same machinehttp://open-terminal:8000, after putting both containers on one network (below)
On another machinehttp://<this machine's address>:8000

Inside a container, localhost means that container, so with both in Docker, connect them to a shared network once. Use your Open WebUI container's name in place of open-webui:

Bash
docker network create openwebui
docker network connect openwebui open-webui
docker network connect openwebui open-terminal

Then, in Open WebUI:

  1. Click your name at the bottom of the sidebar and choose Settings.
  2. Scroll down to the Admin settings and choose Integrations.
  3. In the Terminal section, click + next to Open Terminal.
  4. Give it a name your team will recognize, enter the address as the URL, leave Auth on Bearer, and paste your key.
  5. Click Verify Connection, the circular arrows next to the URL. You'll see Server connection verified.
  6. Open Access and choose who can use it. Public gives it to everyone, or use Add Access for specific people and groups. Until you do, only administrators can use it.
  7. Click Save. The connection is on as soon as it's saved.

Maya adds the connection in Integrations, verifies it, makes it available to everyone, and saves it

Everyone you share it with works on the same machine and the same files. That's what you want for a small team: one person's model leaves a report, and the next person's model picks it up.

3. Give the model a job #

Now anyone with access can use it. In a new chat:

  1. Click the cloud icon in the message input, the terminal menu, and choose your machine.
  2. Ask for something that needs a real computer:

Which customers in exports/orders-2026.csv haven't placed an order since March 1? Save them to lapsed-customers.xlsx with their last order date and total spend.

Each command the model runs appears in the conversation, with its result. When the model makes a file, it can open it in a tab for you. Click Split screen to put the chat and the file side by side.

Priya picks the Larkspur workbench and asks which customers haven't ordered since March 1. The model runs the commands, saves a spreadsheet of 87 customers, and opens it beside its answer

4. Look around the machine #

You don't have to go through the model. Click + in the tab bar to open more of the machine beside the chat:

TabWhat it's for
FilesBrowse the machine's files, preview them, and edit spreadsheets, Markdown, and code in place. Its Git panel shows the changes in a repository, with commits, branches, and pull requests
New TerminalA real shell on the same machine, for when you want to type a command yourself
BrowserThe browser the model uses, so you can watch it work
DesktopThe machine's desktop, for apps that open windows

Priya opens the machine's files beside the chat, previews the order export, and runs two commands in a terminal tab herself

5. Add a coding agent #

Coding agents such as Codex and Claude Code can work on the same machine, in the same files. Once one is installed and signed in there, it shows up in the model picker for everyone who can use the machine, and nobody installs anything on their own laptop.

The agents image comes with Codex and Claude Code. Swap the container for it. The volume keeps your files:

Bash
docker rm -f open-terminal
docker run -d --name open-terminal --restart unless-stopped \
  -p 8000:8000 \
  -v open-terminal:/home/user \
  -e OPEN_TERMINAL_API_KEY=your-secret-key \
  ghcr.io/open-webui/open-terminal:agents

If you connected the containers to a network in step 2, run docker network connect openwebui open-terminal again, because the new container starts outside it.

Then sign an agent in. We used Codex with an API key for the videos. For Codex with an OpenAI API key, pipe the key in from your shell so it never appears on screen:

$ printenv OPENAI_API_KEY | docker exec -i open-terminal codex login --with-api-key

To sign Codex in with a ChatGPT account instead, run docker exec -it open-terminal codex login --device-auth and follow the link. Device login has to be enabled in your ChatGPT account or workspace. For Claude Code, run docker exec -it open-terminal claude and follow the prompts, or add -e ANTHROPIC_API_KEY=... to the docker run command.

Maya swaps in the agents image, keeping the files, and signs Codex in with an API key

In a chat, pick the machine in the terminal menu, then open the model picker and search for the agent. Agents appear as the agent and its model, such as codex/gpt-6.1-sol. Give it a job, and its steps and file changes stream into the chat like any other model's.

Write a script, lapsed.py, that saves every customer in exports/orders-2026.csv with no order since a given date to lapsed-customers.xlsx. Run it for March 1 and tell me how many customers it found.

Priya picks Codex in the model picker. It writes lapsed.py, runs it, finds the same 87 customers, and the script opens beside its answer

Agent chats are saved chats, so leave Temporary Chat off. Codex, Claude Code, Cursor, Grok, OpenCode, Cline, Gemini CLI, Pi, Hermes, Antigravity, GitHub Copilot, Goose, and Qwen Code are all supported once they're installed and signed in, and any other agent that speaks the Agent Client Protocol can be added with OPEN_TERMINAL_ACP_AGENTS. The agent's sign-in lives on the machine, so everyone who can use the machine uses that account.

6. Decide what needs your approval #

By default, the model runs its tools without asking. We'd turn approvals on before you share a machine that holds anything you'd hate to lose. To have it ask first:

  1. As an administrator, open Settings, then Interface under the Admin settings, and turn on Tool Permissions.
  2. Click Save. Open WebUI shows the change, Off to On, and asks you to confirm. Click Save again.
  3. In a chat, click + in the message input, choose Tool Permissions, and pick Ask for approval. Full access runs everything without asking.

From then on, each step waits in the chat with Allow and Deny. When the model has already taken a few steps, the request sits on the summary line for the group, such as "Ran 1 command, Listed 2 directories". Click that line to see the exact command before you allow it.

Maya turns on Tool Permissions, picks Ask for approval, and allows the command that moves the November inventory export into an archive folder

If something doesn't work #

What you seeWhat to do
Verify Connection failsCheck the address from inside Open WebUI's server, not your browser. With both in Docker, localhost is the wrong address: use the container name on a shared network, as in step 2. Check that the key matches OPEN_TERMINAL_API_KEY exactly
Other people don't see the machine in the terminal menuOpen the connection in Settings > Admin > Integrations and share it under Access. Make sure its switch is on
The model talks about commands instead of running themUse a model that's good at calling tools, and check that the machine is selected in the terminal menu of this chat
An agent doesn't appear in the model pickerSelect the machine first. Check that the agent is installed and signed in on that machine, which the agents image and the step 5 sign-in take care of, and that Temporary Chat is off
The connection stopped working after you replaced the containerIf Open WebUI is in Docker, connect the new container to the shared network again
Files are gone after an updateAlways start the container with the same -v open-terminal:/home/user volume. The files live there, not in the container

Where it can run #

Open Terminal is the same program everywhere. What changes is whose machine it's on.

WhereHowGood for
A container next to Open WebUIThe docker run command aboveA team sharing one machine and its files
A server or VMpip install open-terminal, then open-terminal runA machine with the hardware or data you need, such as a GPU
Your own laptopTether, our desktop app, which installs Open Terminal for youWork that's already on your computer, reachable from any browser
One for each person, chat, or modelTerminals, which starts a container for eachTeams where people need machines of their own

Besides latest and agents, there's a cuda image with GPU-enabled PyTorch, and slim and alpine images with only a minimal shell. We'd start with Docker. It keeps the model's commands inside a container, and it takes one command to try. Tether is for work that's already on your laptop, and Terminals is for when one shared machine isn't enough.

Is it safe? #

Open Terminal runs real commands, so it's worth knowing what it can reach.

  • The model can do what the machine allows. In a container, that's the container. Installed directly on a computer, commands run with that user's permissions, so the model can reach what you can.
  • The API key is the key to the machine. Anyone with it can run commands and read files. Keep it to Open WebUI's server, keep port 8000 reachable only from there, and share the connection in Open WebUI rather than the key.
  • You can approve each step. Turn on Tool Permissions, as in step 6, and choose Ask for approval.
  • Everyone on one machine shares it. People you give the same machine see the same files and running programs, and use the same signed-in agents. Open Terminal's multi-user mode gives each person their own folder, but it isn't a security boundary, so it's for small teams who trust each other. For machines that keep people apart, use Terminals.

The Open Terminal docs cover every setting, and Put your model to real work in Open WebUI shows what we did once ours was connected.

The Open WebUI Team

AI on your terms.

Your models. Your data. Your infrastructure.