Creating Terminals
A terminal is a ready-made workspace the AI can run commands and work with files in. You create it yourself from the chat, give it a name and decide who can use it. Each terminal starts one or more instances, the containers where the commands run.
Use a terminal when the AI needs a real computer to work on, such as running code, editing files or building a project, and each person or chat needs a clean, separate place for it. One terminal can serve a whole team through a shared group, or give each user, chat or model its own instance so files never mix. Set an image, resources, a start directory and a setup script once and every instance starts the same way.
Admins add the Terminals server as a connection and give people Write access. People with Write access create and manage terminals. Everyone else uses the terminals that are shared with them.
Connection Access
Add the connection in Settings > Integrations (admin section) as described in Connecting to Open WebUI and the Authentication section. The connection form has the Name, ID, URL, API Key, Auth, Verify Connection, Chat Uploads, Access and Advanced options. Terminals themselves are created from the chat.
Access on the connection has two permissions:
| Permission | What it lets a user do |
|---|---|
| Read | See and use the terminals that are shared with them |
| Write | Create and manage terminals on this server, and see every terminal on it |
Create a Terminal
- Open the terminal menu in the message input (the cloud icon). With Write access it shows even before you have a terminal.
- Under Terminals, click New terminal.
- Fill in the dialog and click Create.
| Field | What it does |
|---|---|
| Name | The name shown in the terminal menu |
| Server | The Terminals connection that runs the terminal. Shown only when you create a terminal and more than one Terminals connection is available |
| Separate instances | A switch. When on, a dropdown next to it picks User, Chat or Model and starts on User. When off, everyone with access shares one instance. See Machine Scope. Locked while instances exist, so delete all instances to change it |
| Start directory | Under Advanced. Folder where commands start. It must be inside the home folder, otherwise commands start in the home folder. Stored as OPEN_TERMINAL_START_DIR |
| Setup script | Under Advanced. Shell script that runs in the start directory every time an instance starts, before it is ready. Only the home folder is kept between restarts, so write the script to be safe to run again. Stored as OPEN_TERMINAL_SETUP_SCRIPT. Progress and failures, with the exit code and the end of the log, show in System info |
| Advanced | Start directory, Setup script, Image, CPU, Memory, Storage, Network and Environment variables. Empty fields use the server default. Values are checked against the server maximums |
A new terminal is private. After creating it, open Terminal settings from the terminal menu and click the Private button at the top of the dialog to open Access, where you can share the terminal with chosen users and groups. Shared access is for use only.
A person with Write access to a Terminals connection can open System info and the files of any running instance on it, with full access to those files. Give Write only to people you trust with everyone's workspaces.
See Environment Variables for raw values and reserved keys and Custom Images for the Image field.
People with access to a terminal can run commands in it. With Separate instances off, everyone with access shares one instance, and with Model everyone using the same model shares one. They see that instance's files, so share such a terminal only with people who may see those files.
Machine Scope
| Separate instances | Result |
|---|---|
| Off | One instance for everyone who uses the terminal |
| On, User | Each user has their own instance |
| On, Chat | Each saved chat has its own instance, with its own files |
| On, Model | Each model has its own instance |
- A Chat terminal needs a saved chat. It works in a saved chat, after the first message is sent.
- A Model terminal needs access to the model.
- People who can reply in a chat shared with Allow replies use that chat's own terminal.
- Automations that post to a channel cannot use Chat terminals.
Chat and User multiply the number of running instances. Ask an admin to set an idle timeout so instances of abandoned chats are cleaned up, see Idle Cleanup, Lifetime and Scheduled Resets.
Manage Machines
The Instances list in the dialog shows every instance of the terminal with its name and whether it is running or stopped. Open the More options menu of a row to act on it. A running instance offers Restart and Stop, plus System info and View files. A stopped one offers Start. Every instance offers Delete instance. While an action runs, the row shows what is happening (Restarting..., Stopping..., Starting... or Deleting...) with a spinner. Delete terminal removes the terminal and its instances and files.
Terminal Menu
Each terminal in the menu has a More menu with Restart and Stop while the instance runs or Start while it is stopped. While the instance runs it also lists System info and View files. Terminal settings is always there. View files opens the file browser for that terminal without selecting it for the chat. System info shows CPU, memory, disk and network use, uptime and top processes, and refreshes every 5 seconds while open.
Chats
Each chat saves its terminal and working folder and restores them when it is reopened. A chat saved without a terminal opens without one.