# owui-bash-mcp

Single-endpoint FastAPI OpenAPI tool server that gives Open WebUI a bash tool
for coding. Runs as the dedicated unix user `owui-coder`, confined to a
persistent projects workspace.

## Endpoint
`POST /run_bash` — `{ command, cwd?, timeout? }` → `{ stdout, stderr, exit_code, timed_out, truncated, cwd }`.
Runs `bash -lc <command>` in `PROJECTS_ROOT/<cwd>`. Filesystem state persists
between calls; cwd does not (pass it each call).

## Config (env)
- `BASH_MCP_PROJECTS_ROOT` (default `/home/owui-coder/projects`)
- `BASH_MCP_DEFAULT_TIMEOUT` (300s), `BASH_MCP_MAX_TIMEOUT` (1800s)
- `BASH_MCP_MAX_OUTPUT` (100000 bytes/stream, tail kept)

## Run
`uvicorn app:app --host 127.0.0.1 --port 8774`
(8770–8773 are already taken on this host by proton-mcp / mcpo.)

## Deploy
systemd system unit `owui-bash-mcp.service` (`User=owui-coder`), registered in
OWUI as tool server `http://127.0.0.1:8774`. See diverse/deploy.

## Test
`BASH_MCP_PROJECTS_ROOT=/tmp/owui-bash-test-root .venv/bin/pytest`
(venv built with `uv venv --python 3.13`).