Quick Start Guide

This guide demonstrates how to build a REST API service with Encore, run it locally with tracing and generated API docs, and deploy it to the cloud.

You'll need Node.jsGo installed.

1. Install Encore and create your app

The Encore CLI provisions your local environment and runs your local development dashboard.

The CLI then prompts you to:

1. Create a free account, if you're new to Encore. It's needed for the deployment step at the end of this guide, and for managing secrets.
2. Select your app's language: TypeScript or Go.
3. Choose a starter template. Pick Hello World and continue.
4. Install AI instructions for agents like Cursor and Claude Code. Pick the one you use, or skip it. See AI Tools Integration for details.
5. Pick a name for your app.

Encore creates your app in a folder named after it.

2. Run your app

Start your app locally:

$ cd your-app-name # replace with the app name you picked
$ encore run

Your local environment is running. Encore sets up the infrastructure your app needs, including databases and Pub/Sub.

Open the Local Development Dashboard

Open http://localhost:9400 in your browser.

The Local Development Dashboard gives you an API explorer, a Service Catalog with generated documentation, and distributed tracing. It also includes Encore Flow, a live visual map of your microservice architecture.

Call your API

Leave the app running and call your API from the API Explorer:

Or call it from a separate terminal:

$ curl http://localhost:4000/hello/world
{"Message": "Hello, world!"}

That response means your first Encore API call worked.

Review a trace of the request

Click the request in the right column of the local dashboard to see its trace.

There's not much to see for a single request and response. But in a real system, Encore automatically traces every request, showing which services, database queries, and Pub/Sub messages it touched, where time was spent, and where failures occurred, without any manual logging. See the tracing docs.

3. Take a look at the code

hello/hello.ts
TypeScript
import { api } from "encore.dev/api";

export const world = api(
  { method: "GET", path: "/hello/:name", expose: true },
  async ({ name }: { name: string }): Promise<Response> => {
    return { message: `Hello ${name}!` };
  }
);

interface Response {
  message: string;
}

hello/encore.service.ts
TypeScript
import { Service } from "encore.dev/service";

export default new Service("hello");

hello/hello.go
TypeScript
// Service hello implements a simple hello world REST API.
package hello

import (
	"context"
)

// This is a simple REST API that responds with a personalized greeting.
//
//encore:api public path=/hello/:name
func World(ctx context.Context, name string) (*Response, error) {
	msg := "Hello, " + name + "!"
	return &Response{Message: msg}, nil
}

type Response struct {
	Message string
}

TypeScript
//encore:api public path=/hello/:name

4. Make a code change

In the same file, change the "Hello" message to "Howdy", then save.

The Encore CLI daemon detects the change, recompiles, and reloads your local environment:

Changes detected, recompiling...
Reloaded successfully.
TRC registered endpoint endpoint=World path=/hello/:name service=hello
TRC listening for incoming HTTP requests

Call your API again to see the change:

$ curl http://localhost:4000/hello/world
{"Message": "Howdy, world!"}

Your change reloaded automatically, with no restart needed. Now deploy it.

5. Deploy your app

Encore's cloud platform deploys your app for you. It includes free development hosting, and for production it deploys to your own AWS or GCP account.

Didn't create an account in step 1? Follow linking an existing app to Encore's cloud platform first.

Push your changes to deploy:

$ git add -A .
$ git commit -m 'Initial commit'
$ git push encore

Encore's cloud platform builds and tests your app, provisions infrastructure, and deploys to a staging environment. The command prints a URL like https://app.encore.dev/$APP_ID/deploys/....

Open that URL to follow the deployment in the Cloud Dashboard.

From there you can view production traces, connect your cloud account, and integrate with GitHub.

What's next?

• Add infrastructure to your app by declaring it in code: see the Encore.ts primitivesEncore.go primitives for databases, Pub/Sub, object storage, cron jobs, and secrets.
• Or let your AI editor do it. With the AI instructions installed, it knows how Encore declares infrastructure, so a prompt like "add a Postgres database to the hello service and store each greeting" is enough. See AI Tools Integration.
• Build a real app with the Uptime Monitor tutorial: an event-driven system using APIs, databases, Pub/Sub, and cron jobs.
• Join the friendly community on Discord to ask questions and meet other Encore developers.