# Run an app locally

## Goal

Execute a PlayMolecule app on the current machine, using Docker or Apptainer as the container runtime.

## Minimal example

```python
from playmolecule.apps import proteinprepare

ed = proteinprepare(outdir="out", pdbid="3ptb")
ed.run()
```

When `ed.run()` returns, the job is done. `ed.status` is `JobStatus.COMPLETED` (or `JobStatus.ERROR`).

## What `run()` does

1. Asks the active execution backend (local, by default) to run the app.
2. The local backend invokes `docker run` or `apptainer run` against the cached image, bind-mounting the run directory into the container.
3. Stdout/stderr stream to your terminal.
4. The function returns when the container exits.

For the conceptual picture, see [Architecture](../explanation/architecture.md).

## Quiet down logs

```python
ed.run(verbose=False)
```

`verbose=False` suppresses live output but still writes everything to the job's log file at `outdir/run_<id>.log` (a sibling of the run directory, not inside it).

## Set the container runtime

Docker is the default. Switch to Apptainer for HPC nodes that can't run Docker:

```bash
export PM_RUNTIME=apptainer
```

See [Switch between Docker and Apptainer](switch-between-docker-and-apptainer.md) for the full picture.

## Run the same `ed` somewhere else

`ed.run(...)` re-uses the same prepared inputs. If `run()` errored once, you can fix the issue (e.g., adjust a file in `outdir/`) and call `run()` again without rebuilding the job.

To submit the same `ed` to SLURM instead:

```python
ed.run(queue="slurm", partition="normalCPU", ncpu=1, ngpu=0)
```

See [Run an app on SLURM](run-an-app-on-slurm.md).

## One-shot syntax

If you don't need the `ed` handle:

```python
proteinprepare(outdir="out", pdbid="3ptb").run()
```

Drop the binding when running interactively. Keep it whenever you need to check status, batch jobs, or inspect inputs.

## Gotchas

- The first time you call an app, the container image must be pulled — that's a one-time multi-hundred-MB download. If the pull fails, check `docker login` / `gcloud auth configure-docker` for the registry (see [Install apps for a cluster](install-apps-for-a-cluster.md)).
- `outdir` must be writable by the user running the Python script. Docker's UID-mapping quirks are out of scope here, but if you see permission errors in the output files, run `docker info` and check your storage driver.
- Setting `PM_BLOCKING=1` makes the call **block until the job finishes** even when running through the HTTP backend — useful for scripts, never useful for interactive work.

## See also

- {py:meth}`~playmolecule.ExecutableDirectory.run`
- [Run an app on SLURM](run-an-app-on-slurm.md)
- [Check job status](check-job-status.md)
- [Architecture](../explanation/architecture.md)