Run a briq
briq_runStart a service, or a sandbox to run code in, for this agent on a cloud microVM. Prefer recipe (see briq_catalog: postgres, redis, sandbox, …) which returns ready-to-use connection outputs; or pass image for any public OCI image. Blocks until the service is ready, for up to two minutes (or wait: false): with a healthcheck, ready means it passed; without one, only that the process started, and if it later exits briq_status shows the exit and briq_logs why. A briq still creating after the wait is on its way: briq_status says when it runs, briq_logs shows each step (download, install, build) as it goes. With recipe, the same fields change the service it makes, as a GitHub Actions service: image (another tag, or pgvector/pgvector:pg16), env, cmd, size, volume ({ gb }), files. A language recipe (python, node, …) also takes your code as files, or a repo as checkout (the briq downloads it itself), with steps and cmd. briq_catalog with the name lists what each takes and its defaults. A briq goes to sleep after sleep without use (1 hour by default on briq.cloud; your calls and visits to its URL are use) and the next call or visit wakes it: a sleeping briq keeps its disk (files written anywhere survive) and costs nothing, so it is there tomorrow and next month. Only briq_destroy removes it. One stopped by briq_stop or its own exit needs briq_start. Put data you cannot afford to lose on a volume. Still briq_destroy what you are finished with.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cmd | No | The command: a string run with sh -c ("npm start"), or the argv. A language recipe's start command; with checkout, pass it | |
| env | No | Env vars; with `recipe`, added to its own or replacing one of its values. { secret: "NAME" } has briq generate a secret and return it in outputs; { secret: "NAME", value: "…" } stores a credential you already have (a password, an API key), not printed back. Secrets are stored encrypted and never shown in status. Never put a credential in a plain value. A credential only the boot needs (a clone of a private repo, a private registry) goes with scope: "boot": a variable of the recipe's steps, then gone, never in the environment briq_exec or the code runs in; for a language recipe or the sandbox. A credential the code calls an API with goes with hosts: { secret: "NAME", value: "…", hosts: ["api.stripe.com"] } (locations: ["header"] unless you add "body"): the briq gets a placeholder, and the team's credential gateway puts the real value into its requests to those hosts only. The code never holds it; prefer this to a plain { secret, value } whenever the value is an API credential. A team secret (briq_secrets lists them; the person adds them on the dashboard) goes as { secret: "NAME", scope: "team" } with no value: the same placeholder and gateway, the value held by the team. `{{briq:NAME}}` in a plain value becomes the address of the briq NAME in the stack (not allowed in a secret value). `{{self:host}}` in a plain value becomes the hostname of the URL of this briq when it is published as it runs (`expose`), for an app that needs its public address at boot; `localhost` without one. | |
| name | No | DNS-safe name within the stack (default: recipe briq name) | |
| size | No | nano | small | medium | large; small by default (a recipe has its own default, and may allow fewer). The Hobby plan runs nano, small, medium; large once the team has a card on file. | |
| wait | No | Wait until ready (default true) | |
| files | No | With a language recipe, your app's files: relative paths go under /app. Otherwise files written into the briq before its command starts, absolute path → content: your app's sources, a config file. Text as it is, or { base64 } for binary; at most 64 files and 256 KB in all. Written again whenever the process starts over, so the spec stays their source of truth. E.g. { "/app/server.py": "…" } with cmd ["python", "/app/server.py"]. | |
| image | No | Any public OCI image, e.g. "redis:7-alpine". With `recipe`: another tag ("postgres:17") or a compatible image ("pgvector/pgvector:pg16") | |
| ports | No | The ports the image listens on. A language recipe: the port the app listens on, [8080] by default | |
| sleep | No | When it goes to sleep: after this long without use, as a string: "30m", "3h", "7d", or "never" (always on, Pro plan and above). Never a number. Use means your calls on it (exec, files, logs, expose), on any briq of its stack, and visits to its stack's URLs. A sleeping briq keeps its disk, costs nothing, and the next call or visit wakes it. A command started with briq_exec async is use while it runs. Other work briq cannot see (a worker, a bot that only makes outgoing connections) needs a window longer than that work, or "never". With a recipe, every briq it makes gets the same. Default set by the service: "1h" on briq.cloud. | |
| stack | No | Stack (namespace with private DNS) to run in; default "default" | |
| steps | No | A language recipe: shell commands run before the app starts, as GitHub Actions steps: [{ run: "npm ci" }, { run: "npm run build" }]. Default: the language's install. With checkout, they run again when the commit changed | |
| expose | No | Publish it as it is created, with its HTTPS URL as URL in outputs: "private" for a URL only whoever has it can open (it carries a secret, checked before any request reaches the briq), "public" for anyone. A recipe publishes its front door (only recipes with something to open in a browser have one; a database does not); an image publishes its port, so pass exactly one in `ports` (with several, run without `expose`, then briq_expose the one you want, which restarts the machine). Nothing restarts, and the URL serves once the briq runs. Off by default: publishing is a decision. | |
| recipe | No | Recipe name from briq_catalog, e.g. "postgres" | |
| routes | No | The nginx recipe: path prefix → "briq:port", e.g. { "/api/": "backend:8080", "/": "frontend:8080" } | |
| volume | No | A durable disk mounted at `mount`: for data that must not be lost (a database), and what a fork copies. Empty at first, and it hides whatever the image had at that path. A recipe that keeps data has one: { gb } sets its size, small by default, so ask for what the data needs ({ gb: 20 }) | |
| checkout | No | A language or static recipe: your code from a repo, as actions/checkout. The briq downloads it at each start onto its volume | |
| entrypoint | No | Image only. argv replacing the image's entrypoint | |
| healthcheck | No | Image only. A command that succeeds once the service serves, e.g. ["wget", "-qO-", "127.0.0.1:8080"]. Use 127.0.0.1, not localhost: inside a briq, localhost is ::1, which a server listening on IPv4 only refuses. briq_run waits for it. `timeoutMs` (default 60000) is per attempt: a process still up when it runs out is waited for again, up to three times, before the create fails. |