AWS Builder Center

Builder Center

ShipShape: Building an AI DevOps Troubleshooter on AWS

Learn how I built ShipShape, an AI DevOps troubleshooter, using AWS Amplify, Lambda, API Gateway, and AWS SAM.

Ubayed Bin Sufian

Introduction

DevOps errors can be frustrating, especially when a log contains unfamiliar messages and it is unclear where to start. I built ShipShape, a friendly, read-only AI troubleshooting agent that helps developers understand errors involving Linux, Docker, Git, and GitHub Actions.
Instead of returning a wall of technical text, ShipShape explains an error in plain English, identifies a likely cause, and suggests diagnostic steps and verification commands.
 
Try ShipShape: https://main.d15f6pzg85kulh.amplifyapp.com/
Source code: https://github.com/Ubayed-Bin-Sufian/ShipShape

What I Built and Who It Helps

ShipShape is designed for developers, students, and people learning DevOps who need a useful starting point when something breaks.
Users can paste an error message or select an example. The agent returns a structured response containing:
  • Explanation: What the error means in understandable language.
  • Likely cause: A probable explanation for the problem.
  • Diagnostic steps: Checks to help narrow down the issue.
  • Verification commands: Commands users can run to investigate or confirm a fix.
I wanted the experience to feel calm and practical. Rather than pretending to know the exact cause of every error, ShipShape gives users a clearer starting point for their investigation.
Safety is an important part of the design. ShipShape suggests commands but does not execute them, modify infrastructure, or automatically change the user's system. The interface also reminds users to remove credentials, tokens, and other sensitive information before submitting logs.

How I Built It

I used AWS for hosting and serverless infrastructure, with OpenAI providing the language-model capabilities.
The application has three main components:
  1. Frontend: React, TypeScript, and Vite power the user interface. AWS Amplify Hosting serves the deployed frontend over HTTPS.
  2. Backend: Amazon API Gateway exposes an HTTPS endpoint that invokes an AWS Lambda function running Python 3.12. I used AWS Serverless Application Model (AWS SAM) to define and deploy the serverless resources.
  3. AI integration: The Lambda function calls OpenAI's Responses API. The OpenAI API key remains on the backend instead of being embedded in the browser application.
The frontend sends an error message to the /troubleshoot endpoint. The backend validates the input, calls the model, and returns structured JSON for the interface to display.
This architecture keeps the frontend lightweight while allowing the backend to handle input validation, AI requests, and error responses.

The Real Challenge: Debugging the Deployment

Getting the first deployment online was only part of the work. Connecting the frontend, backend, and AI service revealed several practical problems that I had to investigate and resolve.

Deploying the Serverless Backend

I used AWS SAM to build and deploy the backend. The guided deployment created the ShipShape CloudFormation stack in the ap-southeast-1 AWS Region.
After confirming the deployment, SAM reported that the stack had been created successfully and provided an API Gateway endpoint.
However, successfully creating the AWS resources did not guarantee that the complete application worked. I still needed to verify the request path from API Gateway through Lambda to the AI service.

Investigating an Unexpected AI Response

My first request to the deployed API returned HTTP 502 with the message:
The AI returned an unexpected answer. Please retry.
I inspected the Lambda logs using sam logs rather than assuming the deployment itself had failed.
The logs showed that the request to OpenAI's Responses API returned HTTP 200 OK, even though ShipShape returned an error to the client. This narrowed the investigation to what happened after the external API responded, including how the application processed and validated the result.
I investigated the response-handling path and corrected the application to handle the structured response expected by the frontend. After rebuilding and redeploying, I repeated the same API request.
The request then returned HTTP 200 OK with structured troubleshooting information for a Docker permission error. The response included a likely cause and diagnostic commands such as ls -l /var/run/docker.sock, groups, and systemctl status docker.
This was an important lesson: an upstream API returning success does not guarantee that your own application can successfully process its response.

Fixing a CORS Problem

