Skip to content

Run Configuration

The [run] section says where pipelex run and pipelex-agent run execute a method when the command does not say.

Configuration Options

class RunExecution(StrEnum):
    LOCAL = "local"
    HOSTED = "hosted"


class RunConfig(ConfigModel):
    execution: RunExecution

Fields

  • execution: where a run executes when the command passes neither --hosted nor --local (nor --runner on the agent CLI).
    • "local" (the default) runs on this machine, with the inference backends configured in .pipelex/inference/ and your own provider keys.
    • "hosted" runs on the hosted Pipelex API, with the Pipelex API key in PIPELEX_API_KEY, at the origin in PIPELEX_BASE_URL (https://api.pipelex.com when unset). Nothing is booted locally, so no provider key or inference configuration is needed on this machine.

A flag on the command always wins: with execution = "hosted", pipelex run … --local still runs on this machine, and with "local", --hosted sends that one run to the hosted API.

pipelex init writes this setting from your answer to "Where should your runs execute?", and pipelex-agent init from the execution of its --config.

Example Configuration

[run]
execution = "hosted"

Put it in your project's .pipelex/pipelex.toml to make hosted runs the default for one project, or in ~/.pipelex/pipelex.toml for every project on the machine; the project's file wins over the global one.

The Key and the Origin

A hosted run reads its key and its origin from the environment, never from this file:

  • PIPELEX_API_KEY holds the Pipelex API key (plx_sk_…). pipelex login gets one through your browser and saves it in ~/.pipelex/.env, which Pipelex loads at startup; you can also export it in your shell.
  • PIPELEX_BASE_URL overrides the origin, for a staging plane or a self-hosted Pipelex API server. --base-url on the command overrides it in turn. Either must be scheme://host[:port], with no path such as /v1.