14 KiB
Installation
./install.sh sets up Docker server + ntfy by default. Use --native for
native binaries only. Native installation requires Go; Docker setup requires Docker
Compose and Python 3, and includes OpenCode in the persistent server container.
git clone https://git.a-wan.net/alan/pipelines.git
cd pipelines
./install.sh
# Explicit choices:
./install.sh --docker # complete server/ntfy setup, including provider login
./install.sh --native # binaries/skill only; honors GOBIN/GOPATH
Native mode installs pipelines, pipelines-server, and pipelines-tui. Go chooses the
destination using GOBIN, or the usual GOPATH/bin default. Put that directory
on PATH. No privileged operations, private dependency installation, login prompts,
Docker provisioning, service registration, or background processes are involved.
Re-running installation updates the binaries and bundled OpenCode skill without
changing databases, login, or OpenCode configuration files.
Docker mode detects the computer's LAN IPv4 address and timezone automatically,
configures http://LAN_IP:8090, and binds both Docker services to 0.0.0.0 without asking
for networking settings (timezone falls back to UTC). On reinstall it updates only
the bind settings to 0.0.0.0, refreshes the detected host LAN IP for Status,
and retains existing URLs/timezone/ports/credentials. It bootstraps
the publishing/phone accounts and publishing token, builds the server, installs
the skill inside the container, and opens container OpenCode provider login
on first setup. Choose any supported provider; signup is handled by that provider.
Provider credentials remain in the opencode-home volume. Reinstalls skip login
after completed setup; ./install.sh --relogin opens it again without
deleting accounts. Setup asks which connected provider/model to validate, then
requires a real, small tool-free model response before marking setup complete
(provider charges may apply). --model PROVIDER/MODEL selects it explicitly;
reinstall retests the saved selection. Login, discovery and validation prime
OpenCode's integration catalog in their own container/service. Discovery retries empty model
reads in the same container, avoiding a cold-start empty-catalog response.
An empty catalog is not proof of an invalid key; saved credentials are retained.
New drafts/templates inherit this selection;
published definitions and retry versions stay unchanged. Failed checks print
bounded, credential-redacted evidence and retain their OpenCode session.
The installer then starts/recreates the Compose services,
checks ntfy health through Pipelines, and sends an authenticated test notification.
It does not register an OS service, delete volumes, or seed pipeline definitions.
Phone reception is not verified by installation.
For fresh configuration you can supply --ntfy-url https://ntfy.example.com --bind-address 127.0.0.1 --timezone Europe/London --port 8081 directly to ./install.sh.
The defaults are ready for direct phone access on your trusted LAN. Only use
plain HTTP on a trusted network. Other existing .env settings are not replaced.
Docker is also the default without a terminal; setup fails rather than
silently falling back to native binaries if the LAN address cannot be detected.
Use an interactive terminal for first Docker/provider setup.
The Docker Pipelines API is unauthenticated: keep its port on a trusted network
and do not forward it to the Internet. For a manual loopback-only deployment,
set PIPELINES_BIND_ADDRESS=127.0.0.1 after installation and use Compose directly.
Ctrl+C cancels cleanly without deleting configuration, credentials or volumes.
If Go is available, Docker setup also updates standard host CLI/TUI binaries and
the skill. Restart an already-running TUI to load the changes. Without Go, the
installer explicitly warns that the host client was not updated; use native
installation when Go is available. See Docker setup.
After ntfy verification, setup also checks the published Pipelines endpoint from
the host (when Go or a host CLI is available) and saves it in
$XDG_CONFIG_HOME/pipelines/client.json, or ~/.config/pipelines/client.json.
Only server_url is updated; unrelated settings are preserved. CLI/TUI precedence
is --url, then PIPELINES_URL, then the saved default, then localhost:8080.
Docker defaults to port 8081, so an old native server on 8080 must not accidentally
become the client target. Setup warns if an environment override still selects
another address; it does not stop or delete that other server.
If Status says ntfy is not configured, check which Pipelines server the client is reaching before reinstalling. On the Docker server computer:
docker compose port pipelines 8080
pipelines --url ws://127.0.0.1:8081/connect status --json
pipelines --url ws://127.0.0.1:8081/connect tui
Use the actual mapped port instead of 8081 if customized. On a different computer, use the Docker host's LAN address instead of 127.0.0.1. The saved default applies only on the computer/user that ran the installer. Phone reception remains untested by these checks.
Failure evidence and confirmations
TUI run/retry/cancel requests cannot be sent before their confirmation modal.
Draft creation/editing and opening a debugging session also require approval.
CLI mutations prompt with a default of No; --yes is explicit noninteractive
approval. The standalone TUI always keeps its modals, including with -yes.
pipelines debug RUN_ID --no-open retrieves the retained run plus read-only
OpenCode session evidence from the server, not the client's unrelated service.
Debug includes the exact pinned pipeline definition and full run snapshot directly.
Large context packets are retained in a private client cache file which OpenCode
is instructed to read, rather than discarding evidence or exceeding argument limits.
New failed operations retain operation, provider/model, executable, directory,
timing, exit/HTTP status and bounded stdout/stderr under opencode_failures in
the step transcript. Credentials are redacted, but project/provider messages may
still contain private context: review before sharing. Older failures cannot gain
discarded subprocess output retroactively; Debug attempts retained session reads.
Native OpenCode schema support is checked with a retained, deny-all, no-inference
POST/readback probe. OpenCode 1.18.35 accepts explicit formats but rejects their
stored messages on readback; affected backends omit format and require the same
strict local {outcome, output} validation. Compatible backends retain schema
mode with no automatic tool-replaying schema retries. The compatibility decision
and probe session are recorded, without rewriting published definitions/history.
For old format-bearing sessions whose HTTP readback fails, Debug uses read-only
opencode export with an exact session-ID check to recover original messages.
StructuredOutputError is surfaced directly; DSML/tool-call markup and flattened
results are rejected and retained, never silently interpreted as successful tool
execution or wrapped into a guessed result. Native HTTP evidence distinguishes
adapter/HTTP failures from actual subprocess exit codes.
To validate a model on the execution computer, run:
pipelines provider-check --model PROVIDER/MODEL
# Docker credentials are separate from host credentials:
docker compose exec pipelines pipelines provider-check --model PROVIDER/MODEL
For a private repository, use your normal Git credentials and GOPRIVATE:
GOPRIVATE=git.a-wan.net go install git.a-wan.net/alan/pipelines/cmd/...@latest
pipelines skill install
For a system-wide command, build as your normal user and install the three binaries into an administrator-selected bin directory using your normal system permissions. Services and OpenCode accounts still run as the logged-in user, never as root. The installer does not hardcode a system destination or run sudo.
Start explicitly
pipelines serve # foreground server; Ctrl+C stops it
# In another terminal:
pipelines
The server listens on loopback. Change into your repository and run a pipeline there; the client sends its current directory to the server. The server's own working directory does not restrict which repositories you can use. Model tool permissions and approved edit paths remain separate, per-run/stage controls.
The SQLite database uses the standard user data location, honoring XDG_DATA_HOME
when set. On macOS it uses the user Application Support directory. -db FILE
selects another database, including an existing one; nothing is imported or moved
automatically. pipelines serve --help prints the actual defaults on your machine.
Drafts use the OS user cache; PIPELINES_DRAFT_DIR overrides that location.
Optional autostart
Stop any existing foreground or legacy server first, then explicitly configure the OS user service:
pipelines service enable
pipelines service status
This starts the server now and at subsequent logins. Linux uses
systemctl --user; macOS uses a LaunchAgent in your user Library/LaunchAgents.
There is no sudo, Docker dependency, or second supervisor. --db
and --addr select the database/listen address, just like foreground startup.
Re-run enable to update the definition and restart with the new settings.
pipelines service enable --print # preview only
pipelines service disable # stop and remove
Setup records the current PATH, HOME, XDG directory overrides, selected OpenCode
executable, and supported ntfy URL/token-file settings in a private service file.
It does not copy provider credentials or the rest of the shell environment.
Use PIPELINES_NTFY_TOKEN_FILE, not an inline token. Re-run enable after changing
these settings or moving binaries. Relative database/token-file paths are resolved
at configuration time. Services do not read your shell startup files.
On Linux this is login autostart, not automatically boot-without-login.
If needed, explicitly enable lingering using your system's normal administration
policy (loginctl enable-linger "$USER"). Pipelines does not change that policy.
macOS LaunchAgents likewise require a user login. Windows autostart is unsupported.
Use journalctl --user -u pipelines.service for Linux logs. On macOS inspect
pipelines service status; run pipelines serve in the foreground for diagnostics.
OpenCode
Use your existing opencode on PATH, or set PIPELINES_OPENCODE to an explicit
executable. No OpenCode version is required just to install binaries. At runtime:
- The standard/native API release uses an owned, authenticated loopback
opencode serveprocess, scoped to the requested repository and using the existing user's configuration/login. The API, not a version number, is checked. - A CLI advertising
apiuses the V2 command interface and its normal discovery. - Both adapters select the pipeline's configured model explicitly and preserve
stage tool permissions. Native
shellpermissions map to OpenCode'sbash. - Audited native sessions record their backend and a private service reference so recovery addresses the same service, rather than a new unrelated instance.
new/editopen the normal interface directly with@pipelinesand a draft context-file reference. The skill handles questions and draft validation inside OpenCode; no preliminary session/API calls or instruction preload are performed.
The global skill is installed in $XDG_CONFIG_HOME/opencode/skills/pipelines,
or the normal ~/.config/opencode/skills/pipelines default. Only unchanged files
previously installed by Pipelines are updated. A user-managed/modified skill is
never overwritten; preserve or rename it before running pipelines skill install.
Installation does not require OpenCode itself. Uninstall retains the skill and drafts.
The bundled examples retain opencode-go/deepseek-v4.1-flash. Availability and
authentication for that model are runtime requirements, not installation checks.
No login or provider credentials are copied or exported by Pipelines.
Optional notifications
Full Docker installation configures this automatically via ./install.sh --docker.
For native mode, use an existing ntfy server or the Docker setup in docs/ntfy.md.
Configure PIPELINES_NTFY_URL, PIPELINES_NTFY_PUBLIC_URL, and a publishing token
via PIPELINES_NTFY_TOKEN_FILE in the server's environment. Keep secrets out of
pipeline definitions. Use HTTPS or an encrypted VPN for phone access; do not
expose an unauthenticated pipeline server or HTTP credentials to untrusted networks.
Uninstall
Disable autostart with pipelines service disable if configured, or stop the
foreground server first, then:
pipelines uninstall
# or pipelines uninstall --yes
Only Go binaries whose embedded build metadata matches this repository are removed from the current command's bin directory. History, drafts, OpenCode, and optional ntfy data remain untouched. Use the permissions appropriate to your chosen bin directory. Custom database paths cannot be inferred, so uninstallation does not purge data.
Existing managed installations
The previous Python-supervised setup is retained only for explicit legacy use.
Set PIPELINES_PREFIX to its existing directory for its lifecycle commands;
no command infers that directory from an executable location. The old
--system-command, provisioning, and autostart installer flags have been removed.
To migrate, stop the old server first, install normal Go binaries, and start with
pipelines serve -db EXISTING_DATABASE. Keep the old
data and credentials until you have verified the new setup. There is no automatic
purge, database move, login migration, or shared OpenCode service modification.