gemmapod run

Synopsis

gemmapod run <dir-or-toml> [--model <name>] [--port <n>] [--once]

Description

gemmapod run registers a pod with the running Host — and starts the Host in the foreground if none is running. The pod directory (or path to a pod.toml) is required.

By default the model comes from pod.toml. You can override it for this run via --model, or interactively pick one from the locally installed Ollama models when stdin is a terminal.

Options

Flag	Effect
`-d, --detach`	Run the Host and the pod in the background as a detached daemon process. Perfect for headless environments or keeping your terminal free.
`--model <name>`	Use this Ollama/custom model instead of the one in `pod.toml`. Skips the interactive picker entirely.
`--port <n>`	Host port to use when starting a new one. Default: try `57447..57456`. Overrides `GEMMAPOD_PORT`.
`--once`	Exit non-zero if signaling doesn't connect within 10s. Intended for CI smoke tests.

Managing Detached Daemons

When you start a pod in the background with -d / --detach, the Host will continue running as a daemon process. You can manage and terminate it using:

Stop a specific pod: gemmapod stop <pod-id>
Shut down the host completely (stops all pods): gemmapod stop (with no arguments) or gemmapod kill.

Model selection precedence

To make running pods simpler, if a model is explicitly specified in your pod.toml file, gemmapod run will automatically bypass the interactive prompts. The precedence logic is as follows:

--model <name> — explicit CLI override (no prompt)
pod.toml's configured model (no prompt)
Interactive picker (TTY only, prompted when no model is defined anywhere and Ollama is reachable)
Fallback: gemma4:e4b (default when no model is found or selected)

The chosen model is logged as pod started — model: <name> so you can confirm what's actually in use.

Examples

# Use the model configured in pod.toml (starts immediately with no prompt if present)
gemmapod run ./examples/raj-card

# Run the host and pod completely in the background as a daemon
gemmapod run ./examples/raj-card --detach

# Stop/kill the background host once done
gemmapod kill

# Pin a model explicitly (good for scripts)
gemmapod run ./examples/raj-card --model llama3:8b