Let me show you what happened when I decided to automate this process using Claude Code and our AIStor MCP server. If you’ve been following this series, you know that the AIStor MCP server allows us to use natural human language to perform administrative tasks on our object stores. Instead of running standard command-line tools (and remembering all the arguments and flags), I can simply ask the MCP server, “create a policy” or “create a user” and explain what I want in human language.

The same approach works for debugging complex production issues, reproducing environments for testing, or quickly spinning up development environments that mirror your production setup. Let me show you how I used it for demo creation—but keep these other use cases in mind as you read. We’ll discuss them at the end of the post.

The challenge: Building a realistic business and technical scenario

I wanted to create a technical demo that showcases AIStor Tables (our implementation of Apache Iceberg Tables) in a way that resonates with enterprise customers. The scenario I had in mind was straightforward:

A typical company with customers, suppliers, and partners, where:

• Each relationship type gets its own bucket
• Documents are organized by type (contracts, meeting notes, reports, analytics)
• Different teams have different access levels
• Sales teams can write to their customers’ buckets and read from others
• Purchasing has full access to supplier buckets
• Partner management controls partner buckets
• C-level executives have full access to everything

For the demo, I wanted:

• 3 customer companies with 3 sales teams
• 2 suppliers with a purchasing department
• 2 partners with a partner management team
• C-level team with CEO and CFO
• Realistic company names and documents
• Proper IAM policies for access control

The traditional approach: 5 hours of manual work

If I were to set this up manually using mc commands, here’s what it would involve:

Creating buckets: about 4 minutes. Simple enough:

mc mb tables/universal-products
mc mb tables/global-services
# ... and so on

Creating documents—this is where it gets painful. Around 1.5-2.5 hours:

• Create each file locally in a text editor or find and download from the internet
• Write realistic content (contracts, meeting notes, analytics reports)
• Save files with proper paths
• Upload each one with mc cp

For 28 documents ranging from simple CSV files to detailed analytics reports, you’re looking at 2-8 minutes per document.

Creating users - About 12-15 minutes:

mc admin user add tables sales-team1-user SalesTeam1SecurePassword2024!
# ... repeat for each user

Creating groups and adding members - Another 12-15 minutes:

mc admin group add tables sales-team-1
mc admin group add tables sales-team-1 sales-team1-user
# ... and so on

Creating IAM policies—the really tedious part. 45-90 minutes:

cat > sales-team-1-rw-policy.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
    "Resource": ["arn:aws:s3:::universal-products/*"]
  }]
}
EOF
mc admin policy create tables sales-team-1-rw-policy sales-team-1-rw-policy.json

Multiply that by the number of required policies, factor in JSON syntax errors, wrong ARNs, debugging time…

Attaching policies - 10 minutes of copy-paste-fix-repeat

Verification - 10-15 minutes, making sure everything is set up correctly

Add context switching and errors - Another 30-60 minutes for typos, wrong paths, JSON debugging.

Total time: 4.5-6 hours for an experienced user. First-timers? Easily 6-8 hours.

What if I told you this entire process could be done in 7 minutes?

The automated approach: 7 minutes

Instead of spending half a day on manual setup, I decided to use Claude Code and the AIStor MCP server for that. Following the concept of “spec-driven development,” I did it in two steps. First, I asked Claude to create a specification file in Markdown based on my explanation of what I want to achieve. Second, I passed that Markdown file to Claude Code for execution.

Here’s what I asked Claude to do using the AIStor MCP Server:

I want to create a demo that showcases Iceberg Tables’ capabilities using a typical company with customers, suppliers, and partners. Create separate buckets for our customers, suppliers, and partners. In each bucket, collect documents such as contracts, meeting notes, quarterly reports, and analytics. Create sales teams with read-write access to their customer bucket and read-only access to other customer buckets. The purchasing department has full access to all suppliers’ buckets. The partner department has access to all partners’ buckets.

Create three customers, three sales teams, two partners, two suppliers, and purchasing and partner teams. Use fake company names, such as Universal Products and Global Services. Create individual buckets for each company. Create sample documents for each bucket in Markdown or CSV formats. Create one user in each team. Create a C-level team with full access to all buckets with the CEO and CFO users.

I added that I want to create a Markdown document to pass to Claude Code for execution via the MCP server. The MCP server was already connected to this instance of Claude Desktop, so it had all the information about available tools and their parameters. As a result, Claude created a comprehensive setup guide document that specified exactly which MCP tools to use for each step.

Claude Code then proceeded to:

• Connect to the cluster
• Create the buckets
• Create realistic documents
• Create users
• Create groups
• Create IAM policies
• Attach all policies
• Verify everything

Total: 68 MCP tool calls executed in about 7 minutes.

What made this possible?

The AIStor MCP server I’ve been writing about in this blog series provides Claude Code with direct access to MinIO operations through the Model Context Protocol. Instead of generating instructions for me to execute, Claude could directly:

• Create buckets
• Upload objects with full content
• Manage users and groups
• Generate proper IAM policies with correct JSON syntax
• Attach policies to groups
• Verify the setup

All through natural language interaction.

The key difference from manual setup:

• No file creation overhead - Documents were created directly in buckets using the text_to_object tool, not saved locally first
• No JSON debugging - Claude generated syntactically correct IAM policies on the first try
• Parallel execution - Multiple operations run simultaneously
• Error prevention - Consistent naming, no typos, correct paths
• Built-in verification - Each step was validated automatically
• Progress tracking - The todo list managed the entire process

The results

Here’s what got created:

7 buckets organized by business relationship:

• universal-products, global-services, premier-solutions (customers)
• quality-components, reliable-materials (suppliers)
• strategic-alliance, innovation-collaborative (partners)

28 documents with realistic content:

• Service agreements with specific terms ($500K-$1.2M contracts)
• Quarterly business review notes
• Performance metrics in CSV format
• ROI analyses with detailed financial projections

7 users properly configured:

• 3 sales team users (one per customer)
• 1 purchasing user
• 1 partner management user
• 2 C-level users (CEO and CFO)

6 groups with correct membership and policies

9 IAM policies defining precise access control:

• Read-write policies for primary buckets
• Read-only policies for cross-team visibility
• Department-specific full access policies
• C-level full access policy

The access control matrix works exactly as designed:

The time comparison

Let’s be precise about the time savings:

Manual setup: 4.5-6 hours (270-360 minutes) Claude Code + AIStor MCP: 7 minutes Time saved: ~4 hours 53 minutes Speed improvement: 38-51x faster

But it’s not just about speed. The automated approach eliminates:

• Repetitive typing
• JSON syntax debugging
• Context switching between the terminal and the text editor
• Mental load of tracking what’s done
• Risk of typos and inconsistencies
• Frustration from small errors

This means you can iterate on environment designs quickly, respond to customer requests same-day, or rebuild environments for troubleshooting without blocking your day.

Next step: using it with AIStor Tables

With this environment set up, I can create an AIStor Tables catalog of these buckets that contains all documents’ metadata, summaries, and keywords. With such a setup, I can build Agentic AI workflows to run cross-bucket queries:

• “Find all contracts with value > $500K”
• “Which suppliers have defect rates below 0.5%?”
• “Show me all partnerships with ROI > 100%”

I also can:

• Build AI agents that navigate across organizational boundaries
• Demonstrate how LLMs can work with properly structured data
• Show the power of combining object storage with AI capabilities
• Use analyze_object to generate summaries
• Use ask_object to query specific documents
• Search across multiple buckets for insights

