Andrea Grandi

Releasing mcp-wire: a tool to easily configure MCPs in coding agents

Sat, 14 Feb 2026 00:00:00 +0000

Introduction

If you’ve been using AI coding agents like Claude Code, OpenCode, or Codex, you’ve probably noticed that each one has its own way of configuring MCP (Model Context Protocol) servers. Claude Code uses JSON, OpenCode uses JSONC, Codex uses TOML, and they all store things in different locations. Adding a new MCP service means manually editing the right config file for each tool you use.

I found myself repeating this process every time I wanted to add or update an MCP server, and it got old really fast.

mcp-wire is a CLI tool that does all of this for you. It installs and configures MCP servers across multiple AI coding tools from a single, guided interface.

Why mcp-wire?

I use multiple coding agents depending on the task, and I want them all to have access to the same MCP services. Manually editing JSON, JSONC, and TOML config files across different tools is tedious and error-prone. I wanted a single command that would:

Detect which coding tools I have installed
Let me pick an MCP service to install
Handle credentials
Write the correct configuration to each tool’s config file

So I built mcp-wire to do exactly that.

How It Works

Run mcp-wire and you get a guided menu:

$ mcp-wire
Use Up/Down arrows, Enter to select.
> Main Menu
  Install service
  Uninstall service
  Status
  List services
  List targets
  Exit

The install wizard walks you through the whole process step by step: pick a service, select one or more targets, review, and apply. No config files to find or edit by hand.

$ mcp-wire install
Install Wizard

Step 1/4: Service
Use Up/Down arrows, Enter to select. Type to filter.
> Select service
  jira - Atlassian Rovo MCP server (OAuth)

Step 2/4: Targets
Detected targets:
  Claude Code (claude) [installed]
  OpenCode (opencode) [installed]
  Codex (codex) [installed]
[ ] Claude Code (claude)
[x] OpenCode (opencode)
[ ] Codex (codex)

Step 3/4: Review
Service: jira
Targets: OpenCode
Credentials: prompt as needed

Step 4/4: Apply
Installing to: OpenCode
  OpenCode: configured
Equivalent command: mcp-wire install jira --target opencode

If you prefer one-liners over menus, every action has a direct command equivalent:

1
2
3

mcp-wire install jira --target claude --scope project
mcp-wire uninstall sentry --target opencode
mcp-wire status

Supported Targets

mcp-wire currently supports three coding agents:

Claude Code (claude) - with user and project scope support
Codex (codex)
OpenCode (opencode)

It automatically detects which ones are installed on your system and only shows those as available targets.

Scope-Aware Installs

For Claude Code, mcp-wire supports scoped installations:

user (default): MCP service is available across all projects
project: MCP service is only available for the current project

1
2
3

mcp-wire install jira --target claude --scope user
mcp-wire install jira --target claude --scope project
mcp-wire status --scope effective

The effective scope shows you the merged result of user and project configurations, so you can see exactly what’s active.

Bundled Services

mcp-wire comes with a few services out of the box:

context7 - Context7 documentation lookup MCP
jira - Atlassian Rovo MCP server
sentry - Sentry MCP server
playwright - Playwright browser automation MCP

You can list what’s available with mcp-wire list services.

Adding New Services

One thing I’m particularly happy about is how easy it is to add new services. You don’t need to write any Go code — just create a YAML file in the services/ directory:

name: example
description: "Example MCP"
transport: http
auth: oauth
url: "https://mcp.example.com/mcp"
env: []

For local command-based MCP servers (stdio transport):

name: example-stdio
description: "Example local MCP"
transport: stdio
command: npx
args: ["-y", "@example/mcp-server"]
env: []

This is also the easiest way to contribute to the project: adding service definitions for MCP servers you use.

Installation

Install via Homebrew (macOS/Linux):

1
2

brew tap andreagrandi/tap
brew install mcp-wire

Or build from source:

git clone https://github.com/andreagrandi/mcp-wire
cd mcp-wire
make build
./bin/mcp-wire

Complete source code is available on GitHub: https://github.com/andreagrandi/mcp-wire

Conclusion

mcp-wire is a small tool that scratches a very specific itch: keeping MCP configurations consistent across multiple coding agents without the manual toil. If you use more than one AI coding tool and you’re tired of editing config files by hand, give it a try.

It’s open source and contributions are welcome, especially new service definitions. If you have feedback or run into issues, feel free to open an issue or send a pull request 🙂

Using VibeTunnel to control Claude Code instances remotely

Sun, 25 Jan 2026 00:00:00 +0000

Introduction

If you work with Claude Code regularly, you know how useful it can be to have multiple instances running on different machines. But what happens when you’re away from your desk and need to check on a long-running task or provide input to your agent?

VibeTunnel solves this problem by exposing your Claude Code terminal sessions through a web interface, allowing you to control them remotely from any browser.

What is VibeTunnel?

VibeTunnel is a tool that transforms your browser into a functional terminal interface, enabling remote command execution with minimal setup. It runs as a server on your machine and provides a web dashboard where you can view and interact with active terminal sessions.

On MacOS, it also comes with a menu bar application that shows the status of your tunnels and gives you quick access to open any active session in your browser.

Some Use Cases

There are several scenarios where VibeTunnel shines:

Long-running tasks: Start a complex refactoring or code generation task before leaving your desk, then check on its progress from your phone or another computer
Multi-machine workflows: Control Claude Code instances running on your home workstation from your laptop at a coffee shop
Team collaboration: Share your terminal session with a colleague to debug an issue together
On-call scenarios: Respond to production issues by accessing your development environment from anywhere

How to Install and Configure It

Installation

On MacOS (Apple Silicon, MacOS 14.0+), you can install VibeTunnel via Homebrew:

`1`	`brew install --cask vibetunnel`

After installation, launch the application from your Applications folder. You’ll see a new icon appear in your menu bar.

Alternatively, on any platform with Node.js 22.12+, you can install it via npm:

`1`	`npm install -g vibetunnel`

Or run it directly without installation:

`1`	`npx -y vibetunnel --no-auth`

Usage

Once VibeTunnel is running, you use the vt command to wrap any terminal command you want to monitor remotely. For Claude Code:

`1`	`vt claude`

This will start Claude Code as usual, but now it’s accessible through the web interface at http://localhost:4020. The menu bar icon will update to show the active session.

You can then open the dashboard in your browser to view and interact with your session:

If you need to bind to a network interface for remote access:

`1`	`vibetunnel --bind 0.0.0.0`

Not Just Claude Code

While I’ve focused on Claude Code in this post, VibeTunnel works with any terminal application. You can use it to remotely control:

Other AI coding agents: Gemini CLI, OpenAI Codex, Aider, or any other agent that runs in the terminal
Interactive shells: Start a full zsh or bash session with vt --shell and have remote access to your entire development environment
Long-running scripts: Monitor build processes, test suites, or deployment scripts from anywhere
Development servers: Keep an eye on your local dev server logs while away from your desk

# Start Gemini CLI
vt gemini

# Start an interactive shell session
vt --shell

# Run and monitor a build
vt npm run build

# Watch test output
vt pytest -v

Essentially, if it runs in a terminal, you can wrap it with vt and access it remotely.

Using Tailscale to Make Instances Reachable from Everywhere

By default, VibeTunnel only exposes your sessions on localhost. To access them from anywhere, you can combine it with Tailscale.

Tailscale creates a secure, private network between your devices. Once you have it set up:

Install Tailscale on your development machine and any device you want to access it from
Make sure both devices are connected to your Tailnet
Start VibeTunnel with network binding: vibetunnel --bind 0.0.0.0
Access your VibeTunnel dashboard at http://[your-tailscale-hostname]:4020

This way, you can securely access your Claude Code instances from your phone, tablet, or any other computer, regardless of where you are in the world.

What Could Be Improved

While VibeTunnel is a useful tool, there are a few areas where it could be better:

Mobile usability: The web interface works on mobile browsers, but it’s not optimised for smaller screens. Typing commands and reading output on a phone can be awkward
Touch interface: Terminal interactions don’t translate well to touch, making it difficult to do anything beyond basic monitoring on mobile devices

If mobile access is a priority for you, you might want to check out Happy as an alternative. It provides a more mobile-friendly interface for interacting with your coding agents remotely (but it is more limited in terms of features and compatibility, ie using /commands etc…)

Conclusion

VibeTunnel is a handy tool for anyone who wants more flexibility in how they interact with Claude Code. Combined with Tailscale, it opens up the possibility of truly remote development workflows.

While the mobile experience could use some polish, it’s already useful for monitoring long-running tasks and occasionally providing input when you’re away from your main machine.

If you give it a try, I’d be curious to hear about your experience!

Sentire - a command line interface for Sentry API

Sat, 30 Aug 2025 00:00:00 +0000

Introduction

When I use coding agents, I often need to retrieve details from a Sentry issue to provide context for diagnosing the root cause. I’ve been using the Sentry MCP for this, but I wanted to switch to a simpler command-line tool. I assumed sentry-cli would fit the bill, until I realized it’s designed for a different purpose (per their docs):

1
2

It’s primarily used for managing debug information files for iOS, 
Android as well as release and source maps management for other platforms.

