# Local experiments

Serve declarative experiments, Python objects, and Python factories locally.

[View canonical HTML](https://pllm.run/cli/reference/gateway/local-experiments/)

Document ID: `pllm.docs.reference.cli.gateway.local-experiments`  
Release: `0.1.0`

`pllm gateway --local` resolves one typed `Experiment`, starts its required roles as child processes, and exposes the trusted loopback Responses and Chat Completions API. The gateway does not replace the experiment's pipeline or profile.

## Target forms

Use `file.py:object` for a Python file, `module:object` for an importable module, or `.json`/`.yaml` for declarative configuration. Python targets are imported code and therefore require `--trust-python` in unattended commands. Add `--factory` only when the selected object is a zero-argument callable returning an `Experiment`. Raw `python file.py` execution is intentionally unsupported.

The repository's [composition example](https://github.com/blairhudson/pllm/blob/main/examples/composition.py) exposes both `experiment` and `build_experiment`; [`examples/pllm.yaml`](https://github.com/blairhudson/pllm/blob/main/examples/pllm.yaml) provides the equivalent declarative form.

## Examples

### Serve a Python experiment locally

Import the checked-in `Experiment` object and start both provider roles behind the trusted loopback gateway.

```bash
pllm gateway --local --experiment examples/composition.py:experiment --trust-python
```

### Build an experiment with a Python factory

Use `--factory` when the selected Python object is a zero-argument callable rather than an existing `Experiment`.

```bash
pllm gateway --local --experiment examples/composition.py:build_experiment --factory --trust-python
```

### Serve a declarative experiment

JSON and YAML targets are data, so they do not require `--trust-python`.

```bash
pllm gateway --local --experiment examples/pllm.yaml
```

## Application endpoint

Applications connect to `http://127.0.0.1:8080/v1` by default. Inference and preparation children remain provider-role services, not application-facing OpenAI-compatible endpoints. Stop the gateway to shut down its local role topology.