Stay tuned to the next blog covering these demos.

Other scenarios of using MCP servers and AI capabilities

This automation capability matters for anyone who needs to create reproducible environments.

For example, imagine you want to debug a complex issue involving access policies, replication rules, and information lifecycle configurations (e.g., when to expire or migrate certain versions of objects to another tier). Using the MCP server, you can quickly collect all the configuration information from your production environment and reproduce it in your test environment. Or you want to test a new version of the AIStor server and ensure your applications work correctly. The closer you can reproduce your production environment, the better.

This applies to many scenarios:

• Customer proof-of-concepts
• Training workshops
• Development and testing environments
• Compliance and audit scenarios
• Disaster recovery testing

When you can go from “here’s what I need” to “it’s ready” in 7 minutes instead of 5 hours, you fundamentally change how you approach environment creation. And when the setup is deterministic and repeatable, you eliminate the “works on my machine” problems.

The combination of Claude Code’s natural language understanding and the AIStor MCP server’s direct access to MinIO operations creates something that feels almost magical—but it’s just good engineering and thoughtful integration of AI capabilities.

Try it yourself

The AIStor MCP server is now available as a tech preview. Please reach out to us for installation instructions so you can try it yourself.

The future of infrastructure automation isn’t just about scripting—it’s about describing what you want in natural language and letting AI handle the implementation details. We’re building that future, one MCP tool at a time.

This is the fourth post in our series on the AIStor MCP server. Previous posts covered basic object operations, administration functions, and how it works internally.

Pavel Anni is a training specialist at MinIO, focused on making object storage accessible and powerful for developers and enterprises.

Originally posted at https://blog.min.io/automating-cluster-deployments-with-mcp/

Now, let’s discuss the internals: how this works and how we developed this MCP server.

High-level MCP architecture

The purpose of the Model Context Protocol is to be a universal mediator between the Large Language Model (LLM) and various resources and tools. The protocol is used with a language model to translate human language into the language accepted by the resource or tool. In the case of the AIStor server, we translate human-language requests, such as “list objects in the bucket ‘demo’,” into MCP tool calls, which are then translated into SDK calls to the AIStor object store.

Here is how the language transformation is happening in the MCP workflow:

• The user asks the LLM client (e.g., Claude Desktop) to perform an action using natural language (e.g., “list objects in bucket demo”).
• The LLM translates the request from human language to a JSON-RPC 2.0 request with parameters, such as the bucket name.
• This request is sent to the MCP server, which translates it into a function call from the resource SDK (e.g., the MinIO SDK for Go).
• The resource sends the response back to the MCP server (e.g., a list of objects in this bucket as a Go slice).
• The MCP server converts this list to plain text or JSON and sends it back to the client.
• The client sends this response to the LLM to translate it into human language.

And here is the flowchart diagram.

Tools and languages

Several SDKs for MCP are available for different languages. Some SDKs are provided by Anthropic (Python, TypeScript, Kotlin, and Java), while others are created by the community (Go, Rust, etc.).

The prototype of this server was created in Python using the SDK provided by Anthropic.

For the production version, we switched to Go. Most of the MinIO object storage software is written in Go, so it was a natural choice for us. We implement MCP server functions, such as listing buckets, retrieving object information, and setting object tags, using the MinIO SDK for Go. With Go, it’s easy to create and distribute executables for various architectures and operating systems.

We use the mcp-go library created by Mark III Labs, which is widely accepted by the community.

Server architecture

This server consists of 25+ tools that work with the object storage cluster, including core commands such as ’list buckets’, ‘get object tags’, ‘get bucket transition rules’, etc. Each function is a gateway between the object storage cluster and the MCP client. It translates the response it receives from the cluster to plain text or JSON and sends it to the client, in this case, Claude for Desktop.

Functions are grouped by their level of access to the cluster resources:

• Read-only tools (enabled by default)
• Tools that can write to the cluster (enabled by the --allow-write flag)
• Tools that can delete objects and buckets (enabled by the --allow-delete flag)
• Admin tools (enabled by the --allow-admin flag)

Depending on the flags used to start the server, it enables certain groups of tools. For example, adding the allow-write flag to the server command in the configuration file will enable functions that can create objects and buckets.

Distribution

This server runs as a Docker container on your host OS. We decided to distribute it as a standard OCI container image because it is more common for our users to have a container platform (such as Docker or Podman) installed on their desktop or laptop than Python or Node.js tools, which are typically used by other servers.

To run this server, you don’t have to clone a repository or install the uv tool for Python. You configure the claude_desktop_config.json file by adding the appropriate docker or podman command and setting the necessary flags and environment variables.

MCP clients

This server can be used with multiple clients that support the MCP protocol. It has been tested with Claude for Desktop, Cursor IDE, mcp-cli text-based client, and others.

Security

We previously mentioned security considerations in our blog. Here are some implementation details.

The server is configured via the claude_desktop_config.json file. To access the object store cluster, you must provide the credentials, including access and secret keys, via environment variables. You can use your personal credentials or create a special user account for the MCP server. We recommend the latter. When creating a special user account, you can create and attach fine-grained policies that give that account access only to specific buckets and functions. Please consult the MinIO documentation (Access Management — MinIO Object Storage for Linux) on creating such a policy.

Sequence diagram

Let’s look at the more detailed diagram of the sequence of events here. It shows the flow between the user, the LLM, the MCP server, and the AIStor object store.

There is no need to explain a picture worth one thousand words, but it’s important to note that the objects don’t leave the object store. Even when you ask a question about the image content, it is analyzed inside the object store cluster, not by the LLM you use.

Conclusion

The MCP server for MinIO AIStor is an excellent addition to traditional methods of interacting with object storage via the command line and/or the UI. It’s like having a universal translator between what you want to do and what the machines need to hear. No more memorizing complex commands or syntax – just tell it what you need in plain language.

In addition to translating from natural language to the server language, the MCP server can utilize LLM to summarize cluster information, including bucket contents, storage distribution, and cluster status. This is something that wasn’t possible with just CLI or UI tools.

As language models become more sophisticated, the way we interact with our storage systems will feel increasingly natural.

Security of MCP servers is one of the hot topics recently. We’ve built in flexible yet strong security, so admins can still control who has access to what. We have implemented several layers of security protections on this server, with the principle of least privilege in mind.

With this MCP server, MinIO isn’t just democratizing object storage; it’s rethinking how we work with technology in a world where machines are becoming increasingly adept at understanding us. We’re excited to see what cool things you’ll do with this technology and how it’ll change your relationship with your data.

In this blog, we’ll learn how to use the same approach to supplement AIStor administrative functions, such as getting information about the cluster’s status and health, analyzing data distribution, and other tasks.

Experienced MinIO system administrators are not afraid of the command line. They can easily use the mc admin commands to manage their clusters. What could using LLM and MCP servers add to their experience? LLMs are great at summarizing large amounts of information and can be used to format the information we get from the cluster in a human-readable way.

Less advanced users who also need information about the cluster status can use LLM capabilities to get a simple answer to their questions instead of calling their admin.

AIStor cluster admin info

When we want to get admin information about the cluster, we run mc admin commands. Usually, they give you a list of nodes and disks with information about their health and utilization. What if we ask LLM the same question?

Here is the summary from the MCP server working with Claude.

Now, imagine you are the administrator of this cluster, and your boss is asking you about its state. Would you be more comfortable presenting this report instead of a command-line output?

