Quotas / Resource Limits

Golem 1.5 introduces resource quotas to control and limit resource usage across agents within an environment. Quotas can enforce rate limits, capacity limits, or concurrency limits with configurable enforcement actions.

Quotas are configured at the environment level and apply to all agents deployed in that environment.

Resource limit types

Golem supports three types of resource limits:

Type	Fields	Description
`Rate`	`value`, `period`, `max`	Rate limit per time period. Periods: `second`, `minute`, `hour`, `day`, `month`, `year`. `max` is the burst limit.
`Capacity`	`value`	Total capacity limit
`Concurrency`	`value`	Maximum concurrent usage

Enforcement actions

Each quota has an enforcement action that determines what happens when the limit is exceeded:

Action	Description
`reject`	Reject requests exceeding the limit
`throttle`	Slow down requests exceeding the limit
`terminate`	Terminate the agent when the limit is exceeded

Configuring quotas in golem.yaml

Quotas are defined per environment using resourceDefaults:


resourceDefaults:
  local:
    api-calls:
      limit:
        type: Rate
        value: 100
        period: minute
        max: 1000
      enforcementAction: reject
      unit: request
      units: requests
    storage:
      limit:
        type: Capacity
        value: 1073741824
      enforcementAction: reject
      unit: byte
      units: bytes
    connections:
      limit:
        type: Concurrency
        value: 50
      enforcementAction: throttle
      unit: connection
      units: connections

Using quotas from an agent

Configuring a resource defines its limit; your agent must reserve units before doing the work that uses it. Acquire a token using the resource’s name, reserve the amount you expect to use, then commit the actual usage. The token’s expected-use argument helps the runtime allocate credits; it does not consume units by itself.

These examples use the api-calls rate quota above to limit a greeting endpoint. Call the helper from an agent method. Each successful reservation permits one request, and the reservation helper commits one unit after preparing the response. If the resource rejects the reservation, the handler does not prepare the response.

TypeScript


import { acquireQuotaToken, withReservation } from "@golemcloud/golem-ts-sdk"
 
export function greet(name: string): string {
  const token = acquireQuotaToken("api-calls", 1n)
  const result = withReservation(token, 1n, () => ({
    used: 1n,
    value: `Hello, ${name}`,
  }))
 
  if (result.isErr()) {
    throw new Error("Request quota exceeded")
  }
  return result.unwrap()
}

Effect TypeScript


import { Effect } from "effect"
import { Quota } from "@golemcloud/effect-golem"
 
export const greet = (name: string) => Effect.gen(function* () {
  const token = yield* Quota.acquireQuotaToken("api-calls", 1n)
  return yield* Quota.withReservation(token, 1n, () =>
    Effect.succeed({ used: 1n, value: `Hello, ${name}` }),
  )
})

Return this Effect from the agent handler. Rejection remains in the error channel as FailedReservationError; the helper scopes the reservation automatically.

Rust


use golem_rust::quota::{FailedReservation, QuotaToken, with_reservation};
 
fn greet(name: &str) -> Result<String, FailedReservation> {
    let token = QuotaToken::new("api-calls", 1);
    with_reservation(&token, 1, |_reservation| {
        let response = format!("Hello, {name}");
        (1, response)
    })
}

Handle Err(FailedReservation) in the agent method instead of continuing the request.

Scala


import golem.host.QuotaApi
import scala.concurrent.Future
 
def greet(name: String): Future[Either[QuotaApi.FailedReservation, String]] = {
  val token = QuotaApi.QuotaToken("api-calls", BigInt(1))
  QuotaApi.withReservation(token, BigInt(1)) { _ =>
    Future.successful((BigInt(1), s"Hello, $name"))
  }
}

Handle Left(FailedReservation) in the agent method. Right contains the response.

MoonBit

Import golemcloud/golem_sdk/quota as @quota in moon.pkg.


fn greet(name : String) -> Result[String, @quota.FailedReservation] {
  let token = @quota.QuotaToken::new("api-calls", 1UL)
  defer token.drop()
 
  @quota.with_reservation(token, 1UL, fn(_reservation) {
    let response = "Hello, " + name
    (1UL, response)
  })
}

Handle Err(FailedReservation) in the agent method. Ok contains the response.

Go


package example
 
import "github.com/golemcloud/golem/sdks/go/golem"
 
func Greet(name string) (string, error) {
    token := golem.NewQuotaToken("api-calls", 1)
    return golem.WithReservation(token, 1, func(_ *golem.Reservation) (uint64, string) {
        response := "Hello, " + name
        return 1, response
    })
}

Handle the returned error in the agent method. A rejected reservation returns *golem.FailedReservation.

For variable usage, reserve an estimate and report the actual amount when committing: unused reserved units are returned, while usage above the reservation incurs debt. If no work consumed the resource, commit zero. For example, a rejected request must not run the protected work. With throttle, reservation waits instead of returning a rejection; with terminate, exceeding the quota terminates the agent.

Managing quotas via REST API

Resources can also be managed via the REST API — CRUD operations on /v1/envs/{environment_id}/resources. See the REST API reference for details.

How quotas work internally

Quota enforcement uses a lease-based system. Worker executor nodes acquire resource leases from the shard manager, with local credit tracking and periodic renewal. This ensures efficient enforcement without per-request coordination.