At this point I realised I needed a different CLI. I tried to search around but I couldn’t find exactly what I was looking for, so I decided to give it a shot.

What is Sentire?

Sentire is a simple and user-friendly command line interface for the Sentry API, written in Go. The name “sentire” comes from Italian, meaning “to feel” - reflecting its purpose of helping developers feel the pulse of their application’s health through Sentry’s monitoring data.

Sentire provides an intuitive CLI for interacting with Sentry’s API, covering essential operations including managing events, issues, projects, and organizations.

Key Features

Multiple Output Formats: JSON, table, text, and markdown formats to suit different use cases
Comprehensive API Coverage: Essential Sentry operations for debugging workflows
Built-in Pagination and Rate Limiting: Handles Sentry’s API constraints automatically
Human-readable Output: Perfect for terminal usage and quick analysis
Machine-readable JSON: Ideal for scripting and automation
URL Inspection: Parse Sentry URLs directly to get detailed event information

Note: this CLI doesn’t implement (yet) all the Sentry API. I focussed on the commands needed to retrieve projects, issues and events. More commands will be added in future releases.

Installation

Install via Homebrew (macOS):

1
2

brew tap andreagrandi/tap
brew install sentire

For other installation methods (Go install, pre-built binaries, building from source), see the official README.

Complete source code is available on GitHub: https://github.com/andreagrandi/sentire

Getting Started

First, set your Sentry API token as an environment variable:

`1`	`export SENTRY_API_TOKEN=your_sentry_api_token_here`

You can obtain an API token from your Sentry organization settings under “Auth Tokens”.

Then you can start exploring your projects and issues:

# List all your projects
sentire projects list

# Get a specific project
sentire projects get <organization> <project>

# List recent issues for an organization
sentire events list-issues <organization> --query="is:unresolved" --period=24h

# Get detailed information about a specific issue
sentire events get-issue <organization> <issue-id>

Output Formats

Sentire supports multiple output formats to suit different workflows:

JSON (default): Machine-readable format for scripting
Table: Human-readable format with borders for terminal viewing
Text: Clean plain text format for simple parsing
Markdown: Documentation-friendly format for reports

# Human-readable table format
sentire events list-issues my-org --format table

# Markdown format for documentation
sentire org stats my-org --format markdown

URL Inspection

One of Sentire’s unique features is the ability to parse Sentry URLs directly:

1
2

# Inspect a Sentry issue URL and get detailed event information
sentire inspect "https://my-org.sentry.io/issues/123456789/"

This automatically extracts the organization and issue ID from the URL and fetches the most relevant debugging information.

Use Cases

Sentire is particularly useful for:

Debugging Workflows: Quickly inspect Sentry URLs and get detailed event information without leaving the terminal
DevOps Teams: Integrating error monitoring into deployment pipelines with machine-readable JSON output
On-call Engineers: Using table format for quick issue triage and markdown format for incident reports
Development Teams: Multiple output formats reduce context switching between terminal and web interface
Automation and Scripting: Built-in rate limiting and pagination make it reliable for automated workflows
Documentation: Markdown output format perfect for including error analysis in reports and documentation

Conclusion

Sentire brings Sentry to your terminal because, let’s be honest, who has time to click around web interfaces when bugs are breathing down your neck?

It’s open source, so if you find bugs (oh, the irony!), have feature requests, or just want to make it less terrible, feel free to open an issue or send a pull request. I hope you will enjoy it 🙂

Claude Code Status Line Script

Fri, 15 Aug 2025 00:00:00 +0000

Introduction

A few days ago, Anthropic released an update for Claude Code that adds an interesting feature: a new command named /statusline, which will create a script to fetch and show useful information in the app’s status bar and automatically add the configuration for it.

You can either let Claude generate the script for you, or provide your own.

Installation

To install my script, you need to download the bash script from this location save it in ~/.claude/statusline-script.sh, make it executable with

`1`	`chmod +x ~/.claude/statusline-script.sh`

and add this configuration in ~/.claude/settings.json

...
"statusLine": {
    "type": "command",
    "command": "~/.claude/statusline-script.sh"
}
...

Features

As you can see from the above screenshot, the script will display the following information:

`1`	`📁 logbasset \| 🦫 1.24.5 \| 🌿 10-logging \| 🤖 Opus 4.1 \| 💸 $0.00 \| 💰 $14.64/day`

📁 current folder
🦫 language version (in this case it’s a Go app but for Python it will show 💼 (my-app) | 🐍 3.12.9)
🌿 git branch name
🤖 current model
💸 cost of the current session
💰 total cost for the day
⏱️ time left for the current session

The app uses ccusage to fetch costs.

Conclusion

In the last few days there has been an explosion of scripts and small apps which can provide a status line for Claude Code. I decided to give it a try and do my custom one. I hope it can be useful for other people too 😉

Releasing Log Basset: an open source CLI to access Scalyr logs

Mon, 28 Jul 2025 00:00:00 +0000

Introduction

At work, we use Scalyr to access our logs. They provide a web interface and a client written in Python, but it hasn’t been updated in the last couple of years, and I’m not sure if it’s abandoned.

As CLI coding agents become more popular, it’s important to have reliable CLI tools for accessing various services.

Log Basset is a CLI tool for accessing Scalyr logs, written from scratch in Go.

Why Log Basset?

There are a few reasons why I decided to rewrite their tool in Go:

I wanted to have fun 🙂
A tool written in Go is easier to distribute and use (no need to set up a virtual environment)
I was curious to stress test OpenCode and sonnet-4

Yes, this tool was mostly written using AI tools. If that’s a problem for you, please do not use it.

Key Features

Log Basset maintains most of the original features, but I focused on the “read-only” ones. In particular, you can:

query: Retrieve log data
power-query: Execute PowerQuery
numeric-query: Retrieve numeric/graph data
facet-query: Retrieve common values for a field
timeseries-query: Retrieve numeric/graph data from a timeseries
tail: Provide a live ’tail’ of a log

Compared to the original version, it also offers:

Flexible time formats and output types
Strong input validation
Multi-layer configuration
Cross-platform support and high performance

Installation

You can either use one of the packages from the GitHub release page or:

Homebrew (macOS/Linux)

1
2

brew tap andreagrandi/tap
brew install logbasset

From Source

1
2
3

git clone https://github.com/andreagrandi/logbasset
cd logbasset
make build

Usage Examples

Once you have set your API key like this:

`1`	`export scalyr_readlog_token='your-api-token-here'`

You can query logs like this:

# Display the last 10 log records
logbasset query

# Display the last 100 log records, showing only timestamp, severity, and message
logbasset query --count=100 --columns='timestamp,severity,message'

# Display the first 10 log records beginning at 3:00 PM today, from host100
logbasset query '$serverHost="host100"' --start='3:00 PM'

# Display the last 1000 entries in CSV format
logbasset query '$source="accessLog"' --output=csv --columns='status,uriPath' --count=1000

Or tail them:

# Display a live tail of all log records
logbasset tail

# Display a live tail from a specific host
logbasset tail '$serverHost="host100"'

# Display live tail with full record details
logbasset tail --output multiline

A complete guide is available in the project readme.

Conclusion

Log Basset is my attempt to make working with Scalyr logs a bit easier and more enjoyable. If you give it a try and have feedback or ideas, let me know—or even better, open an issue or PR on GitHub!

Comparing Claude Code vs OpenCode (and testing different models)

Thu, 17 Jul 2025 00:00:00 +0000

Introduction

In the past few days Claude Code had some reliability issues and was sometimes unavailable. I started looking for alternative solutions (for context: through my job, I already have paid subscriptions to GitHub Copilot and ChatGPT) but I wanted something that would better fit my workflow.

While I initially used Copilot in VSCode, in the last month I’ve mostly been using VSCode for small fixes, code reviews, and navigating the codebase (asking questions using @workspace still beats any other tool I’ve tried so far). I was primarily using Claude Code (I have a Pro subscription, which is usually enough for my needs).

I discovered OpenCode and liked that it’s not tied to a single provider—it can be used with most existing subscriptions and API keys (in particular, you can use your existing Claude Code Pro/Max or GitHub Copilot subscription).

Having recently worked on a task at work (which I admit it’s simple to medium difficulty), after work I decided to give the same task to Claude Code and OpenCode (used with different models) logged in with my GitHub Copilot subscription.

The Task

I won’t (and I can’t) go into specific details of the task, since it’s work stuff, but I can say it was about:

add a new field new_field to ExistingEntity entity
add new_field to ExistingModel model
create an alembic migration
fix existing tests

The results

Overall, the code produced by these models was correct (with one exception), but in a few cases I had to make some manual fixes or request a second iteration, specifying what needed to be corrected.

Claude Code

Claude was, hands down, the best overall. The initial iteration had a couple of minor problems:

the field was marked as not nullable while I wanted it nullable, but I didn’t specify this initially so it couldn’t guess it correctly
the default value given to the field was quite “odd”

OpenCode (copilot/sonnet-4)

