Meshery AGENTS.md: Your AI Coding Guide

Dec 11, 2025 by Admin 40 views

Welcome to Meshery, the universal package manager for cloud-native computing. Think of it as the "npm for Kubernetes," enabling you to discover, manage, and test cloud-native patterns and management planes. Meshery provides a unified platform for interacting with various cloud-native technologies, offering a streamlined experience for deploying, managing, and observing your cloud-native infrastructure. Whether you're a seasoned DevOps engineer or just starting with cloud-native, Meshery aims to simplify complexity and accelerate your journey.

Repository Structure

api/: Contains the RESTful API definitions and implementation for Meshery.
bin/: Houses build scripts and executable binaries for Meshery.
build/: Includes build-related tools and configurations.
cmd/: Entry points for Meshery services and CLI applications.
config/: Configuration files and templates for Meshery.
docs/: Source files for project documentation.
internal/: Private packages and code not intended for external use.
meshery-ui/: The frontend user interface for Meshery.
pkg/: Reusable libraries and core functionalities of Meshery.
provider/: Integrations and adapters for various cloud-native providers.
scheduler/: Components related to Meshery's scheduling and orchestration capabilities.
server/: Core server logic and HTTP handlers.
test/: Test suites and utilities.
ui/: Legacy or shared UI assets.
.github/: GitHub specific configurations and workflows.

Build & Development Commands

# Install dependencies
make install

# Build Meshery
make build

# Run tests
make test

# Lint code
make lint

# Run Meshery
make run

# Deploy Meshery (example, may vary)
make deploy

Code Style & Conventions

Meshery adheres to standard Go project conventions. We strive for clear, idiomatic Go code. Formatting is handled by go fmt and goimports. Linting is performed using golangci-lint, which enforces a comprehensive set of checks including style, potential bugs, and performance. Commit messages should follow the Conventional Commits specification for clarity and automated changelog generation. A .gitmessage template is provided to assist in crafting compliant commit messages.

Architecture Notes

Meshery's architecture is centered around a robust API server that orchestrates various adapters and providers. The core server handles incoming requests, interacts with the database for storing configuration and state, and communicates with adapters to manage cloud-native infrastructure. Adapters translate Meshery's generic operations into provider-specific actions. The UI provides a user-friendly interface for interacting with the Meshery API. Data flows from the UI or external clients to the API server, which then dispatches commands through the appropriate adapter to the target cloud-native environment. State and configuration are persisted in a backend datastore.

graph TD
    A[User/Client] --> B(Meshery API Server)
    B --> C{Database}
    B --> D[Meshery Adapters]
    D --> E(Cloud-Native Provider)
    B --> F[Meshery UI]
    F --> B

Testing Strategy

Meshery employs a comprehensive testing strategy encompassing unit, integration, and end-to-end (e2e) tests. Unit tests, located within package directories, verify individual functions and components in isolation. Integration tests focus on the interactions between different modules and services. E2E tests validate the complete system behavior from the user interface down to the cloud-native provider. Tests can be run locally using make test. Continuous Integration (CI) pipelines automatically execute these tests on every commit and pull request to ensure code quality and prevent regressions.

Security & Compliance

Security is paramount. Meshery does not handle sensitive secrets directly; instead, it relies on the underlying cloud-native platforms and Kubernetes for secret management. Dependency scanning is performed regularly using tools integrated into our CI/CD pipeline to identify and mitigate vulnerabilities in third-party libraries. We adhere to the Apache 2.0 license. Guardrails are in place to prevent accidental misconfigurations or destructive actions, especially within automated agent interactions.

Agent Guardrails

Automated agents interacting with Meshery must operate within defined boundaries. Certain critical configuration files, such as those related to core infrastructure deployment or sensitive credentials, should never be modified directly by agents unless explicitly authorized and reviewed. All significant changes initiated by agents require mandatory review from a designated team member or maintainer. Rate limiting may be applied to agent requests to prevent abuse and ensure system stability. Specific file patterns or directories might be designated as read-only for agents.

Extensibility Hooks

Meshery is designed for extensibility. New providers and services can be integrated via adapters. Feature flags allow for enabling or disabling specific functionalities dynamically. Environment variables are extensively used for configuration, allowing customization of Meshery's behavior without code changes. Plugin points, where applicable, allow for custom logic injection into core workflows. These hooks enable users and developers to tailor Meshery to their specific needs and integrate it seamlessly into diverse environments.