After deploying the backend, I encountered a Cross-Origin Resource Sharing (CORS) issue. The frontend and backend were hosted on different origins, so the API needed to allow requests from the frontend's domain.
To investigate, I tested the API's preflight response and checked the configured frontend origin. The problem was caused by a mismatch in the configured origin, including a trailing slash. I updated the backend to normalize the FRONTEND_ORIGIN value by removing trailing slashes and added the Vary: Origin response header.
I then tested the preflight request and confirmed that the API returned HTTP 204 with the expected Access-Control-Allow-Origin header for the configured origin. Finally, I configured the deployed frontend's HTTPS URL as the production origin and redeployed the backend.
This experience reinforced an important lesson: CORS configuration must match the actual frontend origin, and small differences in URL formatting can prevent browser requests from succeeding.

Fixing the Amplify Frontend Build

The frontend deployment introduced two additional problems.
First, Amplify's npm ci command failed because package.json and package-lock.json were out of sync. The build logs identified missing lock-file entries for packages including @types/react, @types/react-dom, and csstype.
I regenerated the lock file locally with npm install and committed the updated file. This allowed Amplify's clean dependency installation to complete.
The next build failed because the build configuration attempted to enter the frontend directory twice. The existing preBuild command already used cd frontend && npm ci, so repeating cd frontend in the build phase caused a “No such file or directory” error.
I corrected amplify.yml to remove the redundant directory change. This addressed the build-command path problem.
These failures reinforced the importance of reading deployment logs carefully. One issue involved dependency consistency; the other involved build commands and working-directory assumptions. Although both appeared as failed Amplify deployments, they required different fixes.

The Details That Make ShipShape Useful

I wanted ShipShape to do more than return an AI-generated paragraph.
The interface presents the response in clearly separated sections, includes example errors to make experimentation easier, displays a loading state while the model responds, and provides helpful error messages when a request fails.
The application also validates input length and reminds users not to submit sensitive data. Its read-only approach is intentional: users remain in control of whether to run a suggested diagnostic command.
The agent does not guarantee that every diagnosis is correct or that every suggested step will resolve the problem. Its purpose is to give users a clearer, more structured starting point for investigating an error.

How I Verified It Worked

I tested the backend with a real request to the deployed API using a Docker daemon permission error.
The API returned HTTP 200 OK with structured troubleshooting output, including an explanation, likely cause, diagnostic steps, and verification commands.
I also tested the CORS preflight request and confirmed that it returned HTTP 204 with the expected local-development origin. During frontend deployment, I used the Amplify build logs to identify and resolve the dependency lock-file and directory-path failures.
The application is deployed here:
 
Evidence for the project:
  • A screenshot of ShipShape displaying a real troubleshooting result.
 
  • A screen recording showing the architecture and an error submission and the returned diagnosis.
 
I plan to use the actual deployed application and real responses as evidence of the working project, rather than relying only on screenshots of the source code.

What I Learned

This project reminded me that building an AI application involves much more than connecting a prompt to a model. Request validation, response processing, CORS, dependency management, deployment configuration, and error handling are all important to the user experience.
I also learned to debug one layer at a time. Lambda logs helped me investigate a response-processing failure. A direct curl request allowed me to verify CORS independently of the browser. Amplify's build logs revealed two separate deployment problems that needed different solutions.
ShipShape gave me hands-on experience bringing together AWS serverless services, a hosted frontend, and an external AI API into a working application.
My goal is to make DevOps troubleshooting a little less stressful—and to keep improving ShipShape based on how people use it.
 

The Experience

One thing I focused on was making troubleshooting less intimidating. Instead of simply returning an AI-generated answer, ShipShape organizes its response into an explanation, a likely cause, diagnostic steps, and verification commands. This gives users a clear path from understanding an error to investigating it, without asking the agent to execute commands or modify their systems.
I verified this approach by testing the backend with a Docker permission error and confirming that the API returned a structured diagnosis with relevant commands. This demonstrated that ShipShape could turn a specific technical problem into actionable troubleshooting guidance. It does not prove that every diagnosis will be correct, but it confirmed that the intended response structure worked for the tested case.
# agents# beginner-projects
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article