Even if this is too much information for your boss, you can ask for a shorter report. It’s just one prompt away.

And the answer was:

This is unimaginable with the current command-line or UI tools. Having such a concise summary of your cluster health is extremely valuable. We even got a recommendation from Claude.

Besides the health status, let’s ask about available space and overall data distribution. Of course, you can get this information by analyzing the output of the mc admin info --json command, but maybe LLM can do it too?

Wow, this is helpful! Claude provided each bucket’s total size, number of objects, and their characteristics. Did you notice the beautiful table it created? You would spend a good portion of a day building it by hand.

What if we ask to create a pie chart? Can Claude do that?

And it did it!

Let’s ask for the cluster diagram.

Object versioning

One of the essential features of object storage lifecycle management is versioning, in which each write of an object is stored as a unique object. Versioning is typically not enabled by default. Imagine you are a data scientist and don’t remember the exact command to check if versioning is enabled on a bucket. Use human language and ask:

Claude not only answers but also gives you a good explanation of the capabilities.

This is an excellent reminder of the importance of versioning, especially for inexperienced cluster administrators and less privileged users. What about the other bucket?

Note that we used normal human language; we didn’t specify exactly what we needed, and still, Claude understood us perfectly.

This is another excellent explanation of why versioning is important and why it might be disabled for this bucket. Instead of asking our cluster admin, let’s enable versioning for this bucket, too. We don’t remember the exact command, but it’s not a problem.

We didn’t specify which bucket we wanted to enable versioning on, but Claude remembered the conversation’s context and took the right action.

Note the suggestion at the end. Let’s follow it. Trust but verify, right?

And it was confirmed.

Information lifecycle management (ILM)

You can also use human language requests to get information about the lifecycle management configuration, such as rules for keeping versions of an object and deletion restrictions.

And here is the summary.

Again, Claude not only gave us basic information (what we would expect from a command line or UI tools) but also explained its meaning. This is where an MCP server shines as a supplement to traditional command-line administration - it provides context and guidance to simplify and accelerate tasks.

Security considerations

Security is one of the first questions usually asked about MCP servers. How do we control what they can do if we allow them to work with our file systems, databases, and object stores?

We do it on multiple levels with the AIStor MCP server. First, the server starts in read-only mode by default. Second, we added special flags to the MCP server to give it additional capabilities. The user can add the following flags: --allow-write, --allow-delete, and --allow-admin. Certain functions won’t even be visible to the LLM without these flags. The LLM won’t even know that the server can delete objects or get cluster information.

In addition, all the object store privileges and rights are applicable. We suggest creating a separate account for this server and a security profile allowing only the necessary operations. We recommend using the server first in read-only mode, mainly to summarize buckets and objects. If there is a need for admin-level information, use the diagnostics profile that exists by default in each cluster.

Conclusion

When combined with LLM capabilities, the MCP server adds new capabilities to AIStor’s administration and user experience. It transforms complex command-line outputs into human-readable summaries, provides concise answers to cluster status queries, and generates visual aids like pie charts and diagrams. This approach empowers both administrators and regular users to gain quick and understandable insights into their cluster’s health, data distribution, and object management.

Furthermore, integrating LLMs is a valuable learning tool, offering explanations and context alongside information retrieval.

Security is addressed through multiple layers, including a default read-only mode and specific flags for granting additional capabilities, ensuring controlled and secure access to administrative functions. The MCP server, therefore, offers a powerful and intuitive way to manage and understand AIStor clusters, making it a valuable asset for any organization.

Model Context Protocol (MCP), recently announced by Anthropic, is a standard model for how applications and services can be discovered and interacted with in a universal way. MCP also leverages language models to summarize the rich output of these services and can present crucial information in a human-readable form. MCP is therefore a crucial step for unlocking the potential of human-in-the-loop as well as fully autonomous agentic workflows. MCP is analogous to USB-C, which is a standard for connecting devices and operating systems. MCP connects agents to software applications and services. Until now, every agentic developer has had to write their own custom plumbing, glue code, etc., to do this. Without a standard like MCP, building real-world agentic workflows is essentially impossible.

MinIO, the world’s leading AI storage provider, has a rich history of innovation, and we have been pushing boundaries at the intersection of storage, data, and AI. Today, we are thrilled to deliver another industry-first innovation—Model Context Protocol (MCP) for enterprise AI storage. We are previewing an MCP server that enables interaction with and management of MinIO AIStor, our commercial object-store offering, simply by chatting with an LLM such as Anthropic Claude or OpenAI ChatGPT. This preview release includes more than 25 commonly used actions, making exploring and using data in an AIStor object store easier than ever.

This blog post is the first in a series covering various features of the MinIO MCP server. The series will show you user-level and administrative functions performed with the MCP server. We will also tell you how it works inside and how it’s being developed. We will describe using the MCP server as part of a typical Agentic AI workflow.

Let’s explore the exciting new capabilities of the MinIO MCP server. Watch the video or read the text below it to learn about user-level operations with the MCP server for AIStor.

Bucket and object operations

Let’s see how easy it is to explore data in an AIStor object store using MCP. In the following screenshots and dialogues, I’ll show you some operations with the AIStor object store using Anthropic Claude for Desktop client. Plenty of other MCP clients are available, and you can configure all of them to use the AIStor MCP server.

I started with a simple request.

Claude asked me if it was allowed to use the tool to list buckets.

Claude asks for permission every time you want to use a tool. As you can see, you can either “Allow Once” or “Allow for This Chat.” I allowed each new tool for this chat as it appeared in my dialogue. From now on, I will skip these screenshots.

Claude displayed the list of buckets (I truncated the screenshot for brevity).

Let’s see what’s inside one of the buckets:

Claude displayed a list of objects grouped by categories: white papers, blog Markdown files, and images. At the end of the list, it gave a nice summary of the bucket contents.

This is the first advantage of using LLMs. The command-line tool or web UI would give us a list of objects, as requested. The LLM summarizes the bucket’s content and provides an insightful narrative of its composition. Imagine if I had thousands of objects here. A typical command-line query would give us a long list of objects that could be hard to consume. Here, it gives us a human-readable overview of the bucket’s contents. It is similar to summarizing an article with your favorite LLM client.

You can be more specific and ask to list a subset of objects. For example, I’d like to see what benchmark reports we have in the bucket.

Claude gave me the list I expected.

Of course, it listed the PDF files with “benchmark” in their names! But wait… it also listed the papers called “Performance comparison …” and “… support perf.pdf.” Interesting! That means it doesn’t simply search for the word but understands my request’s meaning. This is another advantage of using LLMs.

Object analysis operations

Now, I want to get details about one of the benchmark reports. I don’t have to copy and paste the full file name. Just a little detail will be enough.

Claude understood me perfectly. It tried to read the file contents, but because that function was not implemented for PDF files, it resorted to using the ask-object function. With this new AIStor function, you can ask questions about an object directly, and AIStor will use the AI model embedded in the cluster to answer the question. This is what it did here, giving us a good summary of this paper.

Note that in this case, Claude was smart enough to invoke AIStor’s internal model via the prompt_object API to accomplish its goal. The document didn’t even leave the cluster. Many organizations are reluctant to use AI mainly because of security concerns. In the case of AIStor, all objects stay within your security perimeter.

I have a bucket on this server with 200 receipt images uploaded from a public dataset. We’ll start with analyzing the bucket. Then, we’ll analyze individual receipts and add tags to the objects.

