Using HTTP routers and files

Use an HTTP router to handle streaming requests, serve static assets, or integrate an HTTP framework. To publish files created by a durable agent, add live file mappings to that agent instead. The router and file semantics page explains how these features interact with code-first endpoints, authentication, and durable execution.

The examples below belong in an existing Golem application. Use a CLI and SDK from the same Golem version. Commands assume a local server on your machine, with the application gateway on port 9006.

Handling streaming requests

Define a router with a unique type name and a literal mount path. This EchoRouter streams an upload back to the caller at /echo. It does not collect the upload into memory or calculate its length first.

TypeScript


import { defineHttpRouter } from '@golemcloud/golem-ts-sdk';
 
export const EchoRouter = defineHttpRouter('EchoRouter')
  .mount('/echo')
  .implement((request) => new Response(request.body));

The Web adapter accepts standard Request and Response objects, so a framework with a Fetch-compatible handler can supply the function passed to .implement. Keep its body streaming. For the original, unnormalized HTTP envelope, use .implementRaw instead; see Working with headers.

Web Request, Response, and Headers are normalized views, not a lossless replacement for the canonical envelope. Web APIs can normalize methods and URLs, combine fields, or reject methods and statuses. The Web handler’s context exposes the original request; withRawHeaders supplies ordered byte-valued response fields.

Effect TypeScript


import { Effect } from "effect"
import {
  HttpRouter as Routes,
  HttpServerRequest,
  HttpServerResponse,
} from "effect/unstable/http"
import { Http, HttpRouter } from "@golemcloud/effect-golem"
 
const routes = Routes.add("POST", "/", Effect.gen(function* () {
  const request = yield* HttpServerRequest.HttpServerRequest
  return HttpServerResponse.stream(request.stream)
}))
 
HttpRouter.define("EchoRouter", {
  mount: Http.mount("/echo"),
}).implement(Routes.toHttpEffect(routes))

Use Effect’s HttpRouter (aliased here as Routes) to compose routes. It sees mount-relative URLs: POST / above handles public POST /echo. Inside the handler, yield* HttpRouter.request gives the original full path, query, byte-valued headers, and the same single-consumer body. Do not consume both body views.

Acquire request resources with Effect.acquireRelease or Effect.addFinalizer. The request scope stays open through response consumption; do not rely solely on finalizers inside a body stream that might never start. The application factory runs inside each request’s scope. Resources are released on completion, failure, or local Effect interruption. HEAD and 204/205/304 do not start body streams, so cleanup for eagerly acquired resources belongs to the request scope, not only to a stream’s ensuring finalizer.

HttpRouter.request also preserves absent versus empty query strings. The text, json, and arrayBuffer accessors buffer under HttpIncomingMessage.MaxBodySize; using the request stream does not collect it.

Respondable failures retain their HTTP responses, including HttpApi validation errors. Router misses and request parsing failures become 404 and 400. Other application failures remain invocation failures. The adapter does not support response FormData, non-Uint8Array raw bodies, or WebSocket upgrades.

Local Effect interruption runs and awaits finalizers, but host-level Wasm interruption does not deliver cooperative cancellation to JavaScript. The runtime also cannot interrupt a response producer while its first request for a body chunk is pending. Do not assume Effect finalizers run on every client disconnect or host interruption.

Rust


use golem_rust::agentic::{Config, HttpRequest, HttpResponse, HttpRouter};
use golem_rust::http_router;
 
struct EchoRouter;
 
#[http_router(name = "EchoRouter", mount = "/echo")]
impl HttpRouter for EchoRouter {
    type Config = ();
 
    fn new(_: Config<()>) -> Self {
        Self
    }
 
    async fn handle(&self, request: HttpRequest) -> HttpResponse {
        HttpResponse {
            status: 200,
            headers: vec![],
            body: request.body,
        }
    }
}

Scala


import golem.{BaseAgent, UShort}
import golem.runtime.annotations.*
import golem.runtime.http.*
import scala.concurrent.Future
 
