page
Get Started
Install uterm, run the reference TermHub, attach a worker, and open a browser — then add MCP or the edge backend when you need them.
uterm is a Python + TypeScript monorepo. The reference hub runs locally; the browser frontend is a static bundle; the MCP server is one extra entry point; the Cloudflare edge backend is its own package. You can stop at step 2 and have a working shared terminal.
1. Install
git clone https://github.com/provide-io/provide-uterm.git
cd provide-uterm
uv sync --group dev
npm ci
npm run build:frontend
uv sync resolves the Python workspace (7 packages). npm run build:frontend builds the TypeScript bundle the hub serves to browsers.
2. Run the hub
uv run uterm-server \
--bind 127.0.0.1:27780 \
--auth dev \
--config scripts/uterm-server.example.toml
--auth dev disables authentication and is intended for local use only. For production, switch to --auth jwt and supply the signing key in the config file.
Open http://127.0.0.1:27780/ in a browser — you should see the uterm frontend with a placeholder until a worker attaches.
3. Attach a worker
In a second terminal:
uv run uterm connect ws://127.0.0.1:27780/term \
--role operator \
--pty bash
The worker spawns a bash PTY and registers it with the hub. The browser session you opened in step 2 now shows that PTY’s output and accepts input from the holder of the hijack lease.
4. Add a second participant
Open a second browser window or another uterm connect client. The hub assigns it an adjective-animal identity (e.g. drifting-otter), gives it a deterministic color, and shows it in the presence strip. With the default RBAC, it joins as viewer — it can watch but not type.
Optional: register the MCP server
To let an AI agent participate, register uterm-mcp with your MCP harness.
Claude Code
.mcp.json (project) or ~/.claude.json (global):
{
"mcpServers": {
"uterm": {
"command": "uv",
"args": ["--directory", "/abs/path/to/provide-uterm", "run", "uterm-mcp"]
}
}
}
Codex
~/.codex/config.toml:
[mcp_servers.uterm]
command = "uv"
args = ["--directory", "/abs/path/to/provide-uterm", "run", "uterm-mcp"]
Reload your harness. The 21 uterm tools become available to the agent.
Optional: deploy at the edge
cd packages/provide-uterm-cloudflare
npx wrangler deploy
Point your browser at the deployed Workers URL instead of 127.0.0.1:27780. The same control channel runs on Cloudflare Durable Objects, with one DO per session.