OpenCode (configured with the Anthropic sonnet-4 model from Copilot) unsurprisingly produced almost the same code as Claude Code (with the same minor problems), but it also reformatted some existing code without permission. Last but not least, it added two tests (like Claude), but it removed six existing ones 😨

I had to iterate and tell it to fix, which was very quick to do.

OpenCode (copilot/gemini-pro-2.5)

Gemini… oh dear! I’m not sure if it’s the model itself or if it’s just not optimized for agentic coding (though it should be, since Google just released gemini-cli 🤷🏻‍♂️). It started hallucinating (I could see this as the code was being written) about existing fixtures, added a new unnecessary one, duplicated some existing code, and completely rewrote an existing class—in a bad way—instead of importing it. I honestly didn’t try a second iteration; I just scrapped the whole thing.

OpenCode (copilot/gpt-4.1)

Last, but not least, I switched to gpt-4.1 from the Copilot subscription. The first iteration wasn’t perfect (it was probably a bit inferior to the one produced by sonnet-4) and needed a couple of fixes, but once I told it what to correct, it did so quickly, and the final version was perfect.

Bonus point: using gpt-4.1 through a Copilot subscription offers unlimited usage 🎉

Conclusion

The best tool I’ve tried so far remains Claude Code, but I have to admit that OpenCode with sonnet-4 could replace it soon (especially considering it was released less than a month ago). Even gpt-4.1 wasn’t bad, and honestly, using it through OpenCode yields much better results than using it from within VSCode.

All three models I used with OpenCode tried to reformat existing code. This must be an OpenCode bug, which I’ve tried to mitigate with a rule in the AGENT.md file.

I will keep testing OpenCode over the next few days, and maybe I’ll write a dedicated review about it.

How to use git worktree effectively with Python projects

Sun, 13 Jul 2025 00:00:00 +0000

Introduction

Working with multiple branches in Python projects can be challenging, especially when you need to switch between different features, bug fixes, or versions while maintaining separate virtual environments and dependencies.

git worktree provides an elegant solution to this problem by allowing you to check out multiple branches simultaneously in separate working directories, but it doesn’t keep Python development requirements in mind.

I won’t go into details about how to use git worktree in this post (for that you can check the manual I linked), but I will explain its limitations and present my workaround.

The Problem with Traditional Branch Switching

When working on Python projects, switching branches often means recreating the virtual environment, reinstalling the dependencies, setting the env variables etc…

git isn’t tight to a specific programming language, so by default it can’t do any of this.

In my case I create the virtual environments with uv (like I explain in this other post) but this won’t be automatically available in the worktree folder and it won’t be active.

The Helper Script

To streamline the git worktree workflow with Python projects, I’ve created a helper script that automates the common tasks:

https://gist.github.com/andreagrandi/542b438bf0017d93aff2b640037e3ce1

The script basically does this:

it uses git worktree as usual
it creates a symbolic link to the existing .venv/
it creates a symbolic link to the existing .envrc (which is where I keep my env variables, automatically activated by direnv)
it runs direnv allow to give direnv permissions to read the env variables

Note: You will need to customise the script replacing /my-project-worktrees/ with the name of the folder where you intend to keep your worktrees and /my-project/ with the main folder of your project.

Conclusion

Git worktree is a great tool for working on multiple branches, but it needs some extra setup for Python projects. The helper script makes this much easier by automatically linking your virtual environment and environment variables to new worktrees, saving you time and hassle.

Using terminal-notifier in Claude Code to get custom notifications

Sat, 12 Jul 2025 00:00:00 +0000

Introduction

When working with Claude Code on macOS, you might find yourself waiting for long-running tasks to complete or missing important prompts for user input. The terminal-notifier utility provides an elegant solution by sending desktop notifications directly from the command line, helping you stay informed about your Claude Code sessions even when you’re focused on other tasks.

Note: I decided to use terminal-notifier both because I can customise the notification I receive and also because my setup was having issues and I didn’t always get notifications from my terminal.

What is terminal-notifier?

terminal-notifier is a command-line tool for macOS that allows you to send user notifications from the terminal to the Notification Center. It’s particularly useful for automation scripts and development workflows where you need to be alerted about specific events.

Installing terminal-notifier

The easiest way to install terminal-notifier is through Homebrew:

`1`	`brew install terminal-notifier`

Using terminal-notifier with Claude Code

Claude Code can be configured to use terminal-notifier for sending notifications in different ways. The most realiable (and deterministic) is using the new /hooks feature. Add this configuration to your ~/.claude/settings.json:

"hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title \"🔔 Claude Code\" -message \"Claude needs your input\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title \"✅ Claude Code\" -message \"The task has been completed\""
          }
        ]
      }
    ]
  }

The other method (not deterministic, but you can customise the message you get) is to add instructions to your global or project-specific CLAUDE.md file:

## Notification

- IMPORTANT: YOU MUST ALWAYS DO THIS: When you need to send me a notification because you need input or when you have finished a task, please use terminal-notifier tool like this: terminal-notifier -title "🔔 Claude Code: request" -message "Claude needs your permission to use ...", or terminal-notifier -title "✅ Claude Code: done" -message "The task has been completed"
- Always customise the message using a short summary of the input needed or the task just completed

Save the file and start a new Claude Code session.

Final result

If everything worked, once Claude has finished elaborating a task, you should get a notification like this:

Troubleshooting

Notifications Not Appearing

Check that notifications are enabled for Terminal in System Preferences > Notifications
Ensure terminal-notifier is properly installed and in your PATH
Try running a test notification manually to verify functionality: terminal-notifier -title "Hello" -message "World!"

Conclusion

Integrating terminal-notifier with Claude Code creates a more efficient and responsive development workflow. By receiving timely notifications about task completion and input requests, you can maintain focus on other work while staying connected to your Claude Code sessions.

The combination of Claude Code’s automation capabilities with macOS’s native notification system provides a seamless development experience that keeps you informed without being intrusive.

Using uv to install Python and create a virtual environment

Thu, 30 Jan 2025 00:00:00 +0000

Following my previous post, today I wanted to see if I could replace my pyenv and pyenv-virtualenv usage with uv.

Install uv

If you haven’t done it yet, you need to first install uv using either this method or one of the methods described in the documentation:

1
2

brew update
brew install uv

Install Python

uv can detect Python versions installed in different ways in the system or it can install its own copies. You can check which ones are installed, using this command:

`1`	`uv python list --only-installed`

Now we are going to install the latest (at the time of writing) version of Python:

`1`	`uv python install 3.13.1`

Create a virtual environment

Creating virtual environment with uv is quite easy. We can do it in this way:

`1`	`uv venv --python 3.13.1 --prompt my-project`

With --python 3.13.1 we specify the Python version we want and with --prompt my-project we customise the text that will appear in the prompt.

As the output will say, we can simply activate the environment with this command:

`1`	`source .venv/bin/activate`

Automatically activate the virtual environment

Running source .venv/bin/activate every time we enter the project directory can be boring. We can automate this by using direnv.

direnv is a tool which can automatically set environment variables or run simple commands when we enter inside a directory.

You can install it with:

`1`	`brew install direnv`

Once it’s installed, we need to add this configuration inside our .zshrc:

`1`	`eval "$(direnv hook zsh)"`

or, in case we are using bash, we need to do it inside .bashrc:

`1`	`eval "$(direnv hook bash)"`

At this point simply close and reopen your terminal (it’s the quickest way to reload the configuration) and finally create a file named .envrc inside your project folder, containing these two lines (or append these two lines in case you are already using this file):

1
2

export VIRTUAL_ENV=$PWD/.venv
export PATH=$VIRTUAL_ENV/bin:$PATH

After you save this file and you get back to your terminal, you will get an error like this:

`1`	direnv: error /Users/andrea/Projects/my-project/.envrc is blocked. Run `direnv allow` to approve its content

Just run that command to allow direnv to load your configuration:

`1`	`direnv allow`

Installing Python packages

At this point you can use uv pip (which is a drop in replacement for pip with a few limitations) just like you would use pip:

`1`	`uv pip install requests`

Make an alias for uv pip

If you are happy to use the uv version of pip, you can use it anywhere, even in virtual environments which are not managed by uv. You can create an alias by adding this to your .zshrc (or .bashrc etc…)

`1`	`alias pip="uv pip"`

This way, every time you invoke pip, you will use the uv version:

`1`	`pip --version`

Conclusion

Using uv pip, uv venv and uv python you can definitely speed up Python installation, virtual environments creations and Python packages installation.

But uv is much more. You can also manage dependencies, lock them and do many other things. At this point I don’t feel like switching completely to this tool, especially because a few things (like dependencies locking) are not standard across Python ecosystem and the risk is to use a workflow which is not supported by other existing tools (for example if you are using dependabot you won’t be able to just use uv.lock file, you will need to extract requirements.txt files)

My final advice is to use just the parts which are compatible with your existing workflow and wait until a standard for locking dependencies will be universally accepted, before jumping in with both feet.

Stepping my feet into uv world - part 1

Wed, 29 Jan 2025 00:00:00 +0000

I heard about uv and Astral last year and as I previously mentioned in this blog post, I did (and still have) have some concerns about them.

