Skip to main content

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:

PermissionWhat it lets a user do
ReadSee and use the terminals that are shared with them
WriteCreate and manage terminals on this server, and see every terminal on it

Create a Terminal​

  1. Open the terminal menu in the message input (the cloud icon). With Write access it shows even before you have a terminal.
  2. Under Terminals, click New terminal.
  3. Fill in the dialog and click Create.
FieldWhat it does
NameThe name shown in the terminal menu
ServerThe Terminals connection that runs the terminal. Shown only when you create a terminal and more than one Terminals connection is available
Separate instancesA 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 directoryUnder 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 scriptUnder 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
AdvancedStart 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.

Write access reaches other people's instances

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 instancesResult
OffOne instance for everyone who uses the terminal
On, UserEach user has their own instance
On, ChatEach saved chat has its own instance, with its own files
On, ModelEach 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.

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.