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

bash

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/api/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:

bash

# 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.

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

The MCP tools API is available at:

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

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

bash

micro run --mcp-address :3000

Hot Reload

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

bash

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)

json

{
  "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:

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

Environment Management

bash

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:

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

Without Configuration

If no micro.mu or micro.json exists:

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

Logs

Service logs are written to:

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

View logs:

bash

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

Process Management

bash

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:

bash

micro run github.com/micro/blog

Options

bash

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

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