By the way, inspired by some work a colleague of mine is doing, I wanted to give it a chance and I checked if I could start using it without disrupting my pyenv workflow.

Note: Even if you don’t want to migrate away from your favourite Python environment and virtualenv manager, there are a few ways to use it to speed up your existing configuration, so stay with me.

What is uv?

uv is a package manager for Python which is written in Rust, it’s extremely fast and it’s becoming the favourite package manager across the Python community. As usual, please refer to the official website for more details: https://docs.astral.sh/uv/

Installing uv

It seems obvious but before proceeding with this tutorial, you need to install uv. There are a few different ways described in the official documentation, but if you are using MacOS and also use brew, you can install it with:

`1`	`brew install uv`

Using uv pip

uv reimplements pip so instead of doing pip install -r requirements.txt you can do uv pip install requirements.txt (or similar), and believe me: It’s faster!

This is a pip command I used to upgrade the dependencies in the virtual environment of one of the work projects (I only renamed the project name)

❯ uv pip install -U -r requirements/base.txt
Using Python 3.12.8 environment at: /Users/andrea/.pyenv/versions/3.12.8/envs/my-project
Resolved 74 packages in 879ms
Prepared 8 packages in 1.50s
Uninstalled 8 packages in 300ms
Installed 8 packages in 28ms
 - alembic==1.14.0
 + alembic==1.14.1
 - attrs==24.3.0
 + attrs==25.1.0
 - boto3==1.35.98
 + boto3==1.36.2
 - botocore==1.35.99
 + botocore==1.36.8
 - deprecated==1.2.15
 + deprecated==1.2.18
 - s3transfer==0.10.4
 + s3transfer==0.11.2
 - sentry-sdk==2.19.2
 + sentry-sdk==2.20.0
 - structlog==24.4.0
 + structlog==25.1.0

The speed is impressive! I almost thought the command had failed because it finished so quickly. You can find more details in the docs: https://docs.astral.sh/uv/pip/packages/

Using nox[uv]

For the same project, we use nox as a wrapper to run tests and it takes care of creating specific virtual environments. By default it uses virtualenv but there is a simple trick to make it use uv.

First you need to install nox[uv]

`1`	`uv tool install 'nox[uv]'`

Then you just need to set this environment variable:

`1`	`export NOX_DEFAULT_VENV_BACKEND=uv`

That’s it! I can’t provide the full output of our test suite, but I timed (time nox -s test ...) the execution and by using uv as backend, our virtual environment is created 13 seconds faster!

Conclusion

I used “part 1” as suffix for this blog post, because I’m sure these experiments will continue in the next days, by using more of the available uv tools. Once I’ve learned more, I will share my experience again.

How to workaround Ollama models pull issues

Sun, 26 Jan 2025 00:00:00 +0000

In the past couple of days I was having this annoying issue while trying to pull a model from Ollama: I was running the command ollama pull deepseek-r1:8b, it was downloading something like 4-5% of the model and then the connection was reset, the client was “crashing” and it always restarted from 0%.

It looks like I wasn’t alone: https://github.com/ollama/ollama/issues/8406

Note: I’m running Ollama 0.5.7, it’s likely they will fix the issue in one of the next releases.

Solution

Someone kindly posted a workaround which is a bash script able to invoke Ollama client and resume the download where it was left (Ollama client should to that, but it’s not doing it correctly when it crashes).

Save this script in a file like ollama-pull.sh and make it executable with chmod +x ollama-pull.sh:

#!/bin/bash

die(){
  echo "$1"
  exit 1
}

#DRYRUN=echo

_=$(command -v jq) || die "Need jq"
_=$(command -v curl) || die "Need curl"

[ -z "$1" ] && die "usage: $0 modelname"

name=${1%%:*}
[[ "$1" = *:* ]] && tag="${1##*:}" || tag=latest

OLLAMA_MODELS=${OLLAMA_MODELS-/usr/share/ollama/.ollama/models}

cd $OLLAMA_MODELS || die "Couldn't cd to OLLAMA_MODELS ($OLLAMA_MODELS)"
[ ! -d blobs -o ! -d manifests ] && die "Missing blobs or manifests directory"
manifest_dir="manifests/registry.ollama.ai/library/$name"
[ -e "$manifest_dir/$tag" ] && die "$name:$tag already exists"
[ ! -d "$manifest_dir" ] && { $DRYRUN mkdir -p "$manifest_dir" || die "Couldn't mkdir manifest dir ($manifest_dir)" ; }