@httpRouter(typeName = "EchoRouter", mount = "/echo")
trait EchoRouter extends BaseAgent {
  @httpHandler def serve(request: HttpRequest): Future[HttpResponse]
}
 
@agentImplementation()
final class EchoRouterImpl extends EchoRouter {
  def serve(request: HttpRequest): Future[HttpResponse] =
    Future.successful(HttpResponse(UShort(200), Nil, request.body))
}

MoonBit


///|
#derive.http_router
#derive.mount("/echo")
struct EchoRouter {}
 
///|
fn EchoRouter::new() -> EchoRouter { EchoRouter::{ } }
 
///|
#derive.http_handler
pub fn EchoRouter::serve(
  _self : Self,
  request : @http.HttpRequest,
) -> @http.HttpResponse {
  let input = request.body
  {
    status: 200,
    headers: [],
    body: @schema.AgentStream::produce(
      async fn(writer) {
        defer input.drop()
        for ;; {
          match input.read() {
            None => return
            Some(chunk) =>
              if writer.write_one(chunk) is @schema.PeerDropped { return }
          }
        }
      },
      on_unstarted_drop=() => input.drop(),
    ),
  }
}

Import golemcloud/golem_sdk/http and golemcloud/golem_sdk/schema in the component’s moon.pkg. Build through golem build so it generates registration and schema code before compiling.

Go


package routers
 
import (
	"io"
	"net/http"
 
	"github.com/golemcloud/golem/sdks/go/golem"
)
 
var EchoRouter = golem.DefineHTTPRouter(golem.RouterSpec{Name: "EchoRouter", Mount: "/echo"})
 
func init() {
	EchoRouter.Handle(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		_, _ = io.Copy(w, r.Body)
	}))
}

Handle accepts any http.Handler, so an http.ServeMux, a third-party router, or an existing service can serve the mount. The handler sees r.URL.Path as the full public path; wrap it in http.StripPrefix("/echo", ...) to route relative to the mount. Blank-import the package from the component’s main.go. For the original, unnormalized HTTP envelope, use HandleRaw instead; see Working with headers.

Merge this deployment into your application’s manifest:

golem.yaml


httpApi:
  deployments:
    local:
      - domain: localhost:9006
        scheme: http
        agents:
          EchoRouter: {}

Build, deploy, and send an upload:


golem build -L
golem deploy -L -Y
printf 'stream me' | curl --data-binary @- http://localhost:9006/echo

The response is stream me. For a router with several routes, dispatch on the request’s method and path, and return 404 for unknown routes. The canonical request uses the full public path; framework adapters may present mount-relative paths as noted in their tabs. Routing precedence explains when a code-first endpoint or file mapping takes priority over the handler.

Working with headers

Keep repeated headers separate, especially Set-Cookie. The raw APIs use lowercase names and byte-valued fields. For example, add two cookies to a streaming response:

TypeScript

The Web adapter already preserves separate Set-Cookie fields. For byte-valued or strictly ordered fields, import withRawHeaders from @golemcloud/golem-ts-sdk and replace the handler with:


.implement((request) => withRawHeaders(new Response(request.body), [
  { name: 'set-cookie', value: new TextEncoder().encode('first=one') },
  { name: 'set-cookie', value: new TextEncoder().encode('second=two') },
]));

withRawHeaders replaces all response headers with this list, rather than adding to Response.headers. Include every header you want emitted.

For canonical methods, paths, queries, and headers without Web API normalization, replace .implement(...) with a raw handler:


.implementRaw((request) => ({
  status: 200,
  headers: [
    { name: 'set-cookie', value: new TextEncoder().encode('first=one') },
    { name: 'set-cookie', value: new TextEncoder().encode('second=two') },
  ],
  body: request.body,
}));

A Web handler can also read context.rawRequest from its second argument to inspect the original head. The body still has only one reader.

Effect TypeScript

Replace the response returned by the handler with:


