/internal/website/docs/guides/micro-run.md

layout

layout
default

micro run - Local Development

micro run provides a complete development environment for Go microservices.

Note

: This guide focuses on micro run features. For a comparison with micro server and gateway architecture details, see the CLI & Gateway Guide.

Quick Start

micro new helloworld
cd helloworld
micro run

Open http://localhost:8080 to see your service.

What You Get

When you run micro run, you get:

URL	Description
http://localhost:8080	Web dashboard - browse and call services
http://localhost:8080/agent	Agent playground - AI chat with MCP tools
http://localhost:8080/api	API explorer - browse endpoints and schemas
http://localhost:8080/api/{service}/{method}	API gateway - HTTP to RPC proxy
http://localhost:8080/mcp/tools	MCP tools - list all services as AI tools
http://localhost:8080/auth/tokens	Token management - create and manage API tokens
http://localhost:8080/auth/scopes	Scope management - restrict endpoint access
http://localhost:8080/auth/users	User management - create and manage users
http://localhost:8080/health	Health checks - aggregated service health
http://localhost:8080/services	Service list - JSON

Plus:

• Authentication - JWT auth enabled with default credentials (admin/micro)
• Hot Reload - File changes trigger automatic rebuild
• Dependency Ordering - Services start in the right order
• Environment Management - Dev/staging/production configs
• MCP Gateway - Optional dedicated MCP protocol listener via --mcp-address

Features

API Gateway

The gateway converts HTTP requests to RPC calls. All API calls require authentication:

# Log in at http://localhost:8080 with admin/micro to get a session
# Or use a token for programmatic access:
curl -X POST http://localhost:8080/api/helloworld/Say.Hello \
  -H "Authorization: Bearer <token>" \
  -d '{"name": "World"}'

# Response
{"message": "Hello World"}

Create tokens at /auth/tokens. The default admin token has * scope (full access).

Agent Playground

The agent playground at /agent lets you interact with your services using AI. Your services are automatically exposed as MCP (Model Context Protocol) tools — no configuration needed.

1. Open http://localhost:8080/agent
2. Configure your API key in Agent Settings (supports OpenAI and Anthropic)
3. Chat with the AI agent — it can discover and call your services as tools

The MCP tools API is available at:

• /mcp/tools — list all services as AI-callable tools
• /mcp/call — invoke a tool (service endpoint) by name

For a dedicated MCP protocol listener (for external AI clients), use:

micro run --mcp-address :3000

Hot Reload

By default, micro run watches for .go file changes and automatically rebuilds and restarts affected services.

micro run              # Hot reload enabled (default)
micro run --no-watch   # Disable hot reload

Changes are debounced (300ms) to handle rapid saves from editors.

Configuration File

For multi-service projects, create a micro.mu file to define services, dependencies, and environments.

micro.mu (Recommended)

# Service definitions
service users
    path ./users
    port 8081

service posts
    path ./posts
    port 8082
    depends users

service web
    path ./web
    port 8089
    depends users posts

# Environment configurations
env development
    STORE_ADDRESS file://./data
    DEBUG true

env production
    STORE_ADDRESS postgres://localhost/db
    DEBUG false

micro.json (Alternative)

{
  "services": {
    "users": {
      "path": "./users",
      "port": 8081
    },
    "posts": {
      "path": "./posts",
      "port": 8082,
      "depends": ["users"]
    }
  },
  "env": {
    "development": {
      "STORE_ADDRESS": "file://./data"
    }
  }
}

Service Properties

Property	Required	Description
path	Yes	Directory containing the service (with main.go)
port	No	Port the service listens on (enables health check waiting)
depends	No	Services that must start first (space-separated in .mu, array in .json)

Dependency Ordering

When depends is specified, services start in topological order:

1. Services with no dependencies start first
2. Each service waits for its dependencies to be ready
3. If a service has a port, we wait for /health to return 200
4. Circular dependencies are detected and reported as errors

Environment Management

micro run                    # Uses 'development' (default)
micro run --env production   # Uses 'production'
micro run --env staging      # Uses 'staging'
MICRO_ENV=test micro run     # Environment variable override

Environment variables from the config are injected into each service's environment.

Graceful Shutdown

On SIGINT (Ctrl+C) or SIGTERM:

1. Services stop in reverse dependency order
2. SIGTERM is sent first (graceful)
3. After 5 seconds, SIGKILL if still running
4. PID files are cleaned up

Without Configuration

If no micro.mu or micro.json exists:

1. All main.go files are discovered recursively
2. Each is built and run
3. No dependency ordering
4. Hot reload still works

Logs

Service logs are written to:

• Terminal: Colorized with service name prefix
• File: ~/micro/logs/{service}-{hash}.log

View logs:

micro logs          # List available logs
micro logs users    # Show logs for 'users' service

Process Management

micro status        # Show running services
micro stop users    # Stop a specific service

Example: micro/blog

The micro/blog project demonstrates a multi-service setup:

# micro.mu
service users
    path ./users
    port 8081

service posts
    path ./posts
    port 8082
    depends users

service comments
    path ./comments
    port 8083
    depends users posts

service web
    path ./web
    port 8089
    depends users posts comments

Run it:

micro run github.com/micro/blog

Options

micro run                        # Gateway on :8080, hot reload
micro run --address :3000        # Custom gateway port
micro run --no-gateway           # Services only, no HTTP gateway
micro run --no-watch             # Disable hot reload
micro run --env production       # Use production environment
micro run --mcp-address :3000    # Enable MCP protocol gateway for AI clients

Tips

1. Browse First: Open http://localhost:8080 to explore your services
2. Try the Agent: Open http://localhost:8080/agent to chat with your services via AI
3. Port Configuration: Set port for services to enable health check waiting
4. Health Endpoint: Implement /health returning 200 for reliable startup sequencing
5. Environment Separation: Keep secrets in production env, use file:// paths for development
6. Hot Reload Scope: Only .go files trigger rebuilds; static assets don't