mistwatch 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Daniel Šebesta
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,120 @@
1
- # Temporary Holding Version
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/danielsebesta/mistwatch/main/web/public/logo-dark.svg">
4
+ <img src="https://raw.githubusercontent.com/danielsebesta/mistwatch/main/web/public/logo.svg" alt="Mistwatch" height="48">
5
+ </picture>
6
+ </p>
2
7
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
8
+ <p align="center">A local proxy for Mistral AI that tracks your budgets and gives your coding tools one <code>auto</code> model.</p>
9
+
10
+ <p align="center">
11
+ <a href="https://www.npmjs.com/package/mistwatch"><img alt="npm" src="https://img.shields.io/npm/v/mistwatch?color=ff8204&logo=npm"></a>
12
+ <a href="https://www.npmjs.com/package/mistwatch"><img alt="downloads" src="https://img.shields.io/npm/dm/mistwatch?color=ff8204"></a>
13
+ <a href="https://github.com/danielsebesta/mistwatch/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/danielsebesta/mistwatch/ci.yml?branch=main&label=CI"></a>
14
+ <a href="https://github.com/danielsebesta/mistwatch/pkgs/container/mistwatch"><img alt="Docker" src="https://img.shields.io/badge/docker-ghcr.io-2496ed?logo=docker&logoColor=white"></a>
15
+ <img alt="Node 24+" src="https://img.shields.io/node/v/mistwatch?color=339933&logo=node.js&logoColor=white">
16
+ <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/npm/l/mistwatch?color=blue"></a>
17
+ </p>
18
+
19
+ > **Unofficial tool.** Mistwatch is an independent project. It is not a product of Mistral AI and is not affiliated with, endorsed by or sponsored by it. "Mistral" is a trademark of Mistral AI and is used here only to describe the service the tool talks to.
20
+
21
+ ## What it does
22
+
23
+ - **Tracks your budgets.** It shows how much of your Vibe Code and Studio (API) allowance you have used, per 5 hours, day, week and month.
24
+ - **Spreads usage over time.** It paces requests so you do not burn a whole month's allowance in one afternoon. When nothing is left it answers `429` with a `Retry-After` header.
25
+ - **Offers an `auto` model.** It picks a suitable Mistral model for each request.
26
+ - **Pools several accounts.** Requests go to whichever account still has room.
27
+ - **Works with your tools.** OpenCode, Pi and the Vibe CLI, or anything that speaks the OpenAI chat API.
28
+
29
+ ## Quick start
30
+
31
+ You need Node 24 or newer. Use whichever package manager you like:
32
+
33
+ ```sh
34
+ npx mistwatch setup # npm
35
+ pnpm dlx mistwatch setup # pnpm
36
+ yarn dlx mistwatch setup # yarn (Berry)
37
+ bunx mistwatch setup # bun
38
+ ```
39
+
40
+ Setup creates the config, imports your Vibe login, creates a client token (shown once) and writes the config of your tools. Then start the proxy and open the web UI:
41
+
42
+ ```sh
43
+ npx mistwatch serve # http://127.0.0.1:8787/
44
+ ```
45
+
46
+ To install it globally instead: `npm i -g mistwatch`, `pnpm add -g mistwatch`, `yarn global add mistwatch` or `bun add -g mistwatch`, then run `mistwatch`.
47
+
48
+ Your tools read the client token from the `MISTWATCH_TOKEN` environment variable. Set it as setup tells you.
49
+
50
+ For scripts and AI agents there is a non-interactive form: `mistwatch setup --yes --harness vibe` (or `opencode`, `pi`). See [AGENTS.md](AGENTS.md).
51
+
52
+ ### Docker
53
+
54
+ ```sh
55
+ docker run -d --name mistwatch -p 127.0.0.1:8787:8787 -v mistwatch:/data ghcr.io/danielsebesta/mistwatch
56
+ ```
57
+
58
+ Publish the port on `127.0.0.1` as shown, so the UI is not exposed to your network. The container keeps its config and database in the `mistwatch` volume. Open <http://127.0.0.1:8787/>, create your login and add your keys there.
59
+
60
+ ## Web UI
61
+
62
+ - **Overview**: Vibe and Studio budgets, limits per period, a spending chart and recent requests.
63
+ - **Accounts**: your Mistral accounts, each with a Vibe key (can be taken over from the Vibe CLI in one click) and a Studio API key. A key is checked before it is saved.
64
+ - **API keys**: `mw-…` keys for your tools. A key is shown only once, when you create it. The same page has ready-made configs for OpenCode, Pi and the Vibe CLI, plus environment variables for other tools.
65
+ - **Settings**: change your password, add users and rename models in charts and tables.
66
+
67
+ ## Connecting your tools
68
+
69
+ `mistwatch setup` does it in one go. You can also do one tool at a time:
70
+
71
+ ```sh
72
+ mistwatch agent-config opencode --write
73
+ mistwatch agent-config pi --write
74
+ mistwatch vibe-config
75
+ ```
76
+
77
+ Claude Code and current Codex CLI do not work directly, because they need the Anthropic Messages or OpenAI Responses format and Mistral offers neither. Put a translating proxy such as LiteLLM in front of Mistwatch if you need them.
78
+
79
+ Agents and integrators can read `/llms.txt` on a running proxy (no sign-in needed). It describes the address, authentication, the `auto` models and the `401` and `429` errors.
80
+
81
+ ## Commands
82
+
83
+ | Command | What it does |
84
+ | --- | --- |
85
+ | `setup` | One-step setup for your tools |
86
+ | `serve` | Run the proxy and web UI (`--port`) |
87
+ | `status` | Show the budget of every account |
88
+ | `sync` | Pull budget usage from Mistral now |
89
+ | `route "prompt"` | Show which model `auto` would pick |
90
+ | `import-vibe` | Add the Vibe CLI login as an account |
91
+ | `passwd <user>` | Create a user or reset a password |
92
+ | `init` | Write a fresh config file |
93
+
94
+ ## Configuration
95
+
96
+ Settings live in `~/.mistwatch/config.toml` (server address and port, limits, prices, the `auto` router). Set `MISTWATCH_HOME` to keep it somewhere else. Accounts and keys are stored in the database, not in the config file.
97
+
98
+ To reach the UI under another host name, for example through a tunnel, add it to `allowed_hosts` under `[server]`.
99
+
100
+ ## Security
101
+
102
+ - Passwords are hashed with salted scrypt. Sessions and proxy keys are stored only as SHA-256 hashes.
103
+ - Mistral keys have to be forwarded, so they cannot be hashed. They are kept in your system keyring (Windows Credential Manager, macOS Keychain, libsecret). The database holds only a reference. The Docker image has no keyring and stores them in the data volume instead.
104
+ - Cookies are `HttpOnly` and `SameSite=Strict`, and five failed sign-ins lock an account for 60 seconds.
105
+ - The server listens on `127.0.0.1` only. If you expose it to a network, put a reverse proxy with HTTPS in front.
106
+ - Forgot your password? Run `mistwatch passwd <username>`.
107
+
108
+ ## Development
109
+
110
+ ```sh
111
+ npm ci
112
+ npm run check # typecheck, lint, tests
113
+ npm run build # dist/cli.js and dist/web
114
+ ```
115
+
116
+ The logo, favicons and colour palette are generated from `brand/` (`npx tsx brand/build.ts`, `npx tsx brand/contrast.ts`).
117
+
118
+ ## Licence
119
+
120
+ [MIT](LICENSE)