return HttpRouter.withRawHeaders(HttpServerResponse.stream(request.stream), [
  { name: "set-cookie", value: new TextEncoder().encode("first=one") },
  { name: "set-cookie", value: new TextEncoder().encode("second=two") },
])

Effect’s withRawHeaders replaces normalized fields with the same names and preserves unrelated response headers. Apply it after ordinary response combinators: subsequent cloning can lose the metadata. Use HttpRouter.request for original request field occurrences that normalized Effect headers cannot represent.

Rust

Import Header from golem_rust::agentic, then replace the response’s headers:


headers: vec![
    Header { name: "set-cookie".into(), value: b"first=one".to_vec() },
    Header { name: "set-cookie".into(), value: b"second=two".to_vec() },
],

Scala

Replace Nil in the response with:


List(
  HttpHeader.ascii("set-cookie", "first=one"),
  HttpHeader.ascii("set-cookie", "second=two")
)

Use HttpHeader(name, bytes) for non-ASCII field values.

MoonBit

Import moonbitlang/core/encoding/utf8, then replace the response’s headers:


headers: [
  { name: "set-cookie", value: @utf8.encode("first=one").to_array() },
  { name: "set-cookie", value: @utf8.encode("second=two").to_array() },
],

Go

Add both fields before the handler writes the body:


w.Header().Add("Set-Cookie", "first=one")
w.Header().Add("Set-Cookie", "second=two")

Repeated fields stay separate and names are sent lowercase. For byte-valued or strictly ordered fields, register a raw handler instead of Handle (a router has one handler); it also needs the context import:


EchoRouter.HandleRaw(func(ctx context.Context, req golem.HTTPRequest) golem.HTTPResponse {
	return golem.HTTPResponse{
		Status: 200,
		Headers: []golem.HTTPHeader{
			{Name: "set-cookie", Value: []byte("first=one")},
			{Name: "set-cookie", Value: []byte("second=two")},
		},
		Body: req.Body,
	}
})

Let Golem handle transfer framing. Omit Content-Length unless you know the exact emitted byte count. Release unused input and stop producing when the output consumer closes. Do not turn stream errors into normal EOF. See the streaming contract for bodyless responses and the distinction between EOF and invocation success.

Serving static files

Create a router with file mappings and no handler. This StaticRouter serves an explicit index at /static and assets below /static/assets/:

TypeScript


import { defineHttpRouter } from '@golemcloud/golem-ts-sdk';
 
export const StaticRouter = defineHttpRouter('StaticRouter')
  .mount('/static')
  .static('/', '/public/index.html')
  .static('/assets/*', '/public/assets/$1')
  .implement();

Effect TypeScript


import { Http, HttpRouter } from "@golemcloud/effect-golem"
 
HttpRouter.define("StaticRouter", {
  mount: Http.mount("/static"),
  static: [
    { route: "/", path: "/public/index.html" },
    { route: "/assets/*", path: "/public/assets/$1" },
  ],
}).register()

Use .register() for a static-only or provider-only router; .implement(...) adds a handler. Static mappings are served by Golem, not an Effect filesystem layer.

Rust


use golem_rust::agentic::{Config, HttpRouter};
use golem_rust::http_router;
 
struct StaticRouter;
 
#[http_router(name = "StaticRouter", mount = "/static", static_files = [
    ("/", "/public/index.html"),
    ("/assets/*", "/public/assets/$1"),
])]
impl HttpRouter for StaticRouter {
    type Config = ();
    fn new(_: Config<()>) -> Self { Self }
}

Scala


import golem.BaseAgent
import golem.runtime.annotations.*
 
@httpRouter(
  typeName = "StaticRouter",
  mount = "/static",
  staticBindings = Array(
    ("/", "/public/index.html"),
    ("/assets/*", "/public/assets/$1")
  )
)
trait StaticRouter extends BaseAgent
 
@agentImplementation()
final class StaticRouterImpl extends StaticRouter

MoonBit


