Configuration reference

Task project

A task project must contain package.json, the selected Manager’s exact lockfile, and helmr.config.ts. .helmrignore is optional source-selection authority and is generated by helmr init. package.json must set "type": "module", select an exact Node release through devEngines.runtime, and select an exact npm, pnpm, or Bun release through packageManager.

import { defineConfig } from "@helmr/sdk"

export default defineConfig({
  dirs: ["tasks"],
  ignorePatterns: ["**/*.test.ts"],
})

dirs is required and must be non-empty. It selects declaration discovery from the submitted project source. ignorePatterns affects discovery only. .helmrignore is the only source-selection file; .gitignore is not read. The root .git entry is always excluded. Retained root node_modules and helmr paths are rejected. Retained .env and .env.* basenames are rejected except names ending in .example, .sample, or .template.

Runtime configuration

Surface	Fields
`task`	`id`, `payload`, `queue`, `maxDuration`, `ttl`, `retry`, `run`
`actor`	`id`, `idleTimeout`, `queue`, `maxDuration`, `ttl`, `retry`, `run`
`sandbox`	`sandbox({ id }).image(img).resources({ cpu, memory })`
`image`	`from`, `run`, `copy`, `copyFrom`, `workdir`, `env`, `user`
`source`	`file(path)`, `directory(path)`

SDK Workspace creation uses inert Secret addresses rather than raw names:

secrets: [
  { secret: secrets.fromName("TOKEN"), env: "TOKEN" },
  {
    secret: secrets.fromName("config-json"),
    file: "/run/secrets/config.json",
  },
]

The corresponding REST request body uses the canonical wire form:

secrets: [
  { name: "TOKEN", env: "TOKEN" },
  {
    name: "config-json",
    file: "/run/secrets/config.json",
  },
]

Secret names must match /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.