# PROMPIT setup guide

Plain-text setup steps for people and AI agents. PROMPIT is a local app: it runs on one
computer, listens only on 127.0.0.1, and sends nothing to its makers. The full manual ships
with the app as `PROMPIT_MANUAL.md`. Where this guide and the manual disagree, the manual wins.

## Rules for agents

- Do everything on the user's own computer. PROMPIT has no account, no cloud service and no API key.
- Don't change PROMPIT's own files. The folder is signed, and PROMPIT refuses to start when a file has changed.
- Never read, print or copy tokens, keys or passwords, including the `?t=` token in PROMPIT's address.
- Ask the user before you install anything, delete anything, or open a port.
- Report what you checked and what you could not check.

## 1. Get PROMPIT

- **Windows:** run the installer from the Download page. It installs for the current user, in `%LOCALAPPDATA%\PROMPIT`.
- **Linux:** download `prompit-linux.tar.gz`, then:

  ```
  tar -xzf prompit-linux.tar.gz
  cd prompit
  ```

  Use `tar`. Tools that drop file modes break the `.sh` launchers.
- **Check the download (Linux):** in the `prompit` folder run
  `deno run --allow-read prompit_sign.ts verify .`. It prints `OK` and the key's fingerprint.
  PROMPIT runs the same check at every start.

## 2. Install what PROMPIT needs

| Need | Windows | Linux |
| --- | --- | --- |
| Deno 2.x | from deno.com, on PATH | from deno.com (`~/.deno/bin` is found automatically) |
| llama.cpp release build | unpacked in `C:\llama.cpp` | unpacked in `~/llama.cpp` |
| Models (`.gguf`) | in `C:\Models` | in `~/Models` |

- Linux also needs bubblewrap (`sudo apt install bubblewrap`), the second wall around everything a model runs.
- llama.cpp releases: https://github.com/ggml-org/llama.cpp/releases
- GGUF models: https://huggingface.co/models?library=gguf
- An NVIDIA card needs the CUDA build of llama.cpp, plus its cudart download unpacked beside `llama-server`. Without it llama.cpp runs on the CPU, and PROMPIT says so.
- PROMPIT lists only the top level of the models folder.
- On a Steam Deck use llama.cpp's Vulkan build and a 16k or 32k context.

## 3. Start PROMPIT

- **Windows:** double-click `prompit.bat` (or start the installed app).
- **Linux:** run `./prompit.sh` from your own desktop session.

PROMPIT opens a browser tab at `http://127.0.0.1:8000/?t=…`. Leave the launcher window open,
because closing it stops PROMPIT. Use that tab:

- Don't open `index.html` directly. It needs the server.
- Don't bookmark the address. The token changes every launch.

## 4. Start the model

1. In the model bar, set PROVIDER to `llama.cpp`.
2. Pick a `.gguf` in MODEL, set CTX, GPU and THR, and press START.
3. Wait for the engine chip to read `RUNNING :8080`.

PROMPIT remembers a setup only after it has loaded, and starts it again at the next launch.

## 5. Open a project folder

1. Click PROJECTS in the rail.
2. Press **New folder**, find the folder in the window that opens, and press **Open this folder**. To start a new one, type its name and press **Make and open**.
3. Choose a mode:
   - **Pep**: a chat that writes files into the folder.
   - **Pump**: a run that keeps working until the job is done, inside a sandbox.
   - **Prop**: a folder's own assistant that works its task queue while you are away.
   - **CLI**: your own signed-in CLI in a terminal.

Rules for a folder go in `PROMPIT.md` inside it (PROJECT RULES in the rail).

## Optional

- **Helper models**, each set up once in the engine settings: decisions (DCN), audio (AUD), meaning search (EMB), pictures and videos (sd-cli from stable-diffusion.cpp).
- **Phone alerts and connectors**: the courier sends alerts to Gotify, Discord, Telegram or email, and lets you message your Props from Discord, Telegram, Slack or email. Set it up under DEPLOY.
- **Renders**: Google Chrome lets PROMPIT look at the pages it builds.

## Check the setup

In the PROMPIT folder:

```
deno run --allow-read --allow-run --allow-env=SystemRoot prompit_server.ts --doctor
```

It prints Deno and OS versions, the signature, whether ports 8000 and 8080 are free, whether
llama-server and models were found, and whether the GPU answers. It starts nothing and prints
no token, file contents or keys, so its output is safe to share.

## Common problems

| You see | Do this |
| --- | --- |
| `PROMPIT // LOCKED` | Start PROMPIT again and use the new tab. |
| `NO ENGINE · set up` or `llama-server NOT FOUND` | Press Engine paths (or ⚙ in the model bar). Give the full path to `llama-server` and the models folder. |
| Port 8000 in use | Another PROMPIT is running. Close it. |
| Port 8080 in use | A llama-server you started yourself is running. Close it and press START. |
| `deno is not on your PATH` | Install Deno, close every terminal window, and start again. |
| `no .gguf files in …` | Wrong folder, or the models are in subfolders. |