///|
#derive.http_router
#derive.mount("/static")
#derive.static_file("/", "/public/index.html")
#derive.static_file("/assets/*", "/public/assets/$1")
struct StaticRouter {}
 
///|
fn StaticRouter::new() -> StaticRouter { StaticRouter::{ } }

Go


var StaticRouter = golem.DefineHTTPRouter(golem.RouterSpec{
	Name:  "StaticRouter",
	Mount: "/static",
	StaticFiles: []golem.FileMapping{
		{Route: "/", Path: "/public/index.html"},
		{Route: "/assets/*", Path: "/public/assets/$1"},
	},
})

A static-only router registers no handler.

Create index.html and message.txt beside golem.yaml. Provision them as read-only files under the router’s type name, and add it to the HTTP deployment:

golem.yaml


agents:
  StaticRouter:
    files:
      - sourcePath: ./index.html
        targetPath: /public/index.html
        permissions: read-only
      - sourcePath: ./message.txt
        targetPath: /public/assets/message.txt
        permissions: read-only
 
httpApi:
  deployments:
    local:
      - domain: localhost:9006
        scheme: http
        agents:
          EchoRouter: {}
          StaticRouter: {}

Redeploy and check the index, metadata, and a byte range:


golem deploy -L -Y
curl http://localhost:9006/static
curl -I http://localhost:9006/static/assets/message.txt
curl -i -H 'Range: bytes=0-3' http://localhost:9006/static/assets/message.txt

Use a nonempty message.txt for the range example. Static responses include a strong ETag and Cache-Control: no-cache. Send the returned ETag in If-None-Match to revalidate; an unchanged asset returns 304. See the file HTTP reference for HEAD, preconditions, and range edge cases.

