---
title: "05 — Open Terminal & Tooling"
description: "## What Open Terminal is"
section: ai-docs
raw: "05-open-terminal-and-tooling.md"
source: ai-generated
tags: ai, llama.cpp, docker
last-updated: 2026-09-15
---

# 05 — Open Terminal & Tooling

> Giving the model a shell: Open Terminal as a hosted, API-driven terminal that agents can drive, plus how it fits the wider tooling layer.

## What Open Terminal is

[Open Terminal](https://github.com/open-webui/open-terminal) is a containerised terminal service that exposes a **real shell over a REST API** rather than a browser-only web terminal. That API surface is the point: it lets a *model* — not just a human — open sessions, send commands, and read output, which turns "the LLM can talk" into "the LLM can *do*."

It's part of the Open WebUI family and plugs in next to the chat UI, so the same authentication and multi-user model carries over.

## How it's deployed here

```yaml
open-terminal:
    image: ghcr.io/open-webui/open-terminal
    container_name: open-terminal
    ports:
      - "8080:8080"
    volumes:
      - /var/local/docker-files/open-terminal:/home
    environment:
      - OPEN_TERMINAL_API_KEY=<REDACTED>
      - OPEN_TERMINAL_MULTI_USER=true
    networks:
      - ai-network
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: unless-stopped
```

Key choices, and why:

- **`OPEN_TERMINAL_MULTI_USER=true`** — the box serves more than one person, so sessions are isolated per user. If you run a single-user instance you can drop it.
- **`OPEN_TERMINAL_API_KEY=<REDACTED>`** — the API is gated by a key. Treat it like a credential: it authorises someone to run shell commands. Never commit the real value (it's redacted in these docs) and rotate it if it ever leaks.
- **`/home` volume persisted to the host** — user workspaces and any files the terminal creates survive container restarts/rebuilds. Without this, an agent's scratch work vanishes on every image upgrade.
- **`extra_hosts: host-gateway`** — the container can reach host services (e.g. the native `llama-server`s) via `host.docker.internal`, same pattern as every other container here.
- **No published port needed for agent use.** It's reachable from other containers on `ai-network` by service name, and from the host via the published `8080`. Expose only what you actually need from outside.

## Why the model needs a shell

A chat model with no tools can only *describe* what to do. A terminal tool closes that gap: the model can inspect the filesystem, run scripts, check command output, and iterate. This is the same "application tier calls a tool, gets a result, feeds it back into context" loop from [01 — Architecture](/ai-docs/01-architecture/) — Open Terminal is just the most general tool you can give it.

The design consequence: **the terminal is a sub-agent-style capability.** Just as you'd delegate a coding sub-task to a smaller model, you can have the *main* agent plan and the terminal (driven by a model) execute. Keeping the executing model small and the planning model big mirrors the [sub-agent split](/ai-docs/04-sub-agents/).

## Security: this is the sharp edge

Giving a model shell access is the highest-risk part of a local AI stack. Guardrails that matter in practice:

- **Authenticate with the API key** — never expose an unauthenticated terminal API, even on a home LAN.
- **Contain the blast radius.** Run the terminal in its own container (as here) so a runaway command can't reach host services or other containers' data by default. The persisted `/home` is the intended workspace; keep host-critical paths out of the mount.
- **Prefer a non-root user inside the container** for day-to-day sessions; reserve root for the specific step that needs it.
- **Rotate the key** and store it outside version control. The compose file here kept the key inline — a practical choice for a single trusted box, but the safer default is a secrets file or manager that is git-ignored.
- **Log and review.** Because the model can run arbitrary commands, keep an eye on what it's actually executing, especially when it's acting autonomously.

## How it relates to the other tools

- **Open WebUI** is the chat front-end and the place where you wire models and tools together in the UI.
- **Open WebUI Pipelines** is the plugin/orchestration server — where you build pipelines that chain models, tools, and agents (including calls *into* Open Terminal).
- **Open Terminal** is the execution end of that pipeline: the tool that turns a decision into an action on a real system.

A typical agentic flow: user asks the Open WebUI chat → the (primary) model decides it needs to run something → the pipeline invokes Open Terminal's API → a command runs in a session → output is returned → the model reasons over it and either answers or runs the next command.

## Related

- [01 — Architecture](/ai-docs/01-architecture/) — the tiers and how containers reach the host
- [Sub-agents](/ai-docs/04-sub-agents/) — delegating work, which is what a shell tool enables
- [Skills](/ai-docs/06-skills/) — packaging repeatable procedures the model can follow through these tools

---

## Source Disclaimer

- [x] AI Generated
- [ ] Human Generated
- [ ] AI Edited
- [ ] Human Edited