Skip to main content

Connecting Open Terminal to Open WebUI

Open Terminal is installed and running. This guide covers connecting it to Open WebUI.

Recommended for all deployments, including single-user. The Admin Panel keeps the API key server-side.

1. Open the Admin Panel​

Click your name at the bottom of the left sidebar to open the user menu, then click Admin Panel.

User menu showing Admin Panel option

2. Go to Settings → Integrations​

In the Admin Panel, click Settings in the top nav, then click Integrations.

Admin Panel, Settings → Integrations

3. Find the "Open Terminal" section​

Scroll down until you see the Open Terminal section.

The Open Terminal section under Integrations

Don't confuse it with "Tools"

Open Terminal has its own section under Integrations. Don't add it under "External Tools" or "Tool Servers". Using the dedicated section gives you the built-in file browser and terminal sidebar.

4. Click + and fill in the details​

FieldWhat to enter
URLhttp://localhost:8000 (or http://open-terminal:8000 if using Docker Compose)
API KeyThe password you chose during installation
Auth TypeLeave as Bearer (the default)

Connection form filled in with URL and API key

5. Save​

Click Save. A green "Connected" indicator confirms the connection.

Connected status with green indicator

6. (Optional) Restrict access to specific groups​

Limit terminal access to specific user groups via the access control button.

7. Select a terminal in chat​

In the chat input area, click the terminal button (cloud icon ☁). Your admin-configured terminals appear under System. Select one to activate it for the conversation.

Terminal dropdown showing Docs Terminal under System

The selected terminal name appears next to the cloud icon. The AI can now execute commands, read files, and run code through it.

8. Enable native function calling​

Native function calling is the default tool-calling mode as of v0.10.0, so it is already active for new models. The only thing to check is that the model was not switched to Legacy:

  1. Go to Workspace → Models
  2. Click the edit button on the model you're using
  3. Make sure Function Calling is set to Native (the default), not Legacy
  4. Save

Model capabilities showing Builtin Tools enabled

Legacy Mode is less reliable for tools

If the model is set to Legacy, Open WebUI falls back to prompt-based tool calling instead of the provider's structured tool-call format. That is less reliable and may not trigger terminal commands at all. Native (the default) is recommended.

Performance depends on the model

Not all models are equally capable with tools. Multi-step terminal workflows are the most demanding agentic use case in Open WebUI, so this is one place where a top-tier model genuinely pays off — GPT-5.6 Sol, Claude Opus 5, or Gemini 3.5 Pro. A current mid-tier model (GPT-5.6 Terra, Claude Sonnet 5, Gemini 3.6 Flash, MiniMax M3) is the practical minimum. Older or very small models may fail to invoke tools or produce malformed tool calls. If results are poor, try a more capable model.

9. Try it out​

Ask your AI something like:

"What operating system are you running on?"

The AI should use Open Terminal to run a command and tell you the answer.

AI using run_command to check the operating system

Pre-configure via environment variable

For Docker deployments, you can configure terminal connections automatically using the TERMINAL_SERVER_CONNECTIONS environment variable, which is useful when you want everything set up at startup without manual steps.

Personal Settings (testing only)​

Not recommended for regular use

Adding a terminal connection via personal Settings sends the API key to your browser and routes requests directly from it. This is fine for quick testing, but for anything beyond that, use Admin Settings instead. It's more secure and works for all users automatically.

If you need to test a connection without admin access, you can add one from Settings → Integrations → Open Terminal. The same URL and API key fields apply.

Troubleshooting​

"Connection failed" or timeout​

This almost always means Open WebUI can't reach Open Terminal over the network. What URL to use depends on your setup:

Your setupURL to use
Docker Compose (recommended)http://open-terminal:8000
Separate Docker containershttp://host.docker.internal:8000
Both on same machine, no Dockerhttp://localhost:8000
Open Terminal on another machinehttp://that-machines-ip:8000
Quick check

Run this command to see if Open WebUI can reach Open Terminal:

docker exec open-webui curl -s http://open-terminal:8000/health

If it prints {"status": "ok"}, the connection works. If it errors, the containers can't see each other.

Terminal shows up but AI doesn't use it​

Make sure:

  • The toggle switch next to the connection is turned on. Turning it off takes the terminal server out of service completely: the model is not given its tools, the terminal and file browser refuse to connect, and any proxied request to it is rejected. It is a working off switch, not just a hint to the model, so use it to retire a server without deleting the connection.
  • You've refreshed the page after adding the connection
  • Your model supports tool calling (most modern models do)

Wrong API key​

If you see "unauthorized" or "invalid key":

  • Double-check the key matches what you set during installation
  • If you forgot it, run docker logs open-terminal and look for the API key: line

Next steps​

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.