You can add the same mappings to a router with a handler: matching GET/HEAD files are served first, and an absent file falls through to the handler. For an override directory, declare two /assets/* mappings, first to /overrides/$1, then to /public/assets/$1. Order matters; see ordered mappings.

Expose only directories intended for HTTP access. There is no implicit index lookup, directory listing, or symlink support. Keep secrets outside exposed roots and protect private mounts with authentication.

Serving live agent files

Use a normal durable agent when files are created or modified at runtime. Bind its constructor parameters in the mount and expose only the desired files. This FileOwner creates /value.txt during initialization and overwrites it on update:

TypeScript


import { defineAgent, http, method } from '@golemcloud/golem-ts-sdk';
import * as fs from 'node:fs';
import { z } from 'zod';
 
export const FileOwner = defineAgent({
  name: 'FileOwner',
  id: { name: z.string() },
  http: http.mount('/files/{name}', {
    exposeFiles: [{ route: '/value', path: '/value.txt' }],
  }),
  methods: { update: method({ input: {}, returns: z.string() }) },
});
 
export const FileOwnerImpl = FileOwner.implement({
  init({ id }) {
    fs.writeFileSync('/value.txt', `initial:${id.name}`);
    return {};
  },
  methods: {
    update() {
      fs.writeFileSync('/value.txt', 'updated');
      return 'updated';
    },
  },
});

Effect TypeScript


import { Effect, Schema } from "effect"
import { defineAgent, Http, method } from "@golemcloud/effect-golem"
import * as fs from "node:fs"
 
export const FileOwner = defineAgent({
  name: "FileOwner",
  id: { name: Schema.String },
  http: Http.mount("/files/{name}", {
    exposeFiles: [{ route: "/value", path: "/value.txt" }],
  }),
  methods: { update: method({ input: {}, success: Schema.String }) },
})
 
FileOwner.implement({
  init: ({ name }) => Effect.sync(() => {
    fs.writeFileSync("/value.txt", `initial:${name}`)
  }),
  methods: () => ({
    update: () => Effect.sync(() => {
      fs.writeFileSync("/value.txt", "updated")
      return "updated"
    }),
  }),
})

Rust


use golem_rust::{agent_definition, agent_implementation};
 
#[agent_definition(mount = "/files/{name}", filesystem_bindings = [
    ("/value", "/value.txt"),
])]
pub trait FileOwner {
    fn new(name: String) -> Self;
    fn update(&self) -> String;
}
 
struct FileOwnerImpl;
 
#[agent_implementation]
impl FileOwner for FileOwnerImpl {
    fn new(name: String) -> Self {
        std::fs::write("/value.txt", format!("initial:{name}")).unwrap();
        Self
    }
 
    fn update(&self) -> String {
        std::fs::write("/value.txt", "updated").unwrap();
        "updated".into()
    }
}

Scala


import golem.BaseAgent
import golem.runtime.annotations.*
import scala.concurrent.Future
import scala.scalajs.js
import scala.scalajs.js.annotation.JSImport
 
@agentDefinition(
  mount = "/files/{name}",
  exposeFiles = Array(("/value", "/value.txt"))
)
trait FileOwner extends BaseAgent {
  class Id(val name: String)
  def update(): Future[String]
}
 
@agentImplementation()
final class FileOwnerImpl(name: String) extends FileOwner {
  FileOwnerFs.writeFileSync("/value.txt", s"initial:$name")
 
  def update(): Future[String] = {
    FileOwnerFs.writeFileSync("/value.txt", "updated")
    Future.successful("updated")
  }
}
 
@js.native
@JSImport("node:fs", JSImport.Namespace)
private object FileOwnerFs extends js.Object {
  def writeFileSync(path: String, text: String): Unit = js.native
}

MoonBit


///|
#derive.agent
#derive.mount("/files/{name}")
#derive.expose_files("/value", "/value.txt")
struct FileOwner {}
 
///|
async fn FileOwner::new(name : String) -> FileOwner {
  @fs.write_string(@fs.get_root_dir().unwrap(), "value.txt", "initial:" + name).unwrap()
  FileOwner::{ }
}
 
///|
pub async fn FileOwner::update(_self : Self) -> String {
  @fs.write_string(@fs.get_root_dir().unwrap(), "value.txt", "updated").unwrap()
  "updated"
}

Import golemcloud/golem_sdk/filesystem as @fs in moon.pkg.

Go


package fileowner
 
import (
	"os"
 
	"github.com/golemcloud/golem/sdks/go/golem"
)
 
type FileOwnerID struct{ Name string }
 
var FileOwner = golem.DefineAgent[FileOwnerID](golem.Spec{
	Name: "FileOwner",
	HTTP: &golem.Mount{
		Path:        "/files/{name}",
		ExposeFiles: []golem.FileMapping{{Route: "/value", Path: "/value.txt"}},
	},
})
 
var Update = FileOwner.Method[golem.Unit, string]("update")
 
type state struct{}
 
func init() {
	impl := FileOwner.Implement(func(id FileOwnerID) *state {
		if err := os.WriteFile("/value.txt", []byte("initial:"+id.Name), 0o644); err != nil {
			panic(err)
		}
		return &state{}
	})
	impl.Handle(Update, func(_ *golem.Context[state], _ golem.Unit) string {
		if err := os.WriteFile("/value.txt", []byte("updated"), 0o644); err != nil {
			panic(err)
		}
		return "updated"
	})
}

The definition and implementation share one package here for brevity; usually they live in a definition package and its impl package.

Add FileOwner: {} beside the routers in the deployment’s agents map, then:


golem deploy -L -Y
curl http://localhost:9006/files/alice/value
golem agent invoke -L 'FileOwner("alice")' update
curl http://localhost:9006/files/alice/value

The first read returns initial:alice; the second returns updated. Reads use Cache-Control: no-store with no ETag. No exported method is called to serve the file, but the first read can initialize the agent. A slow download can delay other work on that agent; see live-file lifecycle.

Calling an agent from a router

Call ordinary agents through the same clients used for agent-to-agent communication. For example, inside an async handler, update the file owner before constructing the response:

TypeScript


await FileOwner.client.get({ name: 'from-router' }).update();

Effect TypeScript

Inside the handler’s Effect.gen block:


const owner = yield* FileOwner.client.get({ name: "from-router" })
yield* owner.update({})

Keep the call in the request’s Effect scope; do not launch a detached runPromise.

Rust


FileOwnerClient::get("from-router".to_string()).update().await;

Scala

Chain the response with map after the update, using the Scala.js execution context:


import scala.scalajs.concurrent.JSExecutionContext.Implicits.queue
 
FileOwnerClient.get("from-router").update().map { _ =>
  HttpResponse(UShort(200), Nil, request.body)
}

MoonBit

Make the handler pub async fn before awaiting the generated client:


let owner = FileOwnerClient::get("from-router")
defer owner.drop()
owner.update() |> ignore

Go

Inside the handler, before writing the response:


fileowner.Update.MustCall(fileowner.FileOwner.Get(fileowner.FileOwnerID{Name: "from-router"}), golem.Unit{})

For cross-component calls, declare the dependency and generate its client as described in Calling an agent in another component. A router’s cancellation does not roll back completed agent calls. Client retries are new requests and can repeat effects; see cancellation and recovery.

Publishing OpenAPI

Add an OpenAPI provider to describe your router’s operations. For EchoRouter, describe POST / relative to its mount; Golem publishes it as POST /echo. The provider must return OpenAPI 3.1.0, not an OpenAPI 3.0 or YAML document.

TypeScript

Insert this before .implement(...); the SDK serializes the returned object:


.openApi(() => ({
  openapi: '3.1.0',
  info: { title: 'Echo API', version: '1' },
  paths: {
    '/': {
      post: {
        operationId: 'echo',
        responses: { '200': { description: 'Streamed request bytes' } },
      },
    },
  },
}))

Effect TypeScript

Add an openApi effect beside mount in the EchoRouter options:


openApi: Effect.succeed({
  openapi: "3.1.0",
  info: { title: "Echo API", version: "1" },
  paths: {
    "/": {
      post: {
        operationId: "echo",
        responses: { "200": { description: "Streamed request bytes" } },
      },
    },
  },
}),

For a schema-defined Effect HttpApi, generate the description from the same API that builds the handler. This separate CatalogRouter serves GET /catalog/items/{id}:


import { Effect, FileSystem, Layer, Path, Schema } from "effect"
import { Etag, HttpPlatform, HttpRouter as Routes } from "effect/unstable/http"
import {
  HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, OpenApi,
} from "effect/unstable/httpapi"
import { Http, HttpRouter } from "@golemcloud/effect-golem"
 
const Api = HttpApi.make("Catalog").add(
  HttpApiGroup.make("items").add(
    HttpApiEndpoint.get("getItem", "/items/:id", {
      params: Schema.Struct({ id: Schema.String }),
      success: Schema.Struct({ id: Schema.String, count: Schema.Int }),
    }),
  ),
)
const Handlers = HttpApiBuilder.group(Api, "items", (handlers) =>
  handlers.handle("getItem", ({ params }) =>
    Effect.succeed({ id: params.id, count: 7 }),
  ),
)
const Platform = Layer.mergeAll(
  Path.layer,
  Etag.layerWeak,
  FileSystem.layerNoop({}),
  HttpPlatform.layer.pipe(Layer.provide(FileSystem.layerNoop({}))),
)
 
HttpRouter.define("CatalogRouter", {
  mount: Http.mount("/catalog"),
  openApi: Effect.sync(() => OpenApi.fromApi(Api)),
}).implement(Routes.toHttpEffect(
  HttpApiBuilder.layer(Api).pipe(
    Layer.provide(Handlers),
    Layer.provide(Platform),
  ),
))

Add CatalogRouter: {} to the deployment’s agents map. The example supplies the platform services required by HttpApiBuilder; its no-op filesystem deliberately does not support filesystem operations. Golem’s static mappings do not use it. Keep generated paths mount-relative. Effect.sync builds the document when the provider effect runs rather than at module load. Golem invokes providers lazily, separately from ordinary requests.

Rust

Add this method to the HttpRouter implementation:


async fn openapi(&self) -> String {
    r#"{
        "openapi": "3.1.0",
        "info": {"title": "Echo API", "version": "1"},
        "paths": {"/": {"post": {
            "operationId": "echo",
            "responses": {"200": {"description": "Streamed request bytes"}}
        }}}
    }"#.into()
}

Scala

Add a declaration to EchoRouter:


@openApiProvider def describe(): Future[String]

Implement it in EchoRouterImpl:


def describe(): Future[String] = Future.successful(
  """{
    "openapi": "3.1.0",
    "info": {"title": "Echo API", "version": "1"},
    "paths": {"/": {"post": {
      "operationId": "echo",
      "responses": {"200": {"description": "Streamed request bytes"}}
    }}}
  }"""
)

MoonBit


///|
#derive.openapi_provider
pub fn EchoRouter::describe(
  _self : Self,
) -> String raise @http.OpenApiJsonError {
  @http.openapi_json({
    "openapi": "3.1.0",
    "info": { "title": "Echo API", "version": "1" },
    "paths": {
      "/": {
        "post": {
          "operationId": "echo",
          "responses": { "200": { "description": "Streamed request bytes" } },
        },
      },
    },
  })
}

Go


EchoRouter.OpenAPI(func(ctx context.Context) string {
	return `{
		"openapi": "3.1.0",
		"info": {"title": "Echo API", "version": "1"},
		"paths": {"/": {"post": {
			"operationId": "echo",
			"responses": {"200": {"description": "Streamed request bytes"}}
		}}}
	}`
})

Keep providers finite and deterministic. Use unique component names and operation IDs across the domain, and local references that resolve within the provider’s own document. See OpenAPI generation for the supported subset, security merging, conflicts, caching, and size limits.

After redeployment, retrieve both formats:


golem deploy -L -Y
curl http://localhost:9006/openapi.json
curl http://localhost:9006/openapi.yaml

To place them under /docs, add openapiEndpoint: /docs beside domain and scheme in the HTTP deployment. The URLs become /docs/openapi.json and /docs/openapi.yaml. Set scheme to match the public origin. Built-in local environments default to http, cloud environments to https; custom-server environments must set it explicitly.

OpenAPI endpoints are public even when a router requires authentication. Do not include secret values, private examples, or requester-specific information. Apply a separate ingress policy if the description must be private.

Protecting mounts

Configure authentication and CORS on the router mount, not its handler method. Use the same security scheme configuration as code-first endpoints. The router declarations accept these options:

TypeScript


.mount('/echo', { auth: true, cors: ['https://app.example.com'] })

Effect TypeScript

Replace the router’s mount option with:


mount: Http.mount("/echo", {
  auth: true,
  cors: ["https://app.example.com"],
}),

Rust


#[http_router(name = "EchoRouter", mount = "/echo",
    auth = true, cors = ["https://app.example.com"])]

Scala


@httpRouter(typeName = "EchoRouter", mount = "/echo",
  auth = true, cors = Array("https://app.example.com"))

MoonBit

Add these annotations to the router struct:


#derive.mount_auth(true)
#derive.mount_cors("https://app.example.com")

Go

Set these fields on the router’s RouterSpec:


var EchoRouter = golem.DefineHTTPRouter(golem.RouterSpec{
	Name:  "EchoRouter",
	Mount: "/echo",
	Auth:  true,
	CORS:  []string{"https://app.example.com"},
})

Protect each child mount explicitly: it does not inherit authentication from a parent. Test denial before checking file existence, and test browser preflight separately from plain OPTIONS. See authentication and failures for host behavior and status codes.

Configuring self-hosted deployments

See HTTP Gateway for shared storage, ingress, HTTP API and MCP ports, streaming timeouts, and resource budgets. These are platform operator settings, not application router declarations.

Troubleshooting

See Troubleshooting for routing, file serving, and OpenAPI failures.

Complete examples are available in the repository for TypeScript , Rust , Scala , MoonBit , and Effect .