manifest=$(curl -sL https://registry.ollama.ai/v2/library/$name/manifests/$tag) || die "Couldn't fetch manifest"
errors=$(jq -cn "$manifest |.errors")
[ "$errors" = "null" ] || die "$errors"

config=$(jq -rn "$manifest | .config.digest") || die "No config digest"

$DRYRUN curl -#L -C - -o blobs/${config/:/-} https://registry.ollama.ai/v2/library/$name/blobs/$config || die "Couldn't fetch config blob"

for layer in $(jq -rn "$manifest | .layers[].digest") ; do
  $DRYRUN curl -#L -C - -o blobs/${layer/:/-} https://registry.ollama.ai/v2/library/$name/blobs/$layer || die "Couldn't fetch layer"
done

[ -n "$DRYRUN" ] && echo "echo '$manifest' > '$manifest_dir/$tag'" || { echo "$manifest" > "$manifest_dir/$tag" || die "Couldn't write manifest" ; }

and run the script in this way:

`1`	`OLLAMA_MODELS=~/.ollama/models ./ollama-pull.sh deepseek-r1:8b`

(replace deepseek-r1:8b with the name:tag of the model you want to pull)

I got a Micro.one blog

Tue, 21 Jan 2025 00:00:00 +0000

I found out about Micro.blog platform thanks to Jeff Triplett a few months ago and I even decided to give it a try, but to be honest, having already a main blog, made with Hugo, which is hosted for free on GitHub Pages, I couldn’t really justify spending another $5/month for a micro blogging platform.

Micro.one

Then Manton Reece (the creator of Micro.blog) announced (actually he didn’t do it officially when I discovered it, but I found out anyway!) a new plan: Micro.one

For just $1/month (or $10/year if you switch to the annual plan!) I can have my micro blog hosted, with custom domain support, I can post text, photos and even podcasts!

What is Micro.blog?

Micro.blog (and Micro.one too) is an hosting solution for static blogs. The user selects a template, creates the content and the platform uses Hugo to create the pages which are then published.

Nothing revolutionary for me, but I reckon this is a quite good solution for many people who would like to have a blog but they don’t have the skills to use Hugo or create a CI jobs which publish to GitHub Pages.

Why a micro blog?

I often have content to post which is too short to justify a proper blog post but it’s too long to be posted on Mastodon or BlueSky. For this type of posts, Micro.blog is perfect!

Conclusion

If you are looking for an easy to use solution to create a personal blog, look no further. Oh, and you can visit mine at this address: https://micro.andreagrandi.it

New Year resolution: sponsoring some of the open source projects I use

Fri, 03 Jan 2025 00:00:00 +0000

After having thought about this for a while, I finally decided to start sponsoring some of the open source projects I regularly use. I set aside a monthly budget and I evenly divided the amount across the projects.

Who am I sponsoring?

So far I’ve started sponsoring these projects / people (in no particular order):

iTerm2 - a terminal for MacOS I’ve been using for years
Sebastián Ramírez - author of FastAPI
Homebrew - a package manager for MacOS
Cryptomator - a tool to encrypt, decrypt and easily access files in various clouds
Pallets - they develop and maintain Flask, Click and a few other tools
Mastodon - the social network I use most
Atuin - a shell history which supports a few different shells

How much am I donating?

If you were expecting to find an amount, please move to the next paragraph 😅

What I can say is that everyone should donate an amount based on their own possibilities and estabilished budget. If all the users of the projects I mentioned, donated as much as I’m doing, those developers would be rich 😉

How am I donating?

For my own simplicity, I decided to support only projects with a Sponsor page on GitHub. This way I can manage all the donations from a single website. I can decide to adjust the amounts and to sponsor more projects. I don’t want to discriminate anyone, but at the end of the day it’s up to me deciding who to support and how 🤷🏻‍♂️

Could I do more?

Yes, but… there was a specific thing which prevented me from donating to other projects I wanted to sponsor. These projects (which I won’t mention, but I’ve contacted them in private to suggest considering a more flexible option) all have a minimum amount set in their Sponsor settings.

Honestly I can’t understand the reason for this, and I’m sure it’s not about fees, because GitHub takes a fixed fees percentage (3% credit card processing fee + 3% GitHub service processing fee) so receiving 1$ from 100 people or 100$ from 1 person doesn’t change the final amount of money the developer receives.

My humble suggestion is to remove the minimum amount: not everyone can or is willing to donate the minimum amount some of these projects have set and you will be able to collect more donations from more people.

Conclusion

My personal opinion is that every cent counts. No matter if you can only afford 5$/month or if you are able to donate 100$/month: every person should donate based on their own preferences and possibilities.

I onestly would prefer to get 1$ from 100 different people than 100$ from a single person. A larger number of people believing in my projects is more important than the final amount.

So, if you really care about open source, beware that GitHub stars can’t be used to pay the bills 😉 please consider donating to the projects you love as much as you can!

My ZSH history

Thu, 02 Jan 2025 00:00:00 +0000

Inspired by this post from Nicola Iarocci, I decided to check my own ~~bash~~ zsh history:

1082 git
99 cd
95 nox
38 pip
37 ls
33 pytest
29 brew
26 code
19 curl
16 pyenv

Even for me, my biggest usage of the terminal is because of git 😅

You can produce your own list by using this command: history | awk '{print $2}' | sort | uniq --count | sort --numeric-sort --reverse | head -10

I got a Basset Hound dog: welcome Fulvio!

Sat, 14 Dec 2024 00:00:00 +0000

I’ve always wanted a dog (actually… my family had one ~30 years ago, but since I wasn’t directly involved with him, I never felt him as my own). Life (and sometimes laziness) had not allowed me to own one in the past (living abroad, moving back to Italy but living in a small apartment etc…) so when I finally had the chance, I got him!

His name is Fulvio and he’s a Basset Hound breed (yes, the same breed as Lieutenant Columbo one 😅)

Since I got him, my life has definitely changed. Mostly for good things (like doing a 45-50 minutes walk every morning which is helping me a lot to be more healthy!) but there are definitely things I still need to get used to 🥲

I’m lucky to have 3 weeks off for this Christmas holidays and this means plenty of time to play with him and to get to know each other.

I don’t have much else to say, so I will leave you with another picture of him.

Greeting from me and Fulvio! 👋 🐶

How to configure an Ethernet connection between iPad and RaspberryPi through USB-C

Sat, 26 Oct 2024 00:00:00 +0000

I recently found out (thanks to this article from Juha-Matti Santala) that not only you can power a RaspberryPi device through the USB-C of an iPad but that you can also get an ethernet connection through it

Requirements

an USB-C iPad (I used an iPad Air 4th gen)
a USB-C cable (I used the one that comes with the iPad)
a RaspberryPi (you need at least a RPI 4. I used a RPi 5)
you already have SSH access to the RaspberryPi (I won’t cover this part in this tutorial)
an updated bootloader on the RaspberryPi (check this documentation)

Configuration

Connect to the RaspberryPi using SSH
Become super user on the RaspberryPi: sudo su
Edit /boot/firmware/cmdline.txt and add these options after rootwait:

`1`	`modules-load=dwc2,g_ether`

Edit /boot/firmware/config.txt and make sure that otg_mode=1 is uncommented. Then add this line after the [all] section:

`1`	`dtoverlay=dwc2`

Use this command to add a new connection:

`1`	`nmcli con add type ethernet con-name ethernet-usb0`

Edit /etc/NetworkManager/system-connections/ethernet-usb0.nmconnection and make sure you have these settings:

[connection]
id=ethernet-usb0
uuid=<random group of characters here>
type=ethernet
autoconnect=true
interface-name=usb0
  
[ethernet]
  
[ipv4]
method=shared
  
[ipv6]
addr-gen-mode=default
method=auto
  
[proxy]

Edit /usr/local/sbin/usb-gadget.sh and add this:

1
2
3

#!/bin/bash

nmcli con up ethernet-usb0

Make the file executable:

`1`	`chmod a+rx /usr/local/sbin/usb-gadget.sh`

Edit /lib/systemd/system/usbgadget.service and add this:

[Unit]
Description=My USB gadget
After=NetworkManager.service
Wants=NetworkManager.service
  
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/local/sbin/usb-gadget.sh
  
[Install]
WantedBy=sysinit.target

Enable the service using this command:

`1`	`systemctl enable usbgadget.service`

Reboot the RaspberryPi:

reboot

Check the configuration is working

Connect the RaspberryPi to the iPad using the USB-C cable and wait for it to boot. Once it finishes booting up, open Settings on the iPad and check if there is an Ethernet section below the WiFi Connection. If you find the entry, then it means the connection is successful.

References

This tutorial has been written thanks to this other tutorial https://github.com/verxion/RaspberryPi/blob/main/Pi5-ethernet-and-power-over-usbc.md

My User Manual

Wed, 11 Sep 2024 00:00:00 +0000

This is my user manual. If we are working together (or planning to), please read it carefully. You will learn how to deal with me productively and avoid misunderstandings. I initially wrote this for my current colleagues, but I thought it could be a good idea to make it public for everyone else I daily interact with.

My style

I need to understand why I’m doing something
I love working as a part of a team, not as an individual
I love pair programming
I like to have a very basic working version first and iterate on it
I love to help

What I value

honesty
direct and straight communication
people who quickly get to the point
leading by example

What I don’t have patience for

process for the sake of process
long meetings where no actions are taken at the end
indirect feedback (heard from third parties)

How best to communicate with me

chat (public channel unless it’s personal)
email is ok…ish
absolutely not by phone

How I make decisions

I need some context first
I understand the problem
I draft some options and evaluate them
I pick the one which is less complicated but at the same time doesn’t prevent further improvements
I iterate and improve the implemented solution

How to help me

give me cooking tips not ready meals! - I appreciate help and I don’t hesitate asking for it when I need, but whenever I do I like to be given tips to unblock me not a ready solution or someone else doing the task for me.
offer me to do pair programming

Random things I like

dogs (especially Basset Hounds)
music (listening to and playing acoustic guitar, bass guitar and analogic synths)
cooking
photography
learning new cool things

Random things I dislike

warm beer
Italian food blasphemy (like putting pineapple on pizza, “fettucine Alfredo”, etc… 😜 )

Building a healthy and sustainable funding model for open source software

Sat, 07 Sep 2024 00:00:00 +0000

If you work in software development, chances are high that your company is using open source software to build their products. Nowadays open source software is nearly everywhere: it can be included in your operating system, in commercial software or it can be responsible for hosting your website or your application.

In this post I will focus mainly on languages, libraries and frameworks which are being used to build software applications, because they are the components I’m most familiar with.

Context

Suppose your company needs to build a new software service which is going to be offered as an API. You will need to pick a language (for example Python), possibly a web framework (like Django, Flask or FastAPI) and some additional libraries (like SQLAlchemy, requests, etc…) to build your service.

Usually developers will pick the tools they are most familiar with, or the tools which are most popular in the community, but very few people ask themselves: who is behind these tools? Who is maintaining them? Who is fixing the bugs? Who is adding new features?

And most importantly: how are these people being paid? (You are not expecting them to work for free, right? 😏)

The current funding models

Some languages and frameworks have a no profit foundation behind them (ie: Python has Python Software Foundation, Django has Django Software Foundation, etc.) which are responsible for managing the project and the community around it.

They can receive a lot of independent donations or being funded by big companies like Google or Microsoft (ie: Guido Van Rossum, the creator of Python, was previously working for Google and now he is currently working for Microsoft).

Big companies (those earning billions every year) usually don’t have any problem spending some money to sustain the tools they also use, but this also means they can have a big influence on the direction the project is taking.

Some smaller projects (like FastAPI) are being funded entirely by independent donations: https://fastapi.tiangolo.com/fastapi-people/#sponsors but this is not a sustainable model for the long term because there is no guarantee that the donations will keep coming.

The Venture Capital model

A different way to fund open source projects is through private investors or venture capital. For example pydantic (a library which is also used by FastAPI) has recently received a $4.7 million investment from a few VCs: https://techcrunch.com/2023/02/16/sequoia-backs-open-source-data-validation-framework-pydantic-to-commercialize-with-cloud-services/

Another quite recent example (which has sparked a lot of discussions in the Python community) is the case of Astral, a small company backed by VCs which are developing a couple of tools for the Python community: ruff which is a code linter and uv which is a Python package and project manager written in Rust.

The opinions from the Community

With specific regard to Astra, there is an interesting conversation happening in a Mastodon thread, and from what I’ve seen, the opinions are quite divided.

Some of them are concerned because this company is using Rust to implement these tools. This could cut Python developers out from directly contributing to the project, because they would need to learn a new language to do so.

Others are concerned because the company is backed by VCs, and they could cut funds at any time, leaving the project in an abandoned state. This of course is a valid concern, but since the project is open source, the community could fork it and continue the development.

Another issue that seems to be mentioned by a few people is the fact that Astral doesn’t seem to have a clear business model (at least until the time of this article). When asked directly, they have been vague about how they intend to monetize their projects and for this reason some people are being cautious before adopting their tools.

Some people are being optimistic instead and looking at this funding as a good thing, because observing how quickly ruff and uv have evolved in so little time, they recognise a lot can be done when people are allowed to work full time on a project.

My own opinion

In the specific case of ruff and uv, I personally don’t have anything against the fact that they are written in Rust. My mantra is “use the right tool for the job”, and if Rust is the right tool for the job (according to their tests, linting the whole CPython code base only takes 0.16s with ruff, while it takes 11.63s with flake8 and even 60s with pylint), then so be it.

By the way, relying on VCs for funding is a double-edged sword: on one side you now have a lot of money to hire people and let them work full time on the project. This ensures the development will proceed at fast pace and issues will be addressed quickly. On the other side, other companies and community members could initially be attracted by the tool, decide to adopt features which are not available (nor compatible with) in other similar tools and eventually find themselves locked in a proprietary ecosystem (check what recently happened to the data scientists community using Anaconda).

What could we do instead

I think an alternative and mid ground solution to the ones described above exists: each company should fund the projects they use and rely on most and / or they should allow employees to dedicate some time to contribute back to these projects.

Funding projects

Let’s pick for example the 5 top components a company could rely on: Python, FastAPI, SQLAlchemy, Pydantic and PostgreSQL.

The company should allocate a yearly budget for these components and donate regularly to the projects. Many companies have no issues purchasing licenses and seats for the services they use, so why donating regularly should be a problem?

By having many companies donating to a project, we avoid that a single company has too much influence on the direction of development. If a single company decides to stop funding a component, there would be many other continuing to support it.

Small projects (those with a single lead developer) could use the money income to be able to work full time on it. Larger projects could hire more people to work full time. The necessary structure and organisation should reflect the size of the project itself.

This would be a win win situation. Developers could work on something they love and being paid for it. Companies could trust the components they use even more because with people working full time on it, it’s more unlikely the project can be abandoned.

This is quite similar to the funding model of Django Rest Framework.

Allowing employees to contribute back

Sometimes project owners need some direct help fixing bugs, preparing releases etc… another way of contribute could be allowing employees to dedicate some work time to contribute back directly. This can have multiple advantages: employees can work on something fun and they can learn new things (reminder: often employees leave a company because they want to work on more interesting stuff and because they are not learning enough in their current role) while projects can get additional (even if not regular) help.

Conclusion

I’m convinced a more sustainable way for funding open source projects is possible. As software developers we can have an high impact on companies (spreading the word, speaking at conferences, leading by example etc…) and this can be beneficial both for the longevity of existing projects and for the safety of companies.

What do you think about this possibility?

It's now possible to use ControlD DNS with Tailscale

Tue, 13 Aug 2024 00:00:00 +0000

If you are using Tailscale in some of your devices, you also need to use Tailscale own DNS server to resolve the names of the devices in the network. If you are also a user of ControlD DNS, and you want to use it with Tailscale, you can finally do it!

Configure a new Endpoint on ControlD

First of all, you need to create a new endpoint on ControlD. You can do it by logging in to your ControlD account, select Endpoints from the left menu, and then click on the plus button.

Scroll down to Router section and select Other as the device type. In the next screen you need to specify a name, I used tailscale-global but you can use any name you want.

Once you have created it, take note of the Resolver ID, because you will need it in the next step.

Configure the DNS on Tailscale

At this point you need to go to Tailscale admin console, and select the DNS tab. Click on the Add nameserver menu, and select “Control D” from the list.

Once you have selected ControlD from the list, you will get this window and you will need to fill the Endpoint using the Resolver ID you got from the previous step.

Now you can click on the Save button.

Verify the configuration is working

The configuration is done! If you already have some devices connected to your Tailscale network, you will be able to check if the configuration is working by checking the endpoints visible in the ControlD dashboard: https://controld.com/dashboard/endpoints

If you see a green dot next to the router icon, it means the endpoint is in use and the configuration is working.

References

Tracking airplanes with a Raspberry Pi and an ADS-B receiver

Sat, 10 Aug 2024 00:00:00 +0000

If you have ever used a flight tracking app like Flightradar24 or FlightAware you might have wondered how they get the data about the airplanes in real time. All these services use an existing network of ADS-B receivers to collect data about the airplanes in the sky.

What is ADS-B?

ADS-B stands for Automatic Dependent Surveillance-Broadcast and it’s a technology that allows aircraft to determine their position via satellite navigation and periodically broadcast it, enabling them to be tracked. The information can be received by air traffic control ground stations as a replacement for secondary radar.

This is all public information (it’s public data and you are legally allowed to receive it and share it).

What do you need?

To build the tracking device you need a few things:

a Raspberry Pi (I’m using a Raspberry Pi 2 Model B)
an ADS-B receiver (I’m using a AirNav RadarBox FlightStick but any RTL2832/R820T2-based USB dongle should work)
a 1090MHz capable antenna (I’m using a Bingfu Antenna RTL SDR, any similar antenna should work, just make sure the connector is compatible with your receiver otherwise you might need an adapter)
a microSD card (I’m using a 16GB one) and a power supply for the Raspberry Pi

Is a Raspberry Pi x enough?

I’m using a Raspberry Pi 2 Model B, which is quite old (it was released in 2015) and it’s not the most powerful Raspberry Pi available. It’s still enough to run the software needed to track the airplanes, but if you have a newer Raspberry Pi (like a Raspberry Pi 4 or 5) you may be able to handle higher workloads (especially if you live nearby a busy airport) and feed multiple services.

If you are still not sure, have a look at the stats of my Raspberry Pi 2 while running the software: I’m using just 23% of the CPU and ~200MB of the total available memory.

Setting up the Raspberry Pi

Once you have all the components, you have two options to set up the Raspberry Pi:

install the software from scratch (this is the most complicated way but it gives you more control over the system)
use a pre-built image (this is the easiest way, you just need to flash the image on the microSD card and you are ready to go) like the one provided by FlightRadar24 or Flightaware

I won’t cover the detailed instructions, but I opted for the first option (also because I wasn’t sure which service I was going to feed).

Something I can definitely suggest, in case you plan to install RaspbianOS from scratch, is to use the Raspberry Pi Imager and to install the Lite version of the OS (you don’t need the desktop environment for this project).

I also suggest to install the Tailscale client and enable SSH access to the Raspberry Pi so you will be able to easily access the RaspberryPi from your computer, regardless of the network you are connected to.

Where to place the antenna?

The antenna should be placed in a location where it has a clear view of the sky. The higher you can place it, the better the reception will be. I placed mine on the window sill, but if you have a balcony or a terrace you can place it there. To facilitate the installation of the device, I strongly recommend to at least use a WiFi connection for the Raspberry Pi, so all you need is a power supply and you just have to pass the antenna cable through the window.

Configuring the feeder

Once you have the Raspberry Pi up and running, you need to install the software to receive the data from the ADS-B receiver and feed it to the services.

The instructions for this step depend on the service you want to feed. In my case I decided to feed to ADS-B Exchange and Flightradar24, which they booth provide detailed instructions and scripts to install the software:

Note: it’s worth saying that if you opt for the easier setup (using a pre-built image) you won’t have to install the software manually, but you will still need to configure the feeder to send the data to the services (by answering a few questions during the setup, about your location and type of receiver).

Add nice stats to your Raspberry Pi

If you want to have some nice stats like the ones I showed you before, you can install install and utility called graphs1090. This utility doesn’t just show you CPU and memory stats, but also data from the ADS-B receiver like the number of messages received, the number of aircrafts tracked, and the number of positions reported.

Which other services could or I should feed?

There are a few other serviced you could feed, and it’s totally up to you which one you want to use. Just keep in mind these two things:

each service you feed will likely give you back a premium account, which will give you access to more features and data. So if you are interested in a specific service, you might want to feed it.
most of the services are “censored” (didn’t I say the data is public?) and they don’t show all the flights. If you want to see all the flights you need to feed to ADS-B Exchange which is the only service that shows all the flights, regardless of the aircraft owner 😏

Here are a few other services you could feed:

Note: some of these services may also send you a free ADS-B receiver or a complete kit if you provide them with a good location to place the receiver (but if you don’t live in a location they are interested in, they won’t send you anything).

Conclusion

With a total budget of around 120€ (Raspberry Pi 2 Model B, AirNav RadarBox FlightStick, Bingfu Antenna RTL SDR) and a couple of hours available, you can build your own flight tracking device and feed multiple services. It’s a fun project and it’s also useful to track the flights in your area. I didn’t know anything about ADS-B receivers before a couple of weeks ago and I totally have to “blame” my friend Alan Pope who told me about this project 😅

References

Here are other useful resources I found while setting up the Raspberry Pi:

Self hosting a website analytics at zero cost

Wed, 31 Jul 2024 00:00:00 +0000

I recently started using Umami (a privacy first, GDPR compliant solution) for this website analytics but I immediately found out that their free plan was not enough for my needs (10k page views per month).

Since it’s completely open source, you can self host it anywhere you want.

I was initially evaluating between buying a Raspberry Pi or renting a VPS, but I eventually found a third solution which comes at zero cost.

Requirements

Your are going to need a few accounts if you want to follow exactly these steps, but keep in mind that my exact configuration is just an example and that you are free to use any other combination of services.

GitHub: used to login on other services and to host a fork of Umami
Umami source code: it’s available on their GitHub account
Vercel: used to host the app itself, they have a generous free plan
Xata: they offer a very generous (15GB) free account for managed PostgreSQL
Cloudflare: this service is optional, but I found it quite useful to get a nice stats.andreagrandi.it which points to the deployed instance on Vercel

I won’t get into every specific detail of the next steps (like “click on the second link of this page, then click…”). If you decide to self host something like this, you should have a basic understanding of how a web application works, what GitHub and a database are etc…

GitHub

Create a GitHub account, if you don’t have one, then go to https://github.com/umami-software/umami and fork their repository into your own account.

Fix Umami migration script

There is an existing issue with Umami initial migration script and Xata PostgreSQL instance. Umami tries to create an extension (which Xata already has) but Xata doesn’t allow the creation of new extensions in the free plan and the returned error will make the script to fail.

To avoid this you need to comment the first line of this migration script (by the way, I got in touch with Xata support too and they mentioned they could eventually avoid returning an error in this case but I don’t have an estimate on when this will be done).

Xata

Before you create the account on Vercel, I suggest you to create the Xata account. You will need the PostgreSQL connection string at hand during Vercel configuration, so it’s better to create it upfront.

You can use the GitHub account to login to Xata, then create a new database and select the “Enable direct access to Postgres” option.

Xata free plan allows you to have a database where you can store up to 15GB of data.

Finally copy the connection string in a safe place, you will need it later.

Connections limit

Since we are here, I suggest you also add connection_limit=10 to the connection string, otherwise you risk to saturate all the available connections in the free plan.

`1`	`postgresql://abc123:<YOUR_API_KEY>@eu-central-1.sql.xata.sh/umami:main?sslmode=require&connection_limit=10`

Vercel

Vercel is an hosting service which allows you to run web applications in a completely managed environment. You won’t have to think about OS upgrades, manually install any framework or think about security. Everything will be managed and all the options can be adjusted from a web interface.

The company behind it is the same behind NodeJS.

Create an account using GitHub login, so you won’t have to use a specific user/password to login.
Import the fork: in my case it’s the one at https://github.com/andreagrandi/umami
Configure the project adding the PostgreSQL connection string: you can find this in the Xata dashboard.
Test the connection and do the first deployment.

Umami

Once the deployment is completed, Umami should be up and running at the address specified here:

At this point you need to change the default password as soon as possible. Login using admin and umami and then go to the settings page to change it.

Cloudflare

In case you already use Cloudflare (I don’t suggest you go through a configuration from scratch just to have a nice url), I will show you what I did to have my stats running on stats.andreagrandi.it

To do this, you need to create a new CNAME record in your Cloudflare dashboard, pointing to the Vercel deployment url, like I did here:

Once the record has been created, you need to go back to Vercel and add the new domain to the project settings (see the previous screenshot), so that the application will be reachable from the new domain.

Complete the configuration

The rest of the instructions are just about configuring the website and adding the analytics snippet to your website. I won’t go into details here, but you can find all the information you need in the official Umami documentation.

Add a website

The first thing you have to do once you login to Umami is to add a new website. You can do this by clicking on “Settings” first, then “Websites” link in the left menu and then on the “Add website” button. You can find the complete instructions here.

Install the analytics snippet to your website

Then you need to copy the tracking code and add it to your website. You can find the complete instructions here. How to do this depends on the technology you are using to build your website, but in general it must be placed inside the <head> tag of your website.

Conclusion

If you are looking for a privacy first, GDPR compliant analytics solution, you should definitely consider Umami. It’s easy to use, free and open-source, and you don’t have to worry about your data being shared with third parties. You can host it yourself and have full control over your data.

Buy or Rent? RaspberryPi vs VPS

Sat, 20 Jul 2024 00:00:00 +0000

Recently I was planning to self host a service I’m using and I was immediately stuck on a decision: should I just buy a Raspberry Pi 5 or rent a VPS?

Requirements

Let’s starts from the basic question: what specs do I need to run this service? Reading around, it seems that something with 4GB of RAM and 20-30 GB of disk could be enough for my needs. Good.

Costs

A Raspberry Pi 5 would cost me around 100€ (including accessories) plus the cost of energy, while renting a VPS with similar characteristics, would cost me around 4,50€/month (I used Hetzner VPS prices as reference).

To compensate costs of purchasing a Raspberry Pi, I should keep running my service for at least a couple of years. After that time, having purchased a Raspberry Pi would come cheaper (if you consider the total cost per month) then keep paying Hetzner.

Complexity

Honestly, both solutions are quite challenging (if you want to do things in the right way) and similar in terms of administration, the main difference would be that in case of a Raspberry Pi, I would have to also include the setup of something like Tailscale Funnel, to be able to expose my device on the public Internet (my provider, Fastweb, doesn’t give public IP addresses to every user and most of them are behind a NAT).

In addition to this, I would also have to do the initial installation of the operating system and the network configuration, but it’s surely not the most difficult part.

Everything else (installing a web server, a database, configuring them, installing and running the service etc…) would be exactly the same.

The solution

Both solutions are valid and both have pros and cons. So, what should one do? The best approach is evaluate both of them and pick the one that suits our needs.

Raspberry Pi (buy)

Let’s analyse the case we buy a Raspberry Pi.

Pros

You physically own the hardware
It can be more fun to own an electronic device
After a couple of years you basically run your service for free (apart from the electricity)
Your data is definitely private

Cons

Home connection is less reliable than a VPS network
If the device breaks after two years, you have to buy it from scratch
A bit more complexity for the initial setup
If you don’t need the service anymore after a couple of months, you are left with an expensive device collecting dust
Physical hardware gets old: the same Raspberry Pi is unlikely to serve you for many years and you will need to buy a new one every few years

VPS (rent)

What if we rent a Virtual Private server?

Pros

Your service is always up (even when your local ISP fails)
You don’t have an high initial cost
If you decide to give up after a couple of months, you have only wasted less than 10€
Easier initial setup

Cons

Your data won’t be private
If you keep running the service after 2 years (or the equivalent considering the cost of the Raspberry Pi) you also keep paying

Conclusion

As you can see, there is no right or wrong solution. Depending on our own priorities and preferences, we may choose to buy something or to rent.

What did I end up choosing for my specific case? Well… in the end I found a third solution which has some of the benefits of both, it was much easier to configure (I got it up and running in less than 1 hour) and most importantly costed me 0€!

But I will talk about it in another post 😉

Python: it is now() time to migrate from utcnow()

Wed, 17 Jul 2024 00:00:00 +0000

This morning I randomly found this post from Miguel Grinberg: It’s Time For A Change: datetime.utcnow() Is Now Deprecated.

The main point is that Python utcnow() method is not timezone aware, and Python 3.12 is deprecating it. Therefore, you should start migrating your code to use now() instead.

Current state until Python 3.11

Until Python 3.11, the utcnow() method returns a datetime object, and you would use it like this:

1
2
3

>>> from datetime import datetime
>>> datetime.utcnow()
datetime.datetime(2024, 7, 17, 12, 17, 9, 835551)

The issue with this method is that it doesn’t include timezone information, so you can’t be certain if the time is in UTC or not.

Changes in Python 3.12

In Python 3.12, the utcnow() method is being deprecated. The new method to use is now(), with the appropriate parameter to make it timezone aware:

1
2
3

>>> from datetime import datetime, timezone
>>> datetime.now(timezone.utc)
datetime.datetime(2024, 7, 17, 12, 20, 21, 831261, tzinfo=datetime.timezone.utc)

Start migrating now

The good news is that you can start migrating your code now, even if you are not using Python 3.12 yet. This way, when you upgrade to Python 3.12, you won’t have to worry about this change.

My curated list of indie blogs

Fri, 12 Jul 2024 00:00:00 +0000

Recently I finally restarted to read indie blogs more regularly. To do that I’m using NetNewsWire, a free and open-source RSS reader for macOS and iOS and every time somone posts an interesting article, for example on Mastodon, I make sure to follow the RSS feed of that blog.

In a few weeks, I’ve collected a list of blogs that I follow and I thought it would be nice to share it with you. I’m trying to read less mainstream news and more personal blogs, because I think that the personal touch of a blog is what makes it interesting and unique.

Some of the blogs I follow

Here are some of the blogs I follow and recommend. I try to read all the blogs I follow, but these surely are the ones I read more often:

Brain Barking

Author: dr. Wouter Groeneveld

A blog about tech, games and food.

Jeff Triplett’s Micro.blog

Author: Jeff Triplett

Jeff is a DjangoCon organiser and a Python Software Foundation Fellow. He writes about Django, Python, and other tech topics.

Juha-Matti Santala

Author: Juha-Matti Santala

Juhis writes a lot! About tech, life, and about writing. He often inspires me to write more.

Terence Eden’s Blog

Author Terence Eden

Terence writes about tech, privacy, and other interesting topics. He often writes about very original gadgets and services and I always learn something new from him. Bonus point, he’s also a very nice person!

Full list

You can find the full list at this address: https://gist.github.com/andreagrandi/3226460db523a4c60e72f22e9ad896e9 or you can download the OPML file from here.

Tell me about your blog!

I’m always looking for new blogs to follow, especially if they are indie blogs. If you have a blog and you think it’s worth reading, please let me know either as a reply on Mastodon, or leaving a comment on the gist on GitHub.

Cryptomator: end-to-end encrypt files in any cloud

Mon, 08 Jul 2024 00:00:00 +0000

If you are using a cloud storage service like Google Drive, Dropbox, OneDrive, etc., you should be aware that your files are not encrypted by default. This means that the cloud provider is able to access and, in some cases, even share them with third parties. In case your cloud provider gets hacked, your files could also be exposed to the public.

To prevent this from happening, you can use a tool like Cryptomator to automatically encrypt your files before uploading them to the cloud.

How does it work?

Cryptomator is a free and open-source software that allows you to create an encrypted vault on your computer where you can store your files. Once you have added your files to the vault, Cryptomator will encrypt them using strong encryption algorithms (256 bit AES).

To be more clear, Cryptomator doesn’t upload your files. Your cloud provider application does:

You write files to the Cryptomator vault -> Cryptomator encrypts them and writes them in a folder which is synced up to your cloud provider -> Your cloud provider application uploads the encrypted files to the cloud.

When you want to access your files, you simply access them from your mounted vault and Cryptomator will automatically decrypt them for you.

Once the application is installed, you will see a new volume in your file manager and you will be able to work with your files as if they were on your file system. The cloud provider will only see the encrypted version of them:

What systems are supported?

Cryptomator is available for most operating systems, including Windows, MacOS, Linux, Android and iOS. This means that you can use it on your desktop computer, laptop, smartphone or tablet. The only limitation is that your cloud provider must have an application for the platform you are using, so you can keep your encrypted files in sync.

I personally use it to keep my files safe on pCloud and I access them from my Mac, iPhone and iPad. Yes, I’m aware that pCloud has its own encryption system, but it comes at an additional cost to the user. I also think that it’s safer if they don’t have the encryption keys, in case they get hacked.

How much does it cost?

Cryptomator is free and open-source, which means that you can use it without paying anything. The only application that is not free is the one for iOS, which costs a few dollars if you want to unlock all the features (for example the ability to write files), but you can still use it for free to read files (and there is a demo version available too).

Conclusion

If you are using a cloud storage service and you want to keep your files safe and secure, you should definitely consider using Cryptomator. It is easy to use, free and open-source, and you don’t have to worry about your cloud provider being 100% safe, because even if your files get leaked, they will be encrypted and no one will be able to read them without the encryption key.

If your website uses Cloudflare, you can now easily block AI bots

Sat, 06 Jul 2024 00:00:00 +0000

If you own a website and you don’t want AI bots to crawl it and you are already using Cloudflare, you are in luck. Cloudflare has recently added a new feature that allows people to easily block AI bots from crawling their website.

Setup

To enable this feature, you need to login to your Cloudflare account, select the website and once you are in the dashboard, go to the “Security” section and finally click on the “Bots” link.

From there you need to enable both “Bot Fight Mode” and “Block AI Scrapers and Crawlers”.

Yes, it’s that simple! And you will be happy to know that this feature is available to all Cloudflare users, even those on the free plan.

Does it really work?

According to Cloudflare logs, there seem to be a lot of AI bots trying to crawl my website. Here you can see just a few of them:

In particular you can see a bot coming from Singapore and recognised as Bytedance (the same company that owns TikTok) which are well known for their scraping activities.

Other AI companies, like PerplexityAI, seem to have found a way around these blocks, because if you try to ask Perplexity to summarise one of the pages of this website, it will still be able to do it, but I’m sure that Cloudflare will soon find a way to block them too.

Conclusion

I think people should be able to decide if they want their content to be used by AI models or not and Cloudflare is now providing an easy option to do that. AI tools are not bad per se, but they should not be built using other people’s content without their consent.

We need an evolved robots.txt and regulations to enforce it

Sat, 22 Jun 2024 00:00:00 +0000

The robots.txt file is a simple text file that tells web robots (like search engine crawlers) which pages on your site to crawl and which not to crawl. It’s a standard that has been around for a long time and it’s still used today.

Some examples of rules you can put in a robots.txt file are:

1
2

User-agent: *
Disallow: /private/

This rule tells all web robots to not crawl the /private/ directory.

1
2

User-agent: Googlebot
Disallow: /users/

This rule tells Googlebot to not crawl the /users/ directory.

Then AI came

In the age of AI, the existing robots.txt specification is not enough to express the rules for web crawlers. We can only tell agent if they can or cannot crawl a certain path, but we cannot express more complex rules.

In my opinion we should be able to express more detailed rules, like:

Indexing: should a web crawler be able to index the content?
Caching: should a web crawler be able to cache the content?
LLM Training: should a web crawler be able to use the content to train a language model?
Summarising: should a web crawler be able to summarise the content?
etc…

Some of the above things were not possible in the past and it should be up to the website owner to decide if they want their content to be used in such ways.

Enforcing the rules

In addition to more detailed rules, we need new regulations to enforce them. It looks like the robots.txt file is not enough to stop certain companies from doing what they want.

As someone recently found out, Perplexity AI is using a fake user agent to crawl websites, pretending to be a regular user. This is a clear violation of the rules specified in robots.txt file. This claim has recently been confirmed by Wired and by MacStories.

Conclusion

As we have seen, having good rules is not enough if they are not enforced. In particular we need regulators to take care of complaints from content owners and fine companies that do not respect the rules (like Perplexity AI), because small content creators cannot afford to take legal actions against big companies.

As with every single thing, it’s never “the tool”, but rather “how you use it”. AI itself can bring innovation in certain fields, but this can’t be done at the expense of other people’s work and rights.

Disclaimer

Yes, of course the cover image has been generated with AI. It’s far from perfect, but it’s still better than my drawing skills. The content of this article instead is 100% human generated.

Simple and free solution to read content from RSS feeds on iOS and MacOS

Tue, 04 Jun 2024 00:00:00 +0000

Reading news and blog posts can be quite time consuming if we manually go to news websites to check if something new is out or if we spend all day checking social media, waiting for people we follow to post their latest article.

An efficient way to fetch new content is to follow the news sites and the blogs we want, using their RSS feed.

What is the best way to do this for iOS and MacOS? There is no “best” way, since there are plenty of RSS clients and combinations of services, but I will tell you a simple and free solution I’m using.

NetNewsWire and iCloud sync

The client I’m using is NetNewsWire. It’s free, open source and available for both iOS and MacOS.

This client supports different synchronisation services, including iCloud, FeedBin and Inoreader or it can be used just on a single device, without using any of these services.

I initially tried using Inoreader and it was “ok”, but it’s a paid service which injects ads in its free plan. Also, its cheaper paid plan only removes ads, without offering any additional value. I really couldn’t justify paying a subscription just to keep my feeds synced across devices, so I opted to use iCloud which, in my case, is exactly what I need and I don’t have to purchase any additional plan (I’m already on a paid plan, but even the free plan is enough for this).

Conclusion

I’m sure there are better solutions around (especially RSS clients) and I would be glad to hear about them, but for now this simple client and iCloud is all I need to enjoy the news and read blog posts.

Truncating time when querying a PostgreSQL database

Sat, 18 May 2024 00:00:00 +0000

When you have to compare dates in a SQL query, you often want to ignore the time part. For example if you have two very common fields like created_at and updated_at and you want to know if they are the same day, you have to truncate the time part.

How to do this depends on the database you are using. Here is how you can do it in PostgreSQL.

SELECT * 
FROM users 
WHERE DATE(created_at) <> DATE(updated_at)
ORDER BY created_at DESC;

This query will return all the users where the created_at and updated_at fields are not on the same day, ignoring the time part.

AI won’t take your Software Developer job (not yet)

Wed, 01 May 2024 00:00:00 +0000

In the last 3 days I had the opportunity to participate to an internal hackathon organised by the company I work for.

We had to build a project based on an SDK and the needed skills to build it were those of a frontend developer.

Being a backend developer and having very basic (almost none) frontend skills, I was suggested to use ChatGPT to write some of the code.

Challenge accepted

Of course I accepted and I worked on the project with another colleague (also backend developer) who also used ChatGPT to write some of the code.

How I normally use ChatGPT

ChatGPT is not new to me. I use it daily for my work, but I mostly use it as a “search engine on steroids”.

Rather than searching something on a search engine, read a few blog posts or forums, then landing on a Stack Overflow page, to find some code and adapt it, I ask the same question to ChatGPT and then I adapt the produced example.

I never ask for a complete feature or even a whole method. I usually need a small example for a very specific thing which I then insert in an existing code base.

How I used it for the hackathon

In the case of the hackathon, I knew what I wanted to achieve, but I had no idea how to do it, so I asked it to produce almost everything I needed.

At the beginning it was easy: I had nothing and I was adding small pieces every time.

After a little bit I ended up with a lot of code I couldn’t understand anymore.

I was having an issue with the produced code and ChatGPT, instead of helping, started to allucinate.

Instead of asking it to fix a specific issue, I was passing back the whole JavaScript file, asking for the issues to be corrected.

I didn’t notice that while fixing the issues, ChatGPT was also rewriting the whole file and in a couple of occasions it started changing the logic entirely.

The errors disappeared but the code started behaving differently.

In the end we had to revert to a simpler and older version of our code, which at least was working correctly.

Conclusion

I remain confident that tools like ChatGPT can be valuable assets for software developers, provided they already possess a strong understanding of the relevant domain, such as Python backend development in my experience.

However, for areas outside one’s expertise, such as frontend development, relying solely on ChatGPT is insufficient.

What is your experience with similar tools? Let me know in the comments.