Skip to content
Back to skills

Binaries

ASecurity

Non-server long-running binaries — when to use `forge scaffold binary` vs `forge scaffold worker` vs `forge scaffold service`, plus the lifecycle and deploy story.

  • 10 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added November 13, 2026
developmentgobashnodeexpresskubernetestestinggitapifrontend

Works with

  • cli
  • api

Security analysis

A100/100

Pro scans all 3 files and shows the line behind each finding

Scanned November 13, 2026

npx -y skills add reliant-labs/forge --skill binaries --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Binaries?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Binaries
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/reliant-labs-binaries/badge)](https://www.skillsdirectory.com/skills/reliant-labs-binaries)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: binaries
description: Non-server long-running binaries — when to use `forge scaffold binary` vs `forge scaffold worker` vs `forge scaffold service`, plus the lifecycle and deploy story.
---

# Binaries

A "binary" is a non-server long-running process that ships its own Deployment. Examples: a reverse proxy, a workspace gateway, an off-service NATS consumer, an authentication sidecar. Forge scaffolds binaries via `forge scaffold binary <name>`.

A binary is its own thin `package main` cobra root under `cmd/<package>/main.go` (devspace idiom — each binary gets its own `cmd/<bin>/` tree), delegating to a small owned composition root in `internal/<package>/`. It does NOT share the server's `internal/app/compose.go` `NewComponents` — that bag constructs the server's handlers/workers; a standalone binary owns its own narrow `Deps`/`Service`/`New` contract. The binary owns *which* runtime loop it composes; it reuses the same typed `internal/config` flag set as the server.

Binaries sit alongside services, workers, and operators as the four long-running shapes forge knows how to scaffold. The decision tree below shows when to pick which.

## When to use a binary vs a worker vs a service

| Shape | What it is | Picks this when |
|---|---|---|
| **service** | Connect-RPC server mounted via its `MountX` method onto the server's `serverkit.Server`. | You're exposing typed RPCs to clients (frontend, other services, daemons). |
| **worker** | In-process goroutine supervised by serverkit. Constructed in the same `internal/app/compose.go` `NewComponents` as services; `WorkerList(components)` adapts it and the cmd serve path starts it when the server boots. | You need background work that *belongs to* the server's lifecycle (queue consumer, periodic sweep, cron). One process, no separate Deployment. |
| **binary** | Standalone process with its **own** `cmd/<bin>/main.go` cobra root and its own owned `Deps`/`Service`/`New` composition root in `internal/<package>/`, with its own Deployment. | You need a process with its own deploy lifecycle: a reverse proxy, a workspace gateway, a webhook receiver isolated from the API server. Also covers **one-off operational binaries** — backfills, data migrations, ad-hoc scripts. |
| **operator** | Kubernetes controller-runtime manager with CRD reconcilers. | You're reconciling Kubernetes resources (CRDs). Operators are a specialised flavour of binary; pick this only when CRDs are involved. |

The litmus test for binary vs worker is: **does this need its own Deployment, OR is it a run-once operational tool?** If either — it's a binary. If neither — it's a worker.

Resist the temptation to hand-roll a `cmd/<name>/main.go` from scratch. `forge scaffold binary` scaffolds the `cmd/<package>/main.go` entry point AND the `internal/<package>/` composition root for you, registers it in `forge.yaml` under `binaries:`, and gives it an image tag — so it stays visible to `forge generate`/`build`/`deploy`. A from-scratch `main()` that doesn't go through `forge scaffold binary` re-implements config/flag loading and shutdown plumbing the scaffold already solves, and is invisible to deploy.

## The cmd/ surface

The server binary's cobra surface is real, owned Go — one symbol per command you can jump to — not a string-projection of a registry.

- **`cmd/<server>/main.go`** (yours) — the server cobra root with the full command tree.
- The server's `serve` command applies a typed `(*app.Components).Mount<Svc>` method expression (or `MountAll`) onto a `serverkit.Server`; named subsets compose the typed `app.MountByName` function values.
- **`cmd/<binary>/main.go`** (yours, from `forge scaffold binary`) — a separate thin `package main` cobra root for each standalone binary, NOT a subcommand under the server root. It loads config, constructs the binary's `Service` via `internal/<package>.New(Deps{...})`, and calls `svc.Run(ctx)`.

There is **no** `cmd/services_gen.go` string-projection, **no** `RegisteredServices` constructor table, and **no** `userCommands()` catch-all. A data-only `Inventory` registry survives for introspection (`forge project map`/`audit`, CLI listing) — names there are for display, never a construction lookup key.

## Adding a binary

```bash
forge scaffold binary workspace-proxy
forge scaffold binary auth-sidecar
```

This creates:

```
cmd/<package>/main.go                # thin package main cobra root — load config, New(Deps), svc.Run(ctx)
internal/<package>/contract.go       # Deps + Service interface + New(Deps) (Service, error) + validateDeps
internal/<package>/<package>.go      # Runner struct + Run(ctx) runtime body
internal/<package>/<package>_test.go # construction + lifecycle tests
```

Nothing is written to `forge.yaml` — it is global-only. The binary is
discovered from its `cmd/<package>/main.go`, and that discovery is what makes
deploy emit a Deployment for it.

The hyphenated CLI name (e.g. `workspace-proxy`) becomes the Go package name with hyphens replaced by underscores (`workspace_proxy`), so `cmd/workspace_proxy/main.go` and `internal/workspace_proxy/` line up with `package workspace_proxy`.

## Binary composition root

A binary owns its **own small typed composition root** in `internal/<package>/contract.go`: a `Deps` struct of interface-typed fields **resolved by type, never by string name**, gated by `validateDeps()` at construction, and a `New(Deps) (Service, error)` constructor. The thin `cmd/<package>/main.go` builds the `Deps` (logger, typed config, plus any DB/NATS/k8s/HTTP dependencies) and hands them to `New`. This is the binary's analogue of the server's `internal/app/compose.go` `NewComponents` — but local to the binary, not the server's `Components` bag.

```go
// internal/workspace_proxy/contract.go
type Deps struct {
    Logger *slog.Logger
    Config *config.Config
    // Add binary-specific deps below, each as a narrow interface:
    Enforcement Enforcer    // interface seam: real in-proc here, a Connect client if split out later
    Users       UserSource  // a local interface, not the concrete type
}

func New(deps Deps) (Service, error) {
    if err := deps.validateDeps(); err != nil {
        return nil, err
    }
    return &Runner{deps: deps}, nil
}
```

Notes:
- **In-process is the default.** A cross-binary dep is the one-line swap: fill its interface with a Connect client instead of the in-proc instance; the consumer is untouched.
- **Per-binary singletons are natural.** A dep that must be one instance within *each* process is constructed once in `cmd/<package>/main.go` and passed into `Deps`.
- **Two-phase wiring is first-class.** Construct, then inject via setters (`x.WithY(z)`) for near-diamonds — plain method calls after both ends exist, in `main.go`.
- **Scalars are config, not dependencies.** A `string`/`int`/`bool`/`Duration` lives in a `<Component>Config` proto block consumed as one typed `Cfg *config.<Component>Config` Deps field — never a naked scalar Deps field.

## Lifecycle — Run blocks until ctx is cancelled

The generated `cmd/<package>/main.go` wires `SIGINT`/`SIGTERM` into a context via `signal.NotifyContext`, constructs the binary's `Service` via `New(Deps{...})`, and calls `svc.Run(ctx)`. The binary's `Runner.Run(ctx)` blocks until ctx is cancelled, then returns cleanly. Graceful shutdown is the binary's own responsibility *inside* `Run` (close servers, drain consumers) — the cobra adapter just propagates cancellation.

```go
// internal/<package>/contract.go
type Service interface {
    Run(ctx context.Context) error // blocks until ctx cancel or fatal error
    Name() string
}
```

For a binary that is purely an HTTP server (proxy, gateway), `Run` starts `srv.ListenAndServe()` in a goroutine and calls `srv.Shutdown` on `<-ctx.Done()`. For a loop (NATS consumer, ticker), `Run` selects on `ctx.Done()` directly. The scaffold's placeholder `Run` body blocks on `<-ctx.Done()` so a freshly added binary compiles and exits cleanly on Ctrl-C.

### Interceptor ordering

If your binary mounts Connect handlers, the interceptor chain (otel-outermost → rate-limit → auth → audit) is composed **explicitly** in the handler assembly inside `Run` — never implied by registration order. Preserve it.

### One-off scripts (backfills, migrations, ad-hoc tools)

A one-off binary's work-loop is allowed to finish: do the work, log the summary, return `nil`. Declare its workload `kind = "job"` instead of `service`/`worker` in `deploy/kcl/workloads.k`, so no runtime restarts it. Same scaffold, same composition root; the only difference is the `kind`.

## Config — the cmdkit paved path

Binaries do **not** hand-roll `os.Getenv`, ad-hoc `slog.Logger`s, hardcoded timeouts, or hand-rolled shutdown. The single typed `internal/config` — generated from the proto config blocks (`AppConfig` + `<Component>Config` with `(forge.v1.config)` annotations) — serves server, CLI, and standalone-binary kinds alike via the **cmdkit paved path**: DB open, logger, flag/env binding, and report envelope, with the logger injected through `observe.WithLogger`/`FromContext`.

Per-env config (logging, env vars) lives directly in `deploy/kcl/<env>/` — not in a redundant second YAML. `forge.yaml` stays strictly top-level (project identity, features, deploy provider, the `binaries:` list).

### How one field resolves

Later layers win: the proto `default_value`, then the config file (`--config`), then the field's `env_var`, then its flag when given on this invocation. A malformed value is a startup error, never a silent fallback to the default.

**An env var set to `""` is unset, for every field type.** `TEMPORAL_HOST=` keeps the file's or the default's value; it does not load `""`. A deploy template rendered from a missing key, compose's `X: ${X}` and `export X=` all mean "not configured". An explicitly empty value comes from a flag (`--pprof-addr=` switches pprof off; `--allowed-registries=` clears a defaulted list). A required field whose variable is set but empty fails with an error that says so.

**Aliases replace a hand-written fallback chain.** When a value has setters you do not control — another tool's convention, or an old name a deployment elsewhere still exports — list the extra names instead of keeping `if v := os.Getenv(A); v != "" { … } else if …`:

```protobuf
string url = 1 [(forge.v1.config) = {
  env_var: "RELIANT_CONTROL_PLANE_URL"
  env_var_aliases: [{name: "CONTROL_PLANE_API_URL"}, {name: "CONTROL_PLANE_BASE_URL", deprecated: true}]
}];
string environment = 2 [(forge.v1.config) = {env_var: "RELIANT_ENV", env_var_aliases: [{name: "NODE_ENV"}]}];
```

- The loader reads `env_var`, then each alias in order; the first one set (non-empty) wins. All of them sit in the env layer: below the flag, above the file and the default. A malformed value in the winning name is an error; it never falls through to the next name.
- `deprecated: true` prints one stderr line at load whenever that alias is set, naming `env_var`. Leave it off for a permanent alias like `NODE_ENV`, which is read silently.
- forge's own setters use `env_var` alone. The KCL env map, the secret store key and `--help` name it (help also lists permanent aliases as `[env: RELIANT_ENV, NODE_ENV]`), so every manifest forge renders converges on one name.
- `generate` refuses an alias that repeats a name another field of the same process reads, an alias without an `env_var`, and aliases on a frontend config field.
- The typed-config guardrail flags `os.Getenv` whatever the name, so a raw read of an alias is a finding exactly like a read of the primary.

### Per-binary config (no project-global AppConfig)

A project can move config OWNERSHIP off a single shared `AppConfig` onto each binary's own message — annotate a config message with `option (forge.v1.binary_config) = {binary: "<cmd/name>"};` (see `forge skill load db` / the config proto's own header for the full mechanics). Doing this for EVERY config message — deleting `AppConfig` entirely — is a legitimate end state, not a half-migration: forge still emits a complete Go/KCL/env surface per binary.

