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​

For the AI to use terminal tools reliably, you need to enable native function calling on your model:

  1. Go to Workspace → Models
  2. Click the edit button on the model you're using
  3. Under Capabilities, enable Native Function Calling (also called "tool use")
  4. Save

Model capabilities showing Builtin Tools enabled

Without this, tools may not work

Native function calling lets the model invoke tools directly using the provider's built-in tool-calling format. Without it, Open WebUI falls back to prompt-based tool calling, which is less reliable and may not trigger terminal commands at all.

Performance depends on the model

Not all models are equally capable with tools. Frontier models (GPT-5.4, Claude Sonnet 4.6, Gemini 3.1 Pro) handle multi-step terminal workflows well. Smaller or older models may struggle with complex tasks, 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 — 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
  • 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​