Claude gave me a comprehensive overview of the bucket.

Did you notice that Claude thought about the most logical next step and suggested it? Sure, I want to get the details about one of the receipts!

And I got the complete analysis of the receipt. Again, the MCP server knew about the ask-object function and used it to analyze the object. The object itself didn’t leave the AIStor cluster.

To make future analysis faster and more effective, it would be great to add tags to each object, such as vendor, transaction date, amount, and currency. Let’s try it.

And the server worked perfectly!

Why don’t we tag the other receipts? To save time, let’s tag the first five.

The server analyzed the images, assigned tags, and checked them with get-object-tags. For the last object, the vendor’s name contained an apostrophe, which is not allowed in tags. The server diagnosed the problem and fixed it by removing the apostrophe.

Imagine doing the same operation without MCP servers. You would have to write a Python script to pull images from the bucket, send them to an AI model for analysis, get the information back, decode it, find the correct fields, apply tags to objects… You could easily spend half a day creating and debugging such a script. We just did it simply using human language in a matter of seconds.

Conclusion

LLMs and MCP servers simplify normal user operations, summarize the bucket contents, analyze objects, and add tags and other metadata easily.

In the next blog in this series, we will explore how the MinIO AIStor MCP server can supplement core admin tasks such as getting the cluster health status, available storage, listing and adding versioning, replication rules, and other bucket parameters. Using the MCP server and LLMs can give you data distribution by bucket and even create a pie chart. Stay tuned.

Next steps

This MCP server for AIStor is currently under active development. If you want to try it, find all the instructions in our GitHub repository https://github.com/minio/mcp-server-aistor.

The MCP server can work with MinIO AIStor and MinIO Object Store (community edition). The community edition doesn’t support some AIStor-specific functions, such as ask-object.

I started testing it with cURL and realized that I had to use the --url-query flag to pass any text with spaces, like this:

curl -X POST --url-query 'text="Hello world"' http://192.168.1.130/lcd

It worked fine with the curl command, and the text was displayed on the LCD.

I started testing it with the LLM asking “Please display ‘Hello world’ on the LCD” and, of course, got errors.

In this project, I am sending the following prompt to the LLM:

You are an IoT API assistant. Convert user commands to curl commands for the IoT server.

Respond only with the curl command, no explanations.

Usually, the LLM responds with a command like:

curl -X POST http://192.168.1.130/leds/1/on

and my dialogue program parses it and converts to a call to one of the requests functions. The parsing function figures out if it’s GET or POST and pulls the URL from the curl command.

But with LCD it was different. The LLM responded with this:

curl -X POST http://192.168.1.130/lcd -H "Content-Type: application/json" -d '{"text":"Hello world"}'

and, of course, my parsing function wasn’t ready to work with this string.

After trying for half-an-hour to parse it properly, I had a brilliant idea. “Let’s ask the LLM to make this work for us!”

I changed the prompt to:

You are an IoT API assistant. Convert user commands to function calls of the Python requests library to send requests to the IoT server.

Respond only with the function call, no explanations.

And the whole function parsing the curl command and converting it to a requests call was reduced from 20 lines of code to a simple eval:

response = eval(function_call)
return response.json()

Isn’t it cool?

Well, I have to admit that the LLM made a mistake once. After asking to turn the motor on, I asked to turn it off. The LLM responded with requests.get() instead of requests.post(). The fix? I added this to the prompt:

Please make sure to use the correct method and endpoint.
Requests for actions like turning on/off devices should be POST requests.

and it didn’t make mistakes since then.

It all started several years ago when I thought “Can I use Alexa to manage physical devices?” I created a simple demo project to show it to my amateur radio friends. You would say, “Alexa, turn my antenna 90 degrees,” and my model antenna would magically turn. It was a fun weekend project that used a Raspberry Pi, a stepper motor, and a miniature model antenna. I published it on YouTube, if you’re curious.

Smart dollhouse

The Alexa experiment was great but had some issues. With Alexa, you should be very precise with your phrases. In my application, Alexa expected you to say, “Alexa, turn my antenna XX degrees,” and only this exact phrase would work. With the growing availability of large language models (LLM) I started thinking about using them to manage motors, devices, and sensors.

“What if I get a dollhouse,” I thought, “and add a bunch of sensors and a microcontroller and write a REST API server for them?” Then, I’ll ask an LLM to convert human language to REST API requests and send them to the server. Also, I wanted something that looks realistic and not just a bunch of sensors scattered on my desk.

Luckily, I found exactly what I needed on Amazon: a wooden house with many of sensors attached to it and a microcontroller. I have to praise the great quality of the kit I bought from Keyestudio: it was very easy to build and attach the sensors, and the software worked on the first run! If you tried similar kits before, you should know it’s not very common.

The kit included a simple Arduino controller with a sample program that implemented some business logic: for example, when there was a signal on the rain sensor on the roof, the servo motor would close the window.

It worked fine, but I needed a server to respond to remote requests.

IoT server

I decided to switch to Raspberry Pi Pico W and MicroPython. The “W” version of Pico gave me the connectivity I needed, and I was going to use MicroPython to implement a simple REST API server.

Using AI helpers

As it’s becoming more common these days, I asked Claude.ai to help me with this project.

I want to write a program in MicroPython for Raspberry Pi Pico. It should run a web server connected to WiFi. The web server should accept REST requests and perform actions on the Pico, such as: getting information from sensors, turning LEDs on and off, turning motors (servos and steppers) on and off. Please help me create an API for this application.

Claude answered with a list of curl commands that can be used against our planned API. I liked this approach: you design the expected user experience first (in our case, it was REST API) and then start implementing it.

It created a very simple web server without using any frameworks at all, just with sockets. I asked if we can use a framework like Flask, and Claude told me that with MicroPython it’s more common to use Microdot because it is lighter on resources. I learned that Microdot is being developed by Miguel Grinberg, the author of one of the most popular books about Flask. That was a good recommendation and I asked Claude to re-write the web server with Microdot.

After that was done, I tested the server on my Pico and it worked just fine! But I had a further idea, and I asked:

Please help me write the GET function for Microdot that will return a list of sensors when called as /sensors and the sensor’s value when called with /sensors/id. I think this should help with discoverability.

And here was another discovery! Claude told me about the concept with a strange name “HATEOAS,” which stands for Hypermedia as the Engine of Application State. It explained the idea behind it, gave examples, and finally, wrote the server code that would respond to routes like /sensors or /leds with the information about sensors and LEDs locations (roof, garden, door), parameters (LED’s color, sensor’s calibration), and, most importantly, the links I should use to work with them.

That was very close to what I needed.

Using LLM to generate REST API calls

Now, thanks to Claude’s help, I had a server that would respond to requests like curl http://server/leds with the following JSON:

{
  "_links": {
    "filter_by_color": {
      "href": "/leds/filter?color={color}",
      "templated": true
    },
    "self": {
      "href": "/leds"
    },
    "filter_by_location": {
      "href": "/leds/filter?location={location}",
      "templated": true
    }
  },
  "data": {
    "1": {
      "color": "yellow",
      "location": "roof",
      "state": 0,
      "_links": {
        "on": {
          "href": "/leds/1/on"
        },
        "self": {
          "href": "/leds/1"
        },
        "off": {
          "href": "/leds/1/off"
        },
        "toggle": {
          "href": "/leds/1/toggle"
        }
      }
    },
    "2": {
      "color": "white",
      "location": "garden",
      "state": 0,
      "_links": {
        "on": {
          "href": "/leds/2/on"
        },
        "self": {
          "href": "/leds/2"
        },
        "off": {
          "href": "/leds/2/off"
        },
        "toggle": {
          "href": "/leds/2/toggle"
        }
      }
    }
  }
}

