334 lines
19 KiB
Markdown
334 lines
19 KiB
Markdown
# Installation
|
|
|
|
To reconfigure login and separate interactive/new-pipeline models without a
|
|
service reinstall: `./install --opencode` or `./install --pi`.
|
|
See [configured harnesses](harnesses-and-control.md) for scope and verification limits.
|
|
|
|
`./install` sets up **Docker server + ntfy**, the only supported runtime installation.
|
|
It requires Docker Compose and Python 3 and includes OpenCode/Pi in the persistent
|
|
server container. Host Go builds the CLI/TUI clients, not a native server.
|
|
|
|
```sh
|
|
git clone https://git.a-wan.net/alan/pipelines.git
|
|
cd pipelines
|
|
./install
|
|
# Optional: choose Pi rather than OpenCode for setup:
|
|
./install --harness pi
|
|
```
|
|
|
|
The installer builds host `pipelines` and `pipelines-tui` clients when Go is
|
|
available, using `GOBIN` or `GOPATH/bin`; put that directory on PATH. It does not
|
|
install a host server. Reconfiguration uses `./install --opencode` or `./install --pi`
|
|
inside the existing Docker installation and never falls back to host execution. It
|
|
resolves and verifies the same current releases and refuses to configure against an
|
|
image that does not match them (rebuild with `./install` first); it does not restart
|
|
or redeploy services.
|
|
|
|
Native Go builds embed VCS identity; Docker setup passes the checkout revision and
|
|
dirty state as compile-time build arguments (without copying `.git` into the image).
|
|
For a build-only refresh use `python3 scripts/build_metadata.py`; it resolves the
|
|
current OpenCode V2/Pi releases and runs `docker compose build` with the identity
|
|
arguments plus the resolved version/digest arguments, without restarting services.
|
|
A plain `docker compose build` cannot resolve the OpenCode image digest, so it must
|
|
be given `OPENCODE_VERSION`, `OPENCODE_DIGEST` and `PI_VERSION` through Docker
|
|
`--build-arg` flags (and `PIPELINES_VERSION`, `PIPELINES_COMMIT` and
|
|
`PIPELINES_DIRTY` outside a Git checkout); `./install` supplies all of them. After deployment,
|
|
`pipelines --url ws://HOST:PORT/connect ping --json` identifies the running server.
|
|
Docker setup checks that the started server's pong matches the source identity
|
|
passed to the build and fails setup if metadata is missing or mismatched.
|
|
|
|
Each setup resolves the current releases before touching settings or services: the
|
|
newest supported **OpenCode V2** release from the single documented complete
|
|
`GET .../git/matching-refs/tags/v2` response (a bounded complete array with no
|
|
pagination parameters; never the moving `latest` tag or the registry's insertion
|
|
order) and the current Pi release from npm. The image is built `FROM` the OpenCode
|
|
image's immutable `sha256` digest, resolved from GHCR, and labeled with the
|
|
resolved OpenCode/Pi versions, digest and source identity; the moving `latest` tag
|
|
and version-only references are never used. Setup verifies the built image reports
|
|
exactly those executable versions and a Node-compatible Pi engine, and stops with
|
|
a clear error (keeping the last verified Dockerfile fallback pins) when discovery,
|
|
resolution, build or compatibility fails rather than guessing or silently
|
|
installing stale or unchecked copies. A full install skips a rebuild only when the
|
|
release receipt **and** the actual built image's release and source identity labels
|
|
already match; a dirty source always invokes the Docker build and relies on layer
|
|
caching. A model/login-only reconfiguration compares only the verified release
|
|
image identity, so a changed source alone does not rebuild on reconfigure.
|
|
Setup writes that release receipt to the machine-local, generated root file
|
|
`.pipelines-releases.json` (with atomic `.pipelines-releases-*` temporary files)
|
|
and both are git-ignored, so a fresh clean checkout stays clean after setup and
|
|
reinstall still reuses the verified release/image identity. The actual built
|
|
image's labels stay authoritative, clean-checkout identities/reinstall reuse are
|
|
unchanged, and a dirty source still rebuilds.
|
|
|
|
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 --relogin` opens it again without
|
|
deleting accounts. Setup then chooses **separate saved defaults** in order: first the
|
|
interactive OpenCode harness model, then the new-pipeline model, in two
|
|
fuzzy-searchable pickers: type to filter, arrow keys or Tab navigate, Enter confirms,
|
|
the saved value is preselected and marked `(current)`, and Esc cancels with nothing
|
|
changed. `--model PROVIDER/MODEL` and `--harness-model
|
|
PROVIDER/MODEL` set them explicitly; reinstall retests the saved selection. Container
|
|
credentials and accounts stay separate from host credentials and are reused on
|
|
reinstall/reconfigure. Picker
|
|
selection performs no inference; the OpenCode path then requires a real, small
|
|
**tool-free model response** for the new-pipeline model before marking setup complete
|
|
(provider charges may apply). 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 the new-pipeline 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.
|
|
|
|
Docker setup mounts the host user's home and the installation checkout at their
|
|
original absolute paths, and runs Pipelines/OpenCode using that host user's UID
|
|
and GID. This makes a client invocation directory such as
|
|
`/home/tank/repos/pipelines` refer to the actual host checkout rather than an
|
|
unavailable container path or the unrelated image checkout at `/workspace`.
|
|
Stage permissions/edit scopes still apply; this is a filesystem mount, not a
|
|
workspace allowlist or automatic file transfer from another client computer.
|
|
For repositories outside those mounts, add a Compose bind at the same absolute
|
|
path. Reinstallation stops the old Pipelines service before changing ownership
|
|
of its managed data/auth/workspace volumes. It never recursively chowns the host
|
|
home/repository, deletes credentials, or removes volumes. Existing data/auth
|
|
volumes use `nocopy` so Docker cannot reset a freshly prepared empty volume's
|
|
ownership to the image UID. Setup verifies that the server can enter the host
|
|
checkout before reporting completion.
|
|
|
|
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`.
|
|
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; Docker still runs
|
|
the server, and you can build the client later with host Go. See [Docker setup](docker.md).
|
|
|
|
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's default host mapping is port 8081 (the container listens on 8080), 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
pipelines provider-check --model PROVIDER/MODEL
|
|
# Docker credentials are separate from host credentials (plain CLI: no TTY):
|
|
docker compose exec -T pipelines pipelines provider-check --model PROVIDER/MODEL
|
|
```
|
|
|
|
For a developer or legacy host build, a private repository uses your normal Git
|
|
credentials and `GOPRIVATE` to compile the client/host binary (this is not a
|
|
supported server installation):
|
|
|
|
```sh
|
|
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.
|
|
|
|
## Developer/legacy host server (unsupported)
|
|
|
|
This explicit foreground server is for developing Pipelines itself or running a
|
|
previous native setup. It is **not** a supported installation; a fresh database
|
|
starts empty.
|
|
|
|
```sh
|
|
pipelines serve # foreground developer/legacy 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.
|
|
|
|
## Developer/legacy autostart (unsupported)
|
|
|
|
Stop any existing foreground or legacy server first, then explicitly configure
|
|
the OS user service:
|
|
|
|
```sh
|
|
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.
|
|
|
|
```sh
|
|
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 runtime (developer/legacy host)
|
|
|
|
For a developer or legacy host server, 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 serve` process, scoped to the requested repository and using the
|
|
existing user's configuration/login. The API, not a version number, is checked.
|
|
- A CLI advertising `api` uses the V2 command interface and its normal discovery.
|
|
- Both adapters select the pipeline's configured model explicitly and preserve
|
|
stage tool permissions. Native `shell` permissions map to OpenCode's `bash`.
|
|
- Audited native sessions record their backend and a private service reference
|
|
so recovery addresses the same service, rather than a new unrelated instance.
|
|
- `new`/`edit` open the normal interface directly with `@pipelines` and 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 packaged format, notification, operations, transfer and verification references
|
|
are self-contained; agents read only those relevant to the task. Authoring
|
|
does not require Pipelines source in the current repository. Without a task prompt,
|
|
OpenCode is instructed to ask what to create/change before investigating files or
|
|
running CLI commands. See [authoring session review](authoring-session-review.md)
|
|
for the reasoning and verification limits.
|
|
New features and confirmed limitations are maintained in the packaged skill alongside
|
|
the topic docs. Skill tests check that every embedded reference is installed and
|
|
its links resolve. Refresh the global managed skill from current source with
|
|
`go run ./cmd/pipelines skill install`; this does not deploy server/runtime fixes.
|
|
|
|
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
|
|
|
|
Installation configures this automatically via `./install`.
|
|
For a developer/legacy host server, use an existing ntfy server or the Docker setup in [docs/ntfy.md](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:
|
|
|
|
```sh
|
|
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.
|