Guide · Open source

How to use Kratos: install the CLI, create a Go service

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Kratos is a Go framework for building microservices, the small backend services that together make up a larger application. It provides APIs for HTTP and gRPC traffic, middleware, service registry, configuration, logging and code generation from Protobuf definitions. This guide shows how to install the CLI, create and run a service, and where to look next.

Kratosgo-kratos/kratos · ★ 26k · MIT Install options & downloads

Quick start

1Install Go, protoc and protoc-gen-go. Make sure Go 1.25 or later is installed, along with protoc and protoc-gen-go.
2Install the Kratos CLI. Run go install for the kratos/cmd/kratos/v3 package, then run kratos upgrade.
3Create a service. Run kratos new helloworld and move into the new folder.
4Fetch dependencies. Run go mod tidy inside the project folder.
5Run the service. Run kratos run and open http://localhost:8000/helloworld/kratos.
6Add a Protobuf API. Add a .proto file, generate client and server code, then run go generate ./...

What you need before you install Kratos

Kratos is written for Go only, so you need a working Go toolchain. The project requires Go 1.25 or later. The generated service workflow also uses protoc and protoc-gen-go, so you should install those before you start.

Beginners with no Go or Protobuf experience may find the setup hard, so it helps to get comfortable with both first.

Go 1.25 or later
protoc
protoc-gen-go

Install the Kratos CLI

Install the command-line tool with the Go package manager, then upgrade the CLI tooling using the kratos command itself.

go install github.com/go-kratos/kratos/cmd/kratos/v3@latest
kratos upgrade

Create and run your first service

Use kratos new to generate a service project, move into its folder, fetch dependencies and start it with kratos run. Once the service starts, open the sample URL in your browser.

Visit http://localhost:8000/helloworld/kratos after the service starts.

kratos new helloworld
cd helloworld
go mod tidy
kratos run

Build from Protobuf definitions

Kratos supports an API-first workflow. You add a Protobuf file, generate client and server code from it, then generate the remaining Go code and run the service.

The source lists these steps for a fuller generated service flow.

kratos proto add api/helloworld/helloworld.proto
kratos proto client api/helloworld/helloworld.proto
kratos proto server api/helloworld/helloworld.proto -t internal/service
go generate ./...
kratos run

Understand the core code structure

A Kratos application creates HTTP and gRPC servers, then passes them to an app object. The app is given a name, a version and the servers to run. The example below uses port 8000 for HTTP and 9000 for gRPC.

http.NewServer sets up the HTTP transport
grpc.NewServer sets up the gRPC transport
kratos.New combines the name, version and servers into one application

package main

import (
	"github.com/go-kratos/kratos/v3"
	"github.com/go-kratos/kratos/v3/transport/grpc"
	"github.com/go-kratos/kratos/v3/transport/http"
)

func main() {
	httpSrv := http.NewServer(http.Address(":8000"))
	grpcSrv := grpc.NewServer(grpc.Address(":9000"))

	app := kratos.New(
		kratos.Name("helloworld"),
		kratos.Version("v1.0.0"),
		kratos.Server(httpSrv, grpcSrv),
	)
	if err := app.Run(); err != nil {
		panic(err)
	}
}

Upgrading from v2 to v3

Kratos v3 reduces core dependencies and makes previously implicit behavior explicit. If you run v2 services, read the v2 to v3 migration guide in the repository before you upgrade production services.

Migration guide: docs/migration/v2-to-v3.md in the repository

Where to find more help

The full documentation lives at go-kratos.dev. Examples and a project layout template are published in separate repositories. Community channels include Discord, GitHub Discussions and a WeChat group. Security issues should be reported privately to go-kratos@googlegroups.com.

Documentation: go-kratos.dev
Examples: github.com/go-kratos/examples
Project layout: github.com/go-kratos/kratos-layout
Discussions: github.com/go-kratos/kratos/discussions

What people use it for

Building a set of backend services that talk to each other over HTTP or gRPC
Starting an API-first project from Protobuf definitions
Creating a cloud-native service with pluggable registry and configuration components
Adding middleware such as recovery, logging, validation, tracing and metrics to services

Frequently asked questions

Is Kratos free to use?

Kratos is open-source software licensed under the MIT license. The source does not mention any paid tier.

What do I need to install Kratos?

You need Go 1.25 or later. For the generated service workflow you also need protoc and protoc-gen-go. The CLI is installed with go install.

Does Kratos work with languages other than Go?

No. The framework is written for Go only, so it is not a choice for projects that do not use Go.

How do I upgrade from Kratos v2?

Review the v2 to v3 migration guide in the repository before upgrading. The source notes that v3 makes previously implicit behavior explicit, so production services should be checked first.

What are alternatives to Kratos?

The source lists go-zero, go-micro, go-kit and beego as comparable projects. Kratos is described as a lightweight framework with explicit, composable components.

Where can I get help if a command fails?

Check the documentation at go-kratos.dev, the Discussions page on GitHub, or the Discord group. Make sure your Go, protoc and protoc-gen-go versions meet the listed requirements.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Kratos suits Go developers building several backend services that talk over HTTP or gRPC, especially teams that want an API-first workflow from Protobuf. If you do not use Go, or you are new to both Go and Protobuf, pick a simpler starting point or learn the basics first. Teams upgrading from v2 should read the migration guide before changing production services.

Install options & downloads