# Get started with the Go AppHost

A Go AppHost is a Go program that defines the resources in your application and how they connect. It uses the same app model as a C# AppHost, through a Go SDK that the Aspire CLI generates from the hosting integrations you install.

## Prerequisites

- [Go](https://go.dev/dl/) 1.26 or later, with `go` on your `PATH`
- The [Aspire CLI](/get-started/install-cli/)
- [Node.js](https://nodejs.org/) for the starter template's React frontend
- A container runtime if you include the optional Redis cache in the starter template. See [Aspire prerequisites](/get-started/prerequisites/) for the supported options.

## Create a Go AppHost

Create a new app from the Go starter template:

```bash title="Aspire CLI"
aspire new aspire-go-starter -n aspire-app -o aspire-app
```

The template creates a Go AppHost (`apphost.go`), a Go API (`api/`), a Vite and React frontend (`frontend/`), and the generated SDK. The frontend waits for the API and proxies `/api` requests to it, and it loads `/api/weatherforecast` on startup. When you publish, the frontend build output is copied into the Go API container and served from `./static`, so the deployed app uses one origin. Redis is optional: `aspire new` prompts for it interactively (default yes), and non-interactive runs omit it unless you pass `--use-redis-cache true`. To choose from the templates that support Go, run `aspire new --language go` instead.

<LearnMore>
  See the [`aspire new` command reference](/reference/cli/commands/aspire-new/) for all options.
</LearnMore>

The project has the following structure:

- aspire-app/
  - .aspire/modules/  Generated Go SDK (do not edit)
    - aspire.go
    - base.go
    - go.mod
    - transport.go
  - .vscode/
    - extensions.json  Recommended VS Code extensions
  - api/  Go API that the AppHost runs
    - go.mod
    - main.go
    - telemetry.go
  - frontend/  Vite and React frontend
    - public/
    - src/
    - index.html
    - package.json
    - package-lock.json
    - vite.config.ts
    - ...
  - .gitignore  Keeps the generated .aspire/ directory out of source control
  - apphost.go  Your AppHost entry point
  - aspire.config.json  Aspire configuration
  - go.mod  Go module for the AppHost

## Run the AppHost

From the project directory, start the AppHost with the Aspire CLI:

```bash title="Aspire CLI"
aspire run
```

The CLI regenerates the SDK when the `packages` list has changed, starts the AppHost with `go run .`, and prints the dashboard URL. Open the dashboard to see the `app` Go API and `frontend` resources with their logs, traces, and metrics. If you included Redis, the dashboard also shows the `cache` resource. Open the `frontend` endpoint to use the React app.

:::note
Always start the AppHost with `aspire run`. The CLI sets the environment variables that the SDK uses to connect to the AppHost server, so running `go run .` on its own fails with `REMOTE_APP_HOST_SOCKET_PATH environment variable not set`.
:::

## apphost.go

The AppHost is a `package main` Go program. The following example shows the starter with Redis enabled. It defines a Go API, a Vite frontend that references and waits for the API, and a Redis cache:

```go title="apphost.go"
package main

import (
	"log"

	"apphost/modules/aspire"
)

func main() {
	builder, err := aspire.CreateBuilder()
	if err != nil {
		log.Fatal(aspire.FormatError(err))
	}

	// A Redis cache the API will use for read-through caching.
	cache := builder.AddRedis("cache")

	// Keep Go modules current and send traces, metrics, and logs to the dashboard.
	api := builder.AddGoApp("app", "./api").
		WithModTidy().
		WithReference(cache).
		WaitFor(cache).
		WithHttpEndpoint(aspire.HttpEndpointEnv("PORT")).
		WithHttpHealthCheck(aspire.HttpHealthCheckPath("/health")).
		WithExternalHttpEndpoints().
		WithOtlpExporter()

	// Reference the app for Vite proxying and wait until it is healthy.
	frontend := builder.AddViteApp("frontend", "./frontend").
		WithReference(api).
		WaitFor(api)

	// Bundle the frontend into the app container for same-origin production serving.
	api.PublishWithContainerFiles(frontend, "./static")

	application, err := builder.Build()
	if err != nil {
		log.Fatal(aspire.FormatError(err))
	}
	if err := application.Run(); err != nil {
		log.Fatal(aspire.FormatError(err))
	}
}
```

`PublishWithContainerFiles` copies the frontend build output into the Go API container at `./static` when you publish. The API serves those files from the same origin as its API endpoints.

If you omit Redis, the generated AppHost has no `AddRedis` call, `WithReference(cache)`, or `WaitFor(cache)`. The frontend and publish configuration stay the same.

The program has three parts:

1. `aspire.CreateBuilder()` connects to the AppHost server that the CLI starts and returns the builder.
2. `AddGoApp`, `AddViteApp`, and the optional `AddRedis` add resources. Each call returns a handle, so `WithReference`, `WaitFor`, and the other configuration methods chain onto it.
3. `builder.Build()` creates the application, and `application.Run()` blocks until the AppHost stops. Both return an error. You don't check each resource: errors from the `Add` and `With` calls are collected and reported together when you call `Build`. See [Go AppHost API conventions](/app-host/go-apphost-conventions/#errors) for how errors are reported and formatted.

See [Deploy Go apps](/deployment/go-apps/) for publishing and deployment options.

## aspire.config.json

The `aspire.config.json` file is the central configuration for your AppHost. This example includes the optional Redis integration:

```json title="aspire.config.json"
{
  "appHost": {
    "path": "apphost.go",
    "language": "go"
  },
  "packages": {
    "Aspire.Hosting.Go": "17.0.0",
    "Aspire.Hosting.JavaScript": "17.0.0",
    "Aspire.Hosting.Redis": "17.0.0"
  },
  "profiles": {
    "https": {
      "applicationUrl": "https://localhost:17127;http://localhost:15118",
      "environmentVariables": {
        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21169",
        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22260"
      }
    },
    "http": {
      "applicationUrl": "http://localhost:15118",
      "environmentVariables": {
        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19001",
        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20115",
        "ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true"
      }
    }
  }
}
```

If you omit Redis, the `packages` section contains only `Aspire.Hosting.Go` and `Aspire.Hosting.JavaScript`.

### Key sections

| Section | Description |
|---------|-------------|
| `appHost.path` | Path to the AppHost entry point (`apphost.go`) |
| `appHost.language` | The AppHost language (`go`) |
| `packages` | Hosting integration packages and their versions. `aspire add` updates this section. |
| `profiles` | Launch profiles with dashboard URLs and environment variables |

## Generated SDK

The `.aspire/modules/` directory holds the Go SDK that the CLI generates from the packages in `aspire.config.json`. The CLI creates and updates it, so don't edit these files.

| File | Purpose |
|------|---------|
| `aspire.go` | Typed API for the installed integrations |
| `base.go` | Handle, option, and error infrastructure |
| `transport.go` | JSON-RPC transport to the AppHost server |

The SDK is one Go package for all integrations. The AppHost's `go.mod` file maps the `apphost/modules/aspire` import path to the `.aspire/modules/` directory, so `apphost.go` imports it like any other package:

```text title="go.mod"
module apphost

go 1.26

require apphost/modules/aspire v0.0.0

replace apphost/modules/aspire => ./.aspire/modules
```

The SDK regenerates when:

- You run `aspire add` to add or update an integration
- You run `aspire run` or `aspire start` and the package list has changed
- You run `aspire restore`

:::tip
The starter's `.gitignore` already lists `.aspire/`. The directory holds generated files that the CLI recreates from `aspire.config.json`, so keep it out of source control.
:::

### Documentation in the SDK

The generated `aspire.go` includes godoc comments, so `go doc` and editor hover (gopls) show each API's summary, parameters, and return value. Obsolete APIs carry a `Deprecated:` notice that gopls and staticcheck flag, and experimental APIs are marked with an **Experimental** heading.

### Restore the SDK

Run `aspire restore` to regenerate the SDK without starting the AppHost:

```bash title="Aspire CLI"
aspire restore --apphost apphost.go
```

Restore after you clone a repository, switch branches, or edit the `packages` section by hand. In CI, restore before any step that compiles the AppHost, such as `go build` or `go vet`.

## Add integrations

Use `aspire add` from the AppHost directory to add a hosting integration. The CLI adds the package to `aspire.config.json` and regenerates the Go SDK in `.aspire/modules/`:

```bash title="Aspire CLI"
aspire add postgresql
```

The `packages` section now lists the PostgreSQL integration:

```json title="aspire.config.json" ins={6}
{
  "packages": {
    "Aspire.Hosting.Go": "17.0.0",
    "Aspire.Hosting.JavaScript": "17.0.0",
    "Aspire.Hosting.Redis": "17.0.0",
    "Aspire.Hosting.PostgreSQL": "17.0.0"
  }
}
```

The regenerated SDK has an `AddPostgres` method. This AppHost adds a PostgreSQL server with one database and gives the API access to it, retaining the starter's frontend and publish configuration. As in the previous example, omit the Redis package and cache configuration if you didn't include Redis:

```go title="apphost.go"
package main

import (
	"log"

	"apphost/modules/aspire"
)

func main() {
	builder, err := aspire.CreateBuilder()
	if err != nil {
		log.Fatal(aspire.FormatError(err))
	}

	cache := builder.AddRedis("cache")
	db := builder.AddPostgres("postgres").AddDatabase("postgresdb")

	api := builder.AddGoApp("app", "./api").
		WithModTidy().
		WithReference(cache).
		WithReference(db).
		WaitFor(cache).
		WaitFor(db).
		WithHttpEndpoint(aspire.HttpEndpointEnv("PORT")).
		WithExternalHttpEndpoints().
		WithOtlpExporter()

	frontend := builder.AddViteApp("frontend", "./frontend").
		WithReference(api).
		WaitFor(api)

	api.PublishWithContainerFiles(frontend, "./static")

	app, err := builder.Build()
	if err != nil {
		log.Fatal(aspire.FormatError(err))
	}
	if err := app.Run(); err != nil {
		log.Fatal(aspire.FormatError(err))
	}
}
```

- `AddPostgres` adds the PostgreSQL server, and `AddDatabase` returns a handle for a database on that server.
- `WithReference(db)` passes the connection details to the API as environment variables named after the resource, such as `POSTGRESDB_URI`. See [Connect to PostgreSQL](/integrations/databases/postgres/postgres-connect/) for a Go example that reads them.
- `WaitFor(db)` starts the API after the database is ready.
- Any error from these calls is reported when you call `Build`.

## Orchestrate apps in other languages

A Go AppHost can run resources written in other languages next to your Go apps. Add the integration for each language that you use. Python and Node.js must also be installed, because these resources run on your machine:

```bash title="Aspire CLI"
aspire add python
aspire add javascript
```

This AppHost runs a Go API and a Python recommendation service that share a Redis cache, and a Vite frontend that calls both:

```go title="apphost.go"
package main

import (
	"log"

	"apphost/modules/aspire"
)

func main() {
	builder, err := aspire.CreateBuilder()
	if err != nil {
		log.Fatal(aspire.FormatError(err))
	}

	cache := builder.AddRedis("cache")

	api := builder.AddGoApp("api", "./api").
		WithReference(cache).
		WaitFor(cache).
		WithHttpEndpoint(aspire.HttpEndpointEnv("PORT"))

	recommender := builder.AddUvicornApp("recommender", "./recommender", "main:app").
		WithReference(cache).
		WaitFor(cache)

	builder.AddViteApp("web", "./web").
		WithReference(api).
		WithReference(recommender).
		WaitFor(api)

	app, err := builder.Build()
	if err != nil {
		log.Fatal(aspire.FormatError(err))
	}
	if err := app.Run(); err != nil {
		log.Fatal(aspire.FormatError(err))
	}
}
```

- `AddUvicornApp` runs a Python ASGI app. The `main:app` argument names the Python module and the application object in it.
- `AddViteApp` runs a Vite frontend. `AddUvicornApp` and `AddViteApp` already register an `http` endpoint that reads its port from `PORT`, so only the Go API calls `WithHttpEndpoint`.
- `WithReference` and `WaitFor` work the same for every resource type. The frontend receives the endpoints of the API and the recommender, and it starts after the API is ready.

<LearnMore>
  See [Set up JavaScript apps in the AppHost](/integrations/frameworks/javascript/) and [Python integration](/integrations/frameworks/python/) for the options of each integration.
</LearnMore>

## Debug a Go AppHost

{/* PLACEHOLDER: replace the link below with the Go AppHost debugging guide when it is published. */}

To debug AppHosts and their resources in Visual Studio Code, see [Run, debug, and deploy](/get-started/aspire-vscode-extension/#run-debug-and-deploy).

## See also

- [Go AppHost API conventions](/app-host/go-apphost-conventions/)
- [Go API reference](/reference/api/go/)
- [Set up Go apps in the AppHost](/integrations/frameworks/go/go-host/)
- [Multi-language architecture](/architecture/multi-language-architecture/)
- [aspire new command](/reference/cli/commands/aspire-new/)
- [aspire run command](/reference/cli/commands/aspire-run/)
- [aspire restore command](/reference/cli/commands/aspire-restore/)