# Go app recipe

URL: https://briq.cloud/cookbook/go

> Your Go code running as a service, from files or a GitHub repo: it builds the module and starts the binary. No image to build.

Tags: app, language

Guides:

- [Run your own app](https://briq.cloud/docs/guides/run-your-own-app.md): Your code as a running service, with a URL, in one call and no image to build.
- [Run a GitHub repo](https://briq.cloud/docs/guides/run-a-github-repo.md): An app from a repo, running with a URL. The briq downloads the code itself, and nothing is built on your side.

## Run it

MCP:

```ts
briq_run({
  recipe: "go",
  params: {
    "version": "1.25",
    "port": 8080,
    "env": {},
    "size": "small"
  },
  wait: true
})
```

REST:

```bash
curl -X POST https://api.briq.cloud/v1/briqs \
  -H "Authorization: Bearer $BRIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe": "go",
    "params": {
      "version": "1.25",
      "port": 8080,
      "env": {},
      "size": "small"
    },
    "wait": true
  }'
# → { "briqs": [{ "id": "bq_…", … }], "outputs": { "APP_URL": "…" }, … }

# ... when done, for each briq id
curl -X DELETE https://api.briq.cloud/v1/briqs/<id> \
  -H "Authorization: Bearer $BRIQ_API_KEY"
```

## Parameters

| Name | Type | Options | Default | What it does |
| --- | --- | --- | --- | --- |
| `version` | enum | 1.25, 1.24 | "1.25" | — |
| `files` | record | { "path": "content" \| { base64 } } | — | Your app's files, path → content (text, or { base64 }). Relative paths go under /app. For a bigger app, or one already on GitHub, pass `repo` instead. Without either, a hello-world app. |
| `repo` | object | { url, ref?, dir?, token? } | — | Your code from a repo instead of `files`. url: "github.com/owner/app", or on another host (GitLab, Bitbucket, Codeberg) the https URL of a .tar.gz archive, without ref. ref: a branch, tag or commit sha; default branch; a full sha pins the code. dir: the app's folder, e.g. "backend". token, private repos only: { secret: "GITHUB_TOKEN", value }, a fine-grained token with Contents: read on this repo; never the person's own token. The briq downloads the code itself, installs when a lockfile changed, runs `build` when the commit changed, then `start` |
| `install` | string | — | — | Shell command replacing the default install step: run before each start; with `repo`, only when a lockfile changed (go and rust build here, at each start) |
| `build` | string | — | — | Shell command run after the install, e.g. "npm run build": with `repo`, only when the commit or the install changed; with files, at each start |
| `start` | string | — | — | Shell command that starts the app (it must not exit). With `repo`, pass it: the default (python app.py, ruby app.rb…) rarely matches a repo; node runs npm start, bun bun run start |
| `port` | number | — | 8080 | — |
| `env` | record | { NAME: "value" \| { secret, value? } } | {} | Env vars. A credential goes as { secret: "NAME", value: "…" }: stored encrypted and never shown again |
| `size` | enum | nano, small, medium, large | "small" | A build (Next.js, Nuxt, a Rust release, a Go toolchain) is many times faster on medium or large: small has one shared CPU, slowed down once a long build used its burst. Up to small, a sleeping briq wakes from a memory snapshot in seconds; medium and large start from scratch on a wake (with `repo`: the branch is looked up again, and a new commit is installed and built before the app answers) |
| `diskGb` | number | — | — | With `repo` only: the size in GB of the volume (/work) that holds the code, its dependencies and build caches |

## Outputs

Returned by `briq_run` once the stack is healthy. Hosts resolve inside your team network; secrets are generated per run.

| Output | Value |
| --- | --- |
| `APP_URL` | `http://app.<stack>.internal:8080` |

## What it runs

| Briq | Image | Ports | Size | Volume |
| --- | --- | --- | --- | --- |
| app | `golang:1.25-alpine` | 8080 | small | — |

## When to use it

* You wrote a Go service and want it built and running next to its database, without a
  Dockerfile or a registry.

## Tips

* **Code in a repo**: pass `repo: { url: "github.com/owner/app" }` instead of `files`. See
  [Run a GitHub repo](https://briq.cloud/docs/guides/run-a-github-repo).
* **Pass the module as `files`**: `go.mod`, `main.go` and the rest, with relative paths (they go
  under `/app`). `go.sum` too when there are dependencies.
* **It builds at each start** (`go build`), then runs the binary. The build cache stays on the
  disk, so a restart rebuilds in seconds; the first start downloads modules and takes longer. If
  it outlasts `briq_run`'s two minutes, the briq shows `creating` until the build is done:
  `briq_status` tells you when it runs.
* **`ListenAndServe(":" + os.Getenv("PORT"), …)`** listens on IPv6 and IPv4; 8080 by default.
* **Publish it as you run it** with `expose: "private"` (or `"public"` for anyone): it returns `URL`.
* **Step by step**: [Run your own app](https://briq.cloud/docs/guides/run-your-own-app), with a database and a URL.