What if I get similar JSONs from the other routes, such as /sensors and /motors, send them to an LLM, and ask it to convert human requests to curl commands? Then, I can send those commands to the server via the requests Python library and work with the devices!

The next step was to write a simple Python script that would get the initial links from the root (/) route of the server and explore all links to get the same JSONs from them.

After the script collected the API description of the server this way, I created a system prompt that included the whole JSON with all the links from the server and added the request:

You are an IoT API assistant.
Convert user commands to curl commands for the IoT server.
API structure: {json.dumps(self.api_structure, indent=2)}
Server URL: {self.server_url}

Respond only with the curl command, no explanations.

Then I created a simple dialog that would get the command from the user in human language, attach it to the prompt, and send it to the LLM.

For this application, I used Haiku-3.5 from Anthropic because it is faster and cheaper than more complex models.

Translate JSON responses to human language

Now the system has started working. I would send a message like, “Turn the yellow LED on,” and it turned on. Or, “Turn the garden LED on,” and the white LED in the garden would turn on. I could ask in normal language, “What’s the light conditions on the roof?” and it responded with a JSON that included a lot of information:

{
  "_links": {
    "config": {
      "href": "/sensors/2/config"
    },
    "self": {
      "href": "/sensors/2/value"
    },
    "all_sensors": {
      "href": "/sensors"
    },
    "sensor": {
      "href": "/sensors/2"
    }
  },
  "data": {
    "unit": "lux",
    "type": "light",
    "calibrated_value": 4114.6,
    "location": "roof",
    "id": "2",
    "raw_value": 41146
  }
}

That was good, but I wanted more reasonable human language instead of JSON! LLM was to the rescue again! Here is another prompt for Haiku:

Convert this IoT API JSON response to concise human language, focusing on the most important information.
Don't print 'Here is the concise summary' or other explanations; print just the content:

And now the answers from my server looked like:

Light sensor #2 located on the roof is measuring 4,109.8 lux, indicating bright illumination conditions.

First public demo

Recently, I went to the local Python meetup in Atlanta. I was going to give a presentation about this project and demonstrate it. Needless to say, I was nervous.

I started a hotspot on my cell phone, connected my laptop to it, and started the Pico. It indicated that it had connected to the hotspot and got an IP address. Now I had to change my dialogue program to point to that address.

The dialogue began:

IoT Controller started. Type 'quit' to exit.

>>> turn the yellow led on

LED 1 is currently on, colored yellow, and located on the roof.

>>> turn the motor on

Motor 1 (DC type) is currently ON and located on the roof.

>>> turn the motor off

Motor #1, a DC motor located on the roof, is currently turned off.

So far, so good. The public loved it when the propeller started spinning and gave me a round of applause.

I switched my keyboard to Cyrillic and typed this:

>>> выключи желтый led

“Wow, is it Russian?” I heard the murmur in the audience.

And magic happened. The LED went off, and I got this message:

LED 1 located on the roof is yellow and currently off (state 0).

I asked the meetup organizer, “Pablo, can you tell it in Spanish to turn the LED on?”

Pablo took the keyboard and typed:

>>> Por favor prender el LED amarillo

LED 1 is currently on (state 1), colored yellow, and located on the roof.

>>> Apaga la maldita led amarilla

LED 1 is currently off, located on the roof, and colored yellow.

>>>

“Wow!” said the audience.

I explained, “This magic is done purely by the LLM. I didn’t do anything in the code. It understands many languages and translates between them and REST and JSON easily. Note that when I spoke to it in Russian, I used the English word ‘LED’, and it understood me perfectly.”

Lessons Learned

This project turned out to be an unexpected learning journey. I started with a simple idea of controlling a dollhouse but ended up learning:

• MicroPython and its differences from regular Python
• Microdot - a lightweight web framework perfect for microcontrollers
• HATEOAS - a REST API design principle with a name that sounds like a sneeze
• The incredible versatility of LLMs in handling natural language processing

Most importantly, I learned that AI assistants like Claude can be excellent coding partners. They not only help with code but also introduce you to best practices and concepts you might not have discovered otherwise.

Future plans

Of course, I started looking for ways to expand the project. And, of course, I found this: a huge 42-in-1 kit from Keyestudio with a lot of sensors and actuators.

Wouldn’t it be cool to say something and have it displayed on the LCD screen? Gas sensors, accelerometers, buzzers, and motors are waiting for me to connect them.

Getting more serious

Of course, it’s just a toy project created for learning. If you want to use IoT in your real home, of course, you should take a look at Home Assistant. That’s what I did, thinking, “Can I apply the same approach to creating Home Assistant’s API requests?” Needless to say, the project has already implemented the API for LLMs “Great minds think alike,” I said to myself proudly. 😉

Project code

If you’re interested in building your own multilingual smart dollhouse (or just want to see how it all works), check out the project on GitHub: Geekhouse Repository. Feel free to contribute, ask questions, or share your own IoT adventures.

Try to use any language you know and see if the LLM can translate it into REST API calls! Try other LLMs, try a local LLM running in your homelab. Most likely, using a local LLM will make turning LEDs on and off faster.

Instantly, I thought of building colorful time displays with knobs to control them.

This project combines two of my favorite things — tech tinkering and fun. I used two Raspberry Pi Picos, some 7-segment LED displays, rotary encoders, and (of course) Go! And before you ask — yes, it does something cool, and no, I haven’t explored all its possibilities just yet.

This isn’t my first attempt at making this thing. I originally started with an Arduino, writing the project in C++. I even got as far as setting time with rotary encoders before life happened (probably work). It stayed unfinished for years.

Control Panel v1.0 (Arduino)

Version 2.0, though? That’s where things got interesting. I picked up TinyGo — a Go compiler for microcontrollers — and decided it was the perfect excuse to learn both TinyGo and Go while having fun. TinyGo works like a charm on Raspberry Pi Pico, so that became my hardware of choice.

Control Panel v2.0 (TinyGo and Raspberry Pi Pico)

The Hardware

Here’s the gear I used:

• Two Raspberry Pi Picos
• 4-digit 7-segment LED displays with the TM1637 chip
• Rotary encoders for setting the time (way more satisfying than buttons)
• DFPlayer Mini to play sound effects. Because what’s a time-travel toy without some audio drama?

The plan was simple: one Pico would set the “preset time,” and the other would handle the “current time” and “memory time.” When you press a button imitating the actual time travel, the “preset time” becomes your “current time,” and the fun begins. Sounds cool, right?

I decided I’ll make a version which adheres to international standards, specifically ISO-8601 where the dates are presented in the form: 2024-12-30 15:04:05. (Well, the real reason was that I couldn’t find alphanumeric LEDs that could display months 😉.)

Why TinyGo?

Let’s be honest: when working with microcontrollers, the usual suspects are Arduino, MicroPython, or maybe CircuitPython. But with TinyGo, I got to work in Go — one of my favorite languages. It just made everything more enjoyable (and less tedious).

Here’s why TinyGo rocks:

• Goroutines: No more messing around with loops and managing every state yourself. With goroutines, the heavy lifting is done.
• Channels: These made it super easy to pass messages around without worrying about blocking the main thread. (Looking at you, Arduino.)

