Install¶

Requirements¶

The gh CLI¶

oss-inbox is built on the gh CLI, the official GitHub command-line tool. The app does not connect to GitHub itself. In the background, it runs gh api for each request to GitHub. gh sends the request with your GitHub login. The app does not keep a GitHub token of its own.

The app does not work without gh. Install and log in to gh before you install oss-inbox.

Install gh for your system. Follow the installation instructions.
Log in with your own GitHub account:

gh auth login

Make sure that the login works:

gh auth status

Systems¶

	Linux	macOS	Windows
Status	Tested (Ubuntu, GNOME)	Not tested	Tested (Windows 11)
Python	3.10 or later	3.10 or later	3.10 or later
`gh` CLI	Yes	Yes	Yes
`uv`	Install from the source	Install from the source	Install from the source
Pop-ups	`notify-send`	Built in	Built in

The executable needs no Python and no uv. Only the install from the source needs them.

Installation¶

Install oss-inbox in one of the two ways below.

Download the executable¶

This way needs no Python.

LinuxmacOSWindows

Download oss-inbox-linux from the latest release.
Make the file executable:
```
chmod +x oss-inbox-linux
```
Start the app:
```
./oss-inbox-linux web
```

Download oss-inbox-macos from the latest release.
Make the file executable:
```
chmod +x oss-inbox-macos
```
Start the app:
```
./oss-inbox-macos web
```

The file has no signature. macOS shows a warning the first time. Right-click the file and select Open.

Download oss-inbox-win.exe from the latest release.
Start the app:
```
.\oss-inbox-win.exe web
```

The file has no signature. Windows shows a warning the first time. Click More info, then Run anyway.

The command starts the daemon and opens http://127.0.0.1:8765 in your browser. The daemon runs in the background. You can close the terminal. To stop the daemon, click Stop daemon on the web page, or run the file with stop, for example ./oss-inbox-linux stop.

Install from the source¶

Run these commands in a terminal. On Windows, use PowerShell.

Get the code:

git clone https://codeberg.org/florence-bockting/oss-inbox.git
cd oss-inbox

Install the app with uv. This also installs Flask and Textual.
```
uv tool install .
```
Start the app:
```
oss-inbox web
```

uv installs the app in its own environment. It puts the oss-inbox command in your PATH. If your shell does not find oss-inbox, run uv tool update-shell. Then open a new terminal. The install is a copy of the code. A later change in the folder has no effect on the command. To use a new release, see Update an install from the source. To change the code, see Run your changes.

The command starts the daemon and opens http://127.0.0.1:8765 in your browser. The daemon runs in the background. You can close the terminal. To stop the daemon, click Stop daemon on the web page, or run oss-inbox stop.

Then set up the app in the browser. For the terminal UI, see Start the app.

Open the Repos tab (how your inbox is organized). Click Load my repos, or type owner/repo. Then select the repos to watch.
Click Sync now and wait for the updates to appear.

Update to a new release¶

Each new release appears on the releases page. Update the app in the same way that you installed it.

Note

The daemon keeps the old version until you restart it.

Update from gh-inbox

Stop the gh-inbox daemon before you start oss-inbox. On the first start, oss-inbox moves your data from ~/.local/share/gh-inbox/ to ~/.local/share/oss-inbox/. Your notes file stays where it is.

Update the executable¶

LinuxmacOSWindows

Stop the daemon: click Stop daemon on the web page.
Download the new oss-inbox-linux from the latest release.
Replace the old file with the new file.
Make the file executable:
```
chmod +x oss-inbox-linux
```
Start the app again:
```
./oss-inbox-linux web
```

Stop the daemon: click Stop daemon on the web page.
Download the new oss-inbox-macos from the latest release.
Replace the old file with the new file.
Make the file executable:
```
chmod +x oss-inbox-macos
```
Start the app again:
```
./oss-inbox-macos web
```

Stop the daemon: click Stop daemon on the web page.
Download the new oss-inbox-win.exe from the latest release.
Replace the old file with the new file.
Start the app again:
```
.\oss-inbox-win.exe web
```

Update an install from the source¶

Run these commands in a terminal. On Windows, use PowerShell.

Stop the daemon: click Stop daemon on the web page.
Get the list of releases:
```
git fetch --tags
```
Change to the new release. Replace v0.1.0 with the release name:
```
git checkout v0.1.0
```
Install again. A new release can add dependencies:
```
uv tool install --force .
```
Start the app again:
```
oss-inbox web
```

Get the newest code before a release

The newest code can contain changes that are not in a release yet. To get it, use these commands in place of steps 2 and 3:

git checkout main
git pull