This does not change how a `forge scaffold binary` composition root or a `forge scaffold service`/`worker` Deps struct is written. `config.Config` keeps meaning exactly what it always meant — "this component's config type" — regardless of whether the project has a root `AppConfig` or has moved entirely to per-binary configs:

- **With a root `AppConfig`** (the common case): `config.Config` aliases it directly.
- **All-binary-annotated, no root `AppConfig`**: `config.Config` aliases the config message bound to the project's PRIMARY binary — the one with the full `cmd/<bin>/cmd` command tree (`server`, `db migrate`, etc.), i.e. the binary a fresh `forge project new` scaffolds. Every service, worker, and internal package mounted into THAT binary's composition graph (`internal/app/compose.go`) keeps reading `Config *config.Config` unchanged.
- **A secondary binary** (`forge scaffold binary <name>`) that wants its OWN config type, distinct from the primary binary's, reads it through the per-binary alias forge always generates alongside `Config` — `config.<MessageName>` / `config.Load<MessageName>(cmd)` — and takes that type on `Deps.Config` instead of `*config.Config`. A freshly scaffolded secondary binary's `Deps.Config *config.Config` compiles either way (it is reading the primary binary's config, same as any other component) until you point it at its own message.

The primary binary MUST have a ROOT config message (no `command`) bound to it once the project goes all-binary — `forge generate` refuses, naming the primary binary, if none is. There is nothing else for `config.Config` to mean once the root `AppConfig` is gone.

`binary` must name a `cmd/<name>` directory, and one message per binary: `forge generate` refuses anything else, with the `proto/<file>:<line>` of each offending annotation. A binary's root config registers EVERY leaf (composed blocks included) as a persistent flag: `config.Register<Msg>Flags(root)` on the binary's root command, `config.Load<Msg>(cmd)` from any of its commands.

### One binary, several processes: `command`

When a binary's subcommands run as SEPARATE PROCESSES (`app server api`, `app server worker`, `app daemon`) — one image, one Deployment per role — scope a config to a subcommand instead of splitting the binary:

```protobuf
message AppConfig {                       // the binary-wide surface: every process
  option (forge.v1.binary_config) = {binary: "app"};
  LogConfig log = 1;
}
message ApiServerConfig {                 // only the `app server api` process
  option (forge.v1.binary_config) = {binary: "app", command: ["server", "api"]};
  int32 grpc_port = 1 [(forge.v1.config) = {env_var: "GRPC_PORT", flag: "grpc-port", default_value: "9090"}];
  string auth_api_key = 2 [(forge.v1.config) = {env_var: "AUTH_API_KEY", sensitive: true}];
}
```

The binding is keyed on `(binary, command)`. A process loads its binary's root config, every SUBTREE config over its path (below), and the ONE config declared for its exact command path:

```go
config.RegisterAppConfigFlags(root)            // persistent: every subcommand inherits
config.RegisterApiServerConfigFlags(apiCmd)    // local: `app server api --help` lists exactly these
// in apiCmd's RunE:
base, err := config.LoadAppConfig(cmd)
api, err := config.LoadApiServerConfig(cmd)    // refuses any command but `server api`
```

- `generate` checks each `command` element is one command name. It cannot check the path EXISTS — a cobra tree is built at runtime — so `Load<Msg>` checks it exactly against the real tree and errors, naming both paths, when called from another command.
- A root config and a command config of one binary may not declare the same env var or flag (one process would read it twice), nor the same top-level field name (one config file serves the process: `binaries/config-files`); `generate` refuses the pair. Compose a shared block onto the root config, not onto each command config, when EVERY process reads it; a subtree config (below) when several commands do.
- KCL: every config keeps its own `<msg>EnvMap`, and a binary with command configs also gets `config_gen.<bin>ProcessEnvMap(cfgs, argv, config_secrets)`, which projects one workload's env from its own `command + args` — root config plus the matching command config, longest declared path first, `config_secrets` routed to whichever config declares each name. config.k scaffolds the bundle as `<bin>_process`:

  ```kcl
  env = config_gen.appProcessEnvMap(appcfg.app_process, (w.command or []) + (w.args or []), w.config_secrets) | w.env
  ```

  The subcommand path is read after the argv token naming the binary (`app`, `./cmd/app`, `/app/app`), or from all of argv when none does (`args = ["server", "api"]` on the project image), and ends at the first flag.

### Several commands, not every process: `subtrees`

A setting many commands read but the server roles must not carry (the CLI's server URL and token; a guard policy `daemon start` and `open` share) is a SUBTREE config, `subtrees: [{path: ["daemon"]}, {path: ["open"]}]`: loaded at or below each path, by no other process. Rules, registration and the KCL projection: `binaries/subtrees`.

### Config files

Every config also loads from a YAML or JSON file: `--config <path>`, or the binary's own `<BINARY>_CONFIG` (`RELIANT_CONFIG` for `cmd/reliant`; the project-global `AppConfig` reads `<PROJECT>_CONFIG`). Precedence is defaults < file < env < flags. One file serves one process, flat across its root and command config. The file's shape, the variable's override and its failure modes: `binaries/config-files`.

Splitting into separate binaries instead (`cmd/app-server` + `cmd/app`) is right when the roles share nothing. When they share a binary — one image, a monolith mode that runs every role in one process, a CLI on the same root — `command` keeps one binary and still gives each process only its own config and credentials.

## Errors

If your binary mounts handlers, every handler maps errors with `svcerr.Wrap(err)` from `forge/pkg/svcerr` — never a raw `connect.NewError(connect.CodeInternal, err)` (it flattens NotFound/InvalidArgument/PermissionDenied) and never a hand-rolled per-binary `mapServiceError`/`toConnectError`. Domain failures use `svcerr` sentinels (`svcerr.NotFound("workspace")`). Skip per-RPC `if deps.X == nil` checks for non-optional deps — `validateDeps()` gates them at construction.

## Deploy

A secondary binary is its own program: `forge scaffold binary <name>`
declares it in `deploy/kcl/workloads.k` with its OWN build, as a `tool`
(built into the project image, never scheduled) and binds it
`_build_only(wl.<name>)` in every env:

```kcl
# deploy/kcl/workloads.k
workspace_proxy = fw.Workload {
    name = "workspace-proxy"
    kind = "tool"
    build = forge.GoBuild {cmd = "./cmd/workspace_proxy", output_name = "workspace_proxy"}
}
```

To RUN it as a long-lived process, make it a `service` (or `worker`) and
name its binary as the `command` — the project image's ENTRYPOINT is the
primary binary, and a workload's `command` replaces it:

```kcl
workspace_proxy = fw.Workload {
    name = "workspace-proxy"
    kind = "service"
    build = forge.GoBuild {cmd = "./cmd/workspace_proxy", output_name = "workspace_proxy"}
    command = ["/app/workspace_proxy"]
    ports = [fw.Port {name = "http", port = 8080, expose = True}]
}
```

then bind it per env like any workload — `_on_cluster(wl.workspace_proxy)`,
`_on_host(wl.workspace_proxy)` (the host runtime runs `command` verbatim), or
`_hosted(...)`. Replicas, resources and env are refinements on the binding
(`_on_cluster(wl.workspace_proxy) | {replicas = 2}`), never a second copy of
the declaration.

A subcommand of the PRIMARY binary needs no build of its own: `args =
["<subcommand>"]` with the project's GoBuild selects it on every runtime.

## Common patterns

A binary's body is `Runner.Run(ctx)` — the placeholder blocks on `<-ctx.Done()`; you replace it with one of these shapes. `Run` owns its own listen/shutdown or loop, propagating cancellation from the ctx the cobra adapter wires SIGINT/SIGTERM into.

### Reverse proxy / gateway

`Run` starts the proxy `http.Server` in a goroutine and calls `srv.Shutdown` on `<-ctx.Done()`. You write the handler and the listen/shutdown dance against the cancelled ctx.

### Off-service NATS consumer

`Run` subscribes, then blocks until ctx cancellation, unsubscribing on the way out:

```go
func (r *Runner) Run(ctx context.Context) error {
    sub, err := r.deps.NATS.Subscribe("events.>", r.handle)
    if err != nil { return err }
    defer sub.Unsubscribe()
    <-ctx.Done()
    return nil
}
```

### Periodic ticker

`Run` selects on a `time.Ticker` and `ctx.Done()` — a plain loop in the binary's own `Run`, no external supervisor.

## Testing

`internal/<binary>/<binary>_test.go` ships:

1. **Construction test** — calls `New(Deps{...})` with every dep mocked through its generated `mock_gen.go` mock, and asserts `validateDeps` accepts a complete `Deps` and rejects missing required fields. Because every dep is an interface filled in one place, "spin up this binary with X mocked" is a few-line, one-call operation against `New`.
2. **Lifecycle test** — start `Run(ctx)` in a goroutine, cancel ctx, assert it returns cleanly; keep it so shutdown regressions stay caught.

Binaries that don't mount RPCs don't use `tdd.RunRPCCases`; ones that do mount handlers test those the same way services do.

## Lint

`forge lint` / `forge project map` check that:

- Every `binaries:` entry has a matching `cmd/<package>/main.go` and `internal/<package>/contract.go`.
- The `Path` in forge.yaml matches the scaffolded `cmd/<package>/main.go`.
- Names don't collide with reserved cobra subcommands (`server`, `version`, `db`).
- The composition graph is acyclic and has no narrow-interface silent drops or unresolved non-optional deps.

Run `forge generate` after editing `binaries:` to keep the scaffold and config in lockstep.

## See also

- `forge skill load services` — Connect-RPC service shape, `MountX`, when to pick this instead.
- `forge skill load workers` — in-process workers supervised by serverkit.
- `forge skill load deploy` — KCL deploy story, including how binaries become Deployments.
- `forge skill load architecture` — the server's explicit composition (`internal/app/providers.go` `Infra`/`OpenInfra` + `internal/app/compose.go` `NewComponents`), serverkit lifecycle, the interface seam — the wiring the server participates in; a standalone binary owns its own narrow `Deps`/`Service`/`New` analogue.

Files in this skill

  • SKILL.md22.2 KB
  • config-files/SKILL.md3.6 KB
  • subtrees/SKILL.md4.6 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in development →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.