Mach5 One Agent Instructions

Mach5 One is the single-node Mach5 server. It exposes the Mach5 HTTP API, Data Explorer, MCP endpoint, and PostgreSQL-compatible SQL endpoint from one binary.

Use this file when you are an AI agent operating on or with the mach5-one repository.

When to use Mach5 One

Use Mach5 One when a user wants to:

• Run Mach5 on a single machine
• Use the Mach5 HTTP APIs locally
• Open Data Explorer locally
• Connect an MCP-compatible agent to Mach5
• Query local Mach5 data through a PostgreSQL-compatible endpoint
• Reproduce Mach5 tutorials, examples, or runtime issues
• Evaluate a workflow before moving it to Mach5 Enterprise

This repository is the Mach5 One runtime surface, not the complete Mach5 product documentation set and not the app registry. Common Mach5 feature docs cover concepts and APIs shared by Mach5 One and Mach5 Enterprise. Reusable Mach5 app catalogs are separate from this repository.

Repository map

Read these files first:

1. README.md — product overview and primary paths
2. docs/install.md — install and verification flow
3. docs/configuration.md — config file and endpoints
4. docs/quickstart.md — first-run workflow
5. docs/mcp.md — MCP setup
6. docs/agent-quickstart.md — agent-focused setup
7. docs/troubleshooting.md — common failures and issue-report fields
8. llms.txt and llms-full.txt — agent-readable documentation index/corpus

For the complete versioned documentation set and edition scope, use the Mach5 website docs: https://mach5.io/docs/next/overview/docs-scope

Examples:

• examples/basic-ingest/
• examples/basic-query/
• examples/agent-configs/
• examples/curl/

Commands

# Create default config and data directories
mach5-one init

# Start the server
mach5-one start

# Print version
mach5-one version

# Start with a custom config
mach5-one --config ./mach5-one.toml start

MACH5_ONE_CONFIG can also set the config path.

Stop the server with Ctrl-C or SIGTERM.

Default endpoints

Web UI and HTTP API: http://localhost:8080
API reference:        http://localhost:8080/apis/rapidoc
OpenAPI:              http://localhost:8080/apis/openapi.json
MCP:                  http://localhost:8080/mcp
Version:              http://localhost:8080/version.txt
Session:              http://localhost:8080/session
PostgreSQL wire:      localhost:5432

Use the configured ports if the user changed server.http_port or server.pg_port.

Agent workflow

1. Confirm Mach5 One is installed:

   mach5-one version
   

2. Start or verify the server:

   mach5-one start
   curl http://localhost:8080/version.txt
   

3. Connect MCP client to:

   http://localhost:8080/mcp
   

4. Discover tools/resources/prompts dynamically.

5. Ask before loading local files.

6. Use Data Explorer, /apis/rapidoc, /apis/openapi.json, and the PostgreSQL endpoint for user-facing workflows.

7. Treat indexes, warehouses, pipelines, query, Data Explorer, MCP, and apps as common Mach5 concepts unless the page specifically discusses Mach5 One local runtime behavior.

Issue-reporting instructions

File runtime issues in this repository. Use the most specific issue template available.

A useful report includes:

• mach5-one version
• OS and architecture
• Install method and release asset name
• Config path, with secrets removed
• Exact command run
• Expected behavior
• Actual behavior
• Logs or error output
• Whether the issue is reproducible with a clean data directory

Do not file public issues for suspected vulnerabilities. Follow SECURITY.md.

App guidance

Do not add reusable app manifests, app registries, app schemas, or app-specific docs to this repository.

Use this repository for the Mach5 One server, API/MCP setup, first-run examples, and runtime issue reports.