How it all works

This setup has two brains (aka Raspberry Pi Picos) that talk to each other via UART. Here’s a rough idea of what’s going on:

1. Left Pico: You set the “preset time” using rotary encoders and 7-segment displays. You click the encoder and now you are in the “setting” mode. You turn the encoder to find the desired value. Then you click again and the value is set. For the date and hour:min displays you have to do it twice. For example, to set the date:

   • click
   • turn, find the month
   • click (the month is set)
   • turn, find the day
   • click (the day and the whole date is set)

Of course, when you turn the month encoder is goes over 12 and starts with 1 again. Of course, the system knows how many days in each month and does the right thing.

2. Right Pico: It handles the “current time” and “memory time” and then updates the times when you hit the button to start the journey.

When you press the “time travel” button, the preset time is sent from the left Pico to the right Pico as an RFC3339 string (fancy, huh?). Then, the present time becomes the new “memory time” — you know, just in case you want to go back to the exact moment you left.

Hardware connections

Software Shenanigans

I kept the code simple but flexible. I used goroutines to handle multiple tasks at once — like updating the display while you’re setting the time — and channels to manage button presses and other events without creating a tangled mess of code.

Here’s the basic rundown:

• You turn the rotary encoder to set the year, month, and day for the preset time.
• The left Pico sends that data over UART to the right Pico.
• When you press the time-travel button, the current time is saved in the “previous” time, and the time set as the target becomes your current time.
• The present time starts ticking as your typical wall clock.

Extra fun stuff: sound and memory

Because time travel needs sound effects (obviously), I hooked up a DFPlayer Mini. It plays MP3s from an SD card, and the Picos send the player commands over UART.

Oh, and the toy remembers your settings. Every second, the times are saved to flash memory. When you power it back on, the Picos pick up right where they left off. Handy, right?

DFPlayer Mini

Lessons I didn’t expect to learn

This project was a great learning experience but it wasn’t all smooth sailing. Here are some of the surprises I encountered:

1. Goroutines: In TinyGo, goroutines will keep going until they hit a blocking operation (like I/O). I had to add tiny sleep calls here and there to make everything work smoothly.

2. Error handling matters: Error handling is always important, but it’s really important here. Things will go haywire if an extra character sneaks into your UART transmission. You must detect it and avoid just hanging up the whole time machine.

3. Rotary encoders are not so simple: I learned about Gray code (have you heard about it?) to implement the rotary encoders, which saved me from a world of trouble. In short, it’s an alternative binary code where two consecutive numbers differ only by one bit. It turns out to be very useful in error-prone environments like electronic circuits. Read more: https://en.wikipedia.org/wiki/Gray_code.

4. Debouncing switches: That’s a whole other world of engineering. When you pressed a button, did it send just one pulse or more? If you’re going down that rabbit hole, here are some excellent reads on switch debouncing: https://www.eejournal.com/article/ultimate-guide-to-switch-debounce-part-1/ and http://www.ganssle.com/debouncing.htm.

What’s next?

There are so many ways I can build on this project. For starters, I could turn this into a Pomodoro timer, an alarm clock, or a chess clock — time-related toys for all occasions.

Or, who knows? Maybe I’ll create a DIY kit so you can build your own time-travel toy at home.

Want to try TinyGo?

If you’re curious about TinyGo and want to dip your toes in, here’s how to start:

1. Get a Raspberry Pi Pico Starter Kit — it usually includes sensors, motors, LEDs, and more.
2. Clone the TinyGo repo: https://github.com/tinygo-org/tinygo
3. Follow the steps here: https://tinygo.org/getting-started/

Trust me, it’s a fun way to learn Go, and you’ll get something you can actually hold and show off to your friends.

Please let me know if you need more details about this project. Or if you have ideas about improving it — I’ll be happy to continue working on it!

“Why do you do that?” I asked.

“What’s wrong with that?” he said. “I know, I know, it’s not a good security practice, but I’m used to it. It’s just a lab server; what can go wrong? And also, all other ways are not that easy.”

“‘What can go wrong?’” I said, “The famous last words!” “I’m not going to tell you horror stories. I just think that what you consider ’the most convenient way’ is not that convenient. There are other ways.”

“Yeah, I know, I know,” he sighed. “Create a normal user, give them sudo access, and all that.”

“Yes, that’s the right way. You are correct. Even better, that user shouldn’t use a password too. Using SSH keys is much better. But if you insist on going directly as root, you can do it with SSH keys too. The good thing about this approach is that you can always check who’s logged in as root with which key.”

“Really? Can you show me?” he asked.

Challenge accepted.

Create users

I used one of my Red Hat servers as a target host. I decided to start a simple Fedora Linux VM for the client host and create three normal users on it.

[pavel@fedora ~]$ sudo useradd -m alice
[pavel@fedora ~]$ sudo useradd -m bob
[pavel@fedora ~]$ sudo useradd -m charlie

Create SSH keys

On behalf of each user, I created their SSH keys. I decided to use the Ed25519 algorithm as it’s shorter and more secure than the default RSA. (To learn more about this, just google ’ed25519 vs. rsa’.)

[pavel@fedora ~] $ sudo su - alice
[alice@fedora ~] $ ssh-keygen -t ed25519
Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/alice/.ssh/id_ed25519):
Created directory '/home/alice/.ssh'.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/alice/.ssh/id_ed25519
Your public key has been saved in /home/alice/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:5xuxPx8QnPv19/6IZ5frmQj1N0hRCP9J364ddE6avL8 alice@fedora
The key's randomart image is:
+--[ED25519 256]--+
|           .. .. |
|           ..o.  |
|            +o . |
|             o+ +|
|        S o oo +*|
|         o oo++Bo|
|          +. .*+B|
|           +o.+BX|
|          . o**EX|
+----[SHA256]-----+
[alice@fedora ~]$ cat .ssh/id_ed25519.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG8Obx1FsUu1jlYDtzfEDHYSDjG82xE7ysxZVzhgpGC5 alice@fedora
[alice@fedora ~] $ exit

[pavel@fedora ~] $ sudo su - bob
[bob@fedora ~] $ ssh-keygen -t ed25519
. . . . Same dialogue . . . .
[bob@fedora ~] $ exit


[pavel@fedora ~] $ sudo su - charlie
[charlie@fedora ~] $ ssh-keygen -t ed25519
. . . . Same dialogue . . . .
[charlie@fedora ~] $ exit

Create fingerprints

I wore my sysadmin hat and told my users: “I trust you. I want to give you root access to my server. But I need your public keys.”

“Great!” Alice, Bob, and Charlie answered. “How can we do it?”

“Login to your accounts. Your public key is this file: ~/.ssh/id_ed25519.pub. It’s just a one-line text file. You can include it in the mail body or attach it as a file. Remember: don’t share your private key–the one without .pub–with anybody! Keep it private!”

My users started working, and in several minutes, I received an email from each of them containing the following information:

From: alice
To: sysadmin
Subject: my public key

Hi Sysadmin,

Here is my public key (I copied it from id_ed25519.pub, as you told us):

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG8Obx1FsUu1jlYDtzfEDHYSDjG82xE7ysxZVzhgpGC5 alice@fedora

I hope this works.

Thanks,
Alice

Add the public keys to the host

