# Using OwnTerm

OwnTerm is a local terminal. The shell works without an account. Agent requests go only to the OpenAI-compatible endpoint you configure. Nothing in this guide signs you into Warp or sends a usage report.

## Install or update

From a checkout of this repository:

```bash
bash script/install-ownterm.sh
```

That downloads the archive for this machine from GitHub Releases, checks it against `SHA256SUMS`, and copies `ownterm` and `ownterm-tui` to `~/.local/bin`. Run the same command later to replace those binaries with the latest release. Pin a version with `--tag v0.2.0` (use the tag you want).

Add `~/.local/bin` to `PATH` if it is not already there, then run `ownterm` or `ownterm-tui`.

The archives are not code-signed. macOS may ask you to allow the app in Privacy & Security the first time you open it. Windows SmartScreen may show a warning. Check `SHA256SUMS` on the release before you bypass either prompt.

To verify by hand:

```bash
curl -fsSL -o SHA256SUMS https://github.com/lcajigasm/ownterm/releases/latest/download/SHA256SUMS
curl -fsSL -o ownterm-linux-x86_64.tar.gz https://github.com/lcajigasm/ownterm/releases/latest/download/ownterm-linux-x86_64.tar.gz
sha256sum -c SHA256SUMS --ignore-missing
```

Use the asset name for your machine: `ownterm-macos-arm64`, `ownterm-macos-x86_64`, `ownterm-linux-x86_64`, or `ownterm-windows-x86_64`.

On a Mac you can also open `ownterm-macos-universal.dmg` and drag `OwnTerm.app` to Applications. That app is the `ownterm` binary for both Apple Silicon and Intel. If the two builds cannot be combined, the release has `ownterm-macos-arm64.dmg` and `ownterm-macos-x86_64.dmg` instead. The `.tar.gz` archives stay on the release for this installer and for Homebrew. The disk image is not code-signed.

## First launch

Start `ownterm`. There is no signup step. With no model configured, the prompt shows **No AI provider**. Settings opens on the agent page and leaves out billing, teams, and Warp Drive. The shell still runs.

You can leave the model unset and use OwnTerm as a terminal. Set a provider when you want the agent.

## Provider

`OWNTERM_MODEL` is required for agent requests. `auto` chooses the cheapest available catalog model for the prompt. A simple prompt stays there. Tools or a long context step up. A missing provider falls back, and the choice is logged. See the README section "Auto mode". Environment variables override `~/.ownterm/provider.env`. The file accepts `provider`, `model`, `base_url`, and optionally `api_key_env`. It is rejected if it contains `api_key`, `token`, or `secret`. Put a cloud key in the environment variable named by `api_key_env` (default `OWNTERM_API_KEY`).

The installer can write the non-secret fields:

```bash
bash script/install-ownterm.sh --provider ollama --model llama3.3
```

Or edit the file yourself:

```
provider=ollama
model=llama3.3
```

`ownterm-tui configure-provider` writes that file. It does not store an API key.

```bash
ownterm-tui configure-provider --provider ollama --model llama3.3
```

Settings does the same write. Open Settings, stay on Warp Agent, and use **Local provider**. The provider and model lists are the ones `ownterm-tui models` prints. Base URL can stay on the preset default. The API key field is only the environment variable name (`OWNTERM_API_KEY` unless you set another). A different name is stored as `api_key_env`. The key itself is never written. Validation errors stay on that form.

`ownterm-tui models --provider ollama` prints suggested model ids and the catalog URL for that endpoint (`/models`). It does not download the catalog. Pass `--base-url` when the preset needs one, or to point at your own server.

| `provider` | Default base URL | Key |
| :--- | :--- | :--- |
| `ollama` | `http://127.0.0.1:11434/v1` | no |
| `lmstudio` | `http://127.0.0.1:1234/v1` | no |
| `vllm` | `http://127.0.0.1:8000/v1` | no |
| `localai` | `http://127.0.0.1:8080/v1` | no |
| `openai` | `https://api.openai.com/v1` | `OWNTERM_API_KEY` |
| `xai` | `https://api.x.ai/v1` | `OWNTERM_API_KEY` |
| `openrouter` | `https://openrouter.ai/api/v1` | `OWNTERM_API_KEY` |
| `groq` | `https://api.groq.com/openai/v1` | `OWNTERM_API_KEY` |
| `compatible` | set `base_url` | optional |

HTTP is accepted only for localhost and loopback. Other endpoints must be HTTPS.

## Agent tools

With a model configured, the assistant can run a shell command, read files, grep, glob, and apply a search-and-replace diff. Those calls stay on this machine. Grep is not Warp's cloud code index. A diff still waits for the confirmation the terminal already shows.

## Local workflows

Workflows in `~/.ownterm/workflows` show up in command search and in the `/` menu. They are files on this machine. Warp Drive is not involved. `ownterm-tui workflow add` writes that YAML. `{{name}}` in the command becomes a prompted argument. Command search and the `/` menu load the file without a restart.

```bash
ownterm-tui workflow add --name "Git status" --command "git status --short" --description "Show the working tree status"
ownterm-tui workflow list
```

`~/.ownterm/workflows/git-status.yaml`:

```yaml
---
name: "Git status"
command: "git status --short"
description: "Show the working tree status"
arguments: []
---
```

Several workflows may share one YAML file, separated by `---`. Restart is not required after you save the file; the directory is watched.

## Headless TUI

`ownterm-tui` is the same terminal without a GPU window. Use it over SSH. It reads the same provider file and the same `~/.ownterm/workflows` directory.

## What stays on this machine

- The installer talks only to GitHub Releases and checks `SHA256SUMS` before it writes the binaries.
- The shipped app does not enable the built-in updater, so it does not download builds on its own.
- Analytics events are not constructed or uploaded.
- Agent traffic goes to the endpoint in your provider file or environment, and nowhere else for inference.