The easiest way to give access to somebody to any account, including root, is to add that user’s public key to the file .ssh/authorized_keys in that account’s home directory. This is exactly what I did for the root user on my lab server. I opened (with Vim, of course) the file /root/.ssh/authorized_keys and entered these three entries (the public keys from my users):

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG8Obx1FsUu1jlYDtzfEDHYSDjG82xE7ysxZVzhgpGC5 alice@fedora
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJgclT4eQ5RlYabZfkdjFV5wGrroXxmd5n2X7okmiaN8 bob@fedora
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJWcjljox2NKwDFllZ5KQc4LSVrBEKoaOE/t/up1XbyD charlie@fedora

Now the system is ready for a test.

Test access

I went to my users and told them: “The system is ready. Feel free to test your access! The first time you login, the system will ask you if you trust the host you are logging in. Answer yes. The host will be added to the list of known hosts–check it later in ~/.ssh/known_hosts– and next time, you won’t be asked for confirmation.”

Alice, Bob, and Charlie opened their terminals on the Fedora machine and tried:

[bob@fedora ~] $ ssh -l root 192.168.1.234
The authenticity of host '192.168.1.234 (192.168.1.234)' can't be established.
ED25519 key fingerprint is SHA256:mhS0bPdGrEIwwMKJdKxpkxLdtYKNp0+FSgwqybeugd8.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? *(Bob typed 'yes')*
Warning: Permanently added '192.168.1.234' (ED25519) to the list of known hosts.

Last login: Wed Apr 26 09:06:21 2023 from 192.168.1.24
[root@rhel-lab ~]#

“Wow! That was easy!” Bob said. “Look, no password!”

“I told you!” I said. “But keep in mind: each of you comes to the server with your own key. That means the server’s admin will always know who logged in as root: Alice, Bob, or Charlie. So please be considerate when working as root on this host.”

I said this to my users but wasn’t ready yet to watch their logins. It was time to prepare.

Check the logs

“They just logged in and out recently,” I thought. “It should be at the end of the log.”

In Red Hat Enterprise Linux, the log file where all security-related events are stored is called /var/log/secure. Let’s check its last 30 lines.

# tail -30  /var/log/secure
Apr 27 10:21:19 deep-rh sshd[1337250]: Accepted publickey for root from 192.168.1.24 port 49090 ssh2: ED25519 SHA256:5xuxPx8QnPv19/6IZ5frmQj1N0hRCP9J364ddE6avL8
Apr 27 10:21:19 deep-rh systemd[1337257]: pam_unix(systemd-user:session): session opened for user root by (uid=0)
Apr 27 10:21:19 deep-rh sshd[1337250]: pam_unix(sshd:session): session opened for user root by (uid=0)
Apr 27 10:21:22 deep-rh sshd[1337282]: Received disconnect from 192.168.1.24 port 49090:11: disconnected by user
Apr 27 10:21:22 deep-rh sshd[1337282]: Disconnected from user root 192.168.1.24 port 49090
Apr 27 10:21:22 deep-rh sshd[1337250]: pam_unix(sshd:session): session closed for user root
Apr 27 10:21:32 deep-rh systemd[1337261]: pam_unix(systemd-user:session): session closed for user root
Apr 27 10:21:34 deep-rh sshd[1337458]: Accepted publickey for root from 192.168.1.24 port 41254 ssh2: ED25519 SHA256:is6l6bRqCCBVKunT+zVGHoUF0A06p8lt/04EoRbyCUY
Apr 27 10:21:34 deep-rh systemd[1337467]: pam_unix(systemd-user:session): session opened for user root by (uid=0)
Apr 27 10:21:34 deep-rh sshd[1337458]: pam_unix(sshd:session): session opened for user root by (uid=0)
Apr 27 10:21:37 deep-rh sshd[1337493]: Received disconnect from 192.168.1.24 port 41254:11: disconnected by user
Apr 27 10:21:37 deep-rh sshd[1337493]: Disconnected from user root 192.168.1.24 port 41254
Apr 27 10:21:37 deep-rh sshd[1337458]: pam_unix(sshd:session): session closed for user root
Apr 27 10:21:47 deep-rh systemd[1337472]: pam_unix(systemd-user:session): session closed for user root
Apr 27 10:21:55 deep-rh sshd[1337680]: Accepted publickey for root from 192.168.1.24 port 42552 ssh2: ED25519 SHA256:QgAov0UZI25hWxnbLiHa00j64/zD1m80UMsSIZtxr2s
Apr 27 10:21:55 deep-rh systemd[1337706]: pam_unix(systemd-user:session): session opened for user root by (uid=0)
Apr 27 10:21:55 deep-rh sshd[1337680]: pam_unix(sshd:session): session opened for user root by (uid=0)
Apr 27 10:21:58 deep-rh sshd[1337730]: Received disconnect from 192.168.1.24 port 42552:11: disconnected by user
Apr 27 10:21:58 deep-rh sshd[1337730]: Disconnected from user root 192.168.1.24 port 42552
Apr 27 10:21:58 deep-rh sshd[1337680]: pam_unix(sshd:session): session closed for user root
Apr 27 10:22:08 deep-rh systemd[1337710]: pam_unix(systemd-user:session): session closed for user root

“Good,” I thought. “I can see their logins and logouts. I can see the IPs from which they logged in. But how can I figure out who logged in and when?”

After a bit of googling, I found out that the string that goes after ED25519 SHA256: is a fingerprint of the user’s public key. “I just have to connect the fingerprints with the public keys,” I thought.

Create a fingerprint database

Fingerprints are only useful if you have collected a good database of them. This is what I did after receiving the emails from my users.

On the lab host (rhel-lab) I saved the users’ public keys in a separate directory under /root. Of course, I made it readable only by root.

# mkdir ~/ssh-keys
# chmod 0700 ~/ssh-keys
# cd ~/ssh-keys

I copied the users’ public keys that they sent me here and added the owner’s name to each file.

# echo "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG8Obx1FsUu1jlYDtzfEDHYSDjG82xE7ysxZVzhgpGC5 alice@fedora" > alice_id_ed25519.pub
# echo "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJgclT4eQ5RlYabZfkdjFV5wGrroXxmd5n2X7okmiaN8 bob@fedora" > bob_id_ed25519.pub
# echo "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJWcjljox2NKwDFllZ5KQc4LSVrBEKoaOE/t/up1XbyD charlie@fedora" > charlie_id_ed25519.pub
# ls -l *pub
-rw-r--r--. 1 root root 94 Apr 27 09:53 alice_id_ed25519.pub
-rw-r--r--. 1 root root 92 Apr 27 09:54 bob_id_ed25519.pub
-rw-r--r--. 1 root root 96 Apr 27 09:54 charlie_id_ed25519.pub

Then I ran the following command against each public key file to create its fingerprint.

# ssh-keygen -lf alice_id_ed25519.pub
256 SHA256:5xuxPx8QnPv19/6IZ5frmQj1N0hRCP9J364ddE6avL8 alice@fedora (ED25519)
# ssh-keygen -lf bob_id_ed25519.pub
256 SHA256:is6l6bRqCCBVKunT+zVGHoUF0A06p8lt/04EoRbyCUY bob@fedora (ED25519)
# ssh-keygen -lf charlie_id_ed25519.pub
256 SHA256:QgAov0UZI25hWxnbLiHa00j64/zD1m80UMsSIZtxr2s charlie@fedora (ED25519)

In the same directory, I opened a file called users.csv and added three records in the form of username,fingerprint, like this:

users.csv

alice,5xuxPx8QnPv19/6IZ5frmQj1N0hRCP9J364ddE6avL8
bob,is6l6bRqCCBVKunT+zVGHoUF0A06p8lt/04EoRbyCUY
charlie,QgAov0UZI25hWxnbLiHa00j64/zD1m80UMsSIZtxr2s

Now I needed a program to scan the /var/log/secure file, find login and logout messages, parse them to find the fingerprint, and look up the user based on their fingerprint in the database.

Create a log-monitoring application

I started learning Go recently, so for each new idea I try to use Go to practice. So this problem looked like a good exercise.

The program’s logic is pretty simple:

• Scan the log file and create a list of login/logout events.
• For each login event, find the user based on their fingerprint.
• Create a list of sessions and add login events to it.
• For each logout event, find the corresponding login event based on the source IP and the port and update the end time of the session.
• Output all sessions with user names, source IPs, start/end times, and duration.

The most challenging part was to parse the log file and collect all necessary fields. That’s why the regular expressions might look scary.

I created a simple Go program consisting of a single main.go file and tested it on a short fragment of /var/log/secure file. It printed out this:

# go run main.go
alice   192.168.1.24    2023-04-27 10:21:19     2023-04-27 10:21:22     3s
bob     192.168.1.24    2023-04-27 10:21:34     2023-04-27 10:21:37     3s
charlie 192.168.1.24    2023-04-27 10:21:55     2023-04-27 10:21:58     3s

Use AI to improve the application

The first version of this app was a simple main.go file with hard-coded file names. I was playing around and needed a simple demo. My first improvement was adding the command-line arguments. I added the pflag package (https://pkg.go.dev/github.com/spf13/pflag) and turned on Codeium (https://codeium.com/) in my VS Code. And here, AI began to help me.

AI coding assistants are very impressive, no doubt. But it’s one thing when you see it helping somebody in the video or you’re trying it yourself with some example programs. And it’s another thing when you write something yourself, you work on your own project, and it starts really helping you. Then you can clearly see how much time you saved by not typing a lot of things (just press [Tab] to accept!), by not looking around your own code (what should be included in this struct, I forgot?), and by not googling function library definitions and arguments. AI remembers all this for you.

Back to my code. I just started typing userDB := flag. and Codeium already knew that it should be StringP and the argument should be named users (short form is u) and the reasonable default should be users.csv. I didn’t argue and accepted. The next argument was the same: I added the log argument almost without typing anything.

So far, so good. Let’s try another tool. I opened ChatGPT and asked:

Me: Act as a Go programming mentor. I will give you a program I wrote. Please suggest possible tests to add to this program. Here is my program:

…and I pasted my simple main.go in the chat window.

In the answer it suggested several cases that I have to test with each function: valid input, empty input, invalid input, duplicate fingerprints, etc. At the end, ChatGPT gave me an example of how it can be done and added:

AI: You can follow a similar pattern to write tests for the other functions as well.

Wow, it acted like a real mentor! It didn’t write the code for me, but it helped me to move in the right direction.

I wanted to write my tests the right way and played a role of a good student:

Me: I read an article that suggested keeping the main.go file small and let the main function only call the application function. They suggested having other functions in separate files and argued that it helps in testing. Can you help me to apply these suggestions to my code?

“Sure!” the AI answered and suggested a good plan of moving all my functions to a separate pkg/sshloginmonitor directory and creating files user.go, session.go, and util.go.

I followed the suggestion, and our discussion continued.

Me: My program should log a fatal error under certain conditions. How should I test that?

In the answer it explained that it’s possible but I should keep in mind that the call to log.Fatal() will terminate my test.

Me: Right! I shouldn’t call log.Fatal() from the function. I should return an error instead. How should I check the if the error is returned?

The AI gave me the full explanation with an example of how it should be done.

Me: How should I specify the expected error in the lists of tests?

Another great example with a slice of test cases showing how to specify the expected error.

Me: How should I test reading from a file? Can it be done by reading from a string constant?

Another great suggestion from AI: you probably should pass io.Reader to your function, not a file name. That way, it will be much easier to test. Accepted; I re-wrote my functions to use io.Reader instead of file names.

And so on, and so forth. Step by step, with the help of ChatGPT and Codeium, my little program got the tests it needed, docstrings for functions, and test cases for different conditions. In other words, in just a couple of hours, it looked much more professional.

I don’t know if AI can fully replace programmers. But I’m sure it can help us write better code. Just don’t be afraid and ask questions.

Find the code in this repo: https://github.com/pavelanni/ssh-login-monitor

“Wait,” I thought. “What if I give the AI the full description of my problem? Will it be able to write it from scratch?”

To be honest, I was a bit skeptical. Well, ChatGPT has impressed me already helping with my code here and there. But to solve this problem from scratch, just from the problem description? Probably not. But let’s give it a try.

ChatGPT solves the problem

I opened the ChatGPT window and typed the problem description.

I added the log (here is just a fragment).

And finally I added the authorized_keys file.

Let’s see what it can do with such a problem!

I didn’t wait for too long. Almost immediately, ChatGPT started printing. (The GPT-4 version prints a bit slower that GPT-3.5 and that creates an effect of “thinking”. Also, it reminds me those old teletype machines used with really old computers.)

Wait, what?? It’s just a language model! How could it calculate the fingerprints??

But I didn’t have time to answer my own question because ChatGPT continued printing.

Well, it found the login events based on the string I gave it (him? her?) and connected the fingerprints to those it just calculated. Impressive. It even found the timestamps and correctly presented them as timestamps. Good job, but that’s easy.

Let’s continue and ask about logout events.

Again, almost without a pause:

Good logic, great explanation! Find the ports and connect them to the login events. That means it remembers the login events from the previous task somehow! Mind blowing… But let’s continue.

If it remembers login and logout events, it should be able to calculate session durations. Or not? Again, it’s just a language model, it should not know how to do arithmetics. Let’s ask and see…

Wow! It even explained how it did the calculations! “Show your work,” as we were told in school.

I found myself sitting with a dropped jaw a few seconds later. (No, it’s not just a figure of speech. Literally.)

For a few minutes I couldn’t collect my thoughts. Yes, it’s a language model. Yes, it can find certain phrases and connect them together because it has seen those phrases and words many times during training. I understand that.

But how can it find numbers (like port numbers) and connect them together? And how can it calculate? Not only something simple like “37 - 34”, but an SSH public key fingerprint?? I can’t imagine that the model was trained on all possible public keys and their fingerprints, can you?

After several minutes of shock I got another great idea. I had to close the loop.

It wrote a piece of Go code, gave me instructions on how to run it, and how to pass the input files to it.

Needless to say that I copied the code into my editor and ran it!

$ go run main.go ../test/secure.log ../test/authorized_keys
Login: alice - 0000-04-27 10:21:19 - 192.168.1.24:49090
Logout: alice - 0000-04-27 10:21:22 - 192.168.1.24:49090
Login: bob - 0000-04-27 10:21:34 - 192.168.1.24:41254
Logout: bob - 0000-04-27 10:21:37 - 192.168.1.24:41254
Login: charlie - 0000-04-27 10:21:55 - 192.168.1.24:42552
Logout: charlie - 0000-04-27 10:21:58 - 192.168.1.24:42552

One minor thing – it didn’t get the current year. But it wasn’t in the log, so this is fine. Now I’m pretty sure I could tell it to use the current year if it’s missing and it would do it perfectly. No doubt.

The code written by ChatGPT is here: https://github.com/pavelanni/ssh-login-monitor/tree/main/chatgpt-version