Files
pipelines/docs/install.md
T

4.5 KiB

Install and test

Run as your normal user, not with sudo. Requires Python 3, a running Docker daemon with Compose, and OpenCode V2 connected to OpenCode Go. Source installs also require Go 1.27+. Platform archives contain the server, CLI, and TUI binaries. If OpenCode is absent and npm is available, the installer offers a private pinned CLI install; Docker itself is not installed automatically.

./install.sh
# Optional: expose the command in /usr/local/bin (sudo for the symlink only):
./install.sh --system-command

Setup prompts for phone username, password, and global notification topic. Blank password generates one. --yes accepts defaults and generates a password; --password-file PATH supplies one without putting it in shell arguments. Phone connection details are saved privately in ~/.local/share/pipelines/secrets/phone-login.txt. Configure the ntfy phone app with those credentials and subscribe to that topic. Phone delivery still needs an actual device test. Prefer Tailscale or HTTPS; HTTP exposes credentials on an untrusted network.

The native server and Docker ntfy are managed together:

pipelines                  # dashboard; b opens rendered templates
pipelines status
pipelines doctor
pipelines stop
pipelines start
pipelines restart
pipelines logs

Default command path is ~/.local/bin/pipelines; add ~/.local/bin to PATH if needed. It points directly to a compiled Go binary, not a shell launcher. Source installation builds all binaries with go install. Service registration uses per-user launchd on macOS or systemd on Linux. --no-autostart uses background supervision instead. Services retain the current user's OpenCode config/login, without exporting credentials into Docker. --system-command is a system PATH shortcut to this user's install, not a shared multi-user service. Other users should install their own instance.

Run in a repository

cd ~/repos/my-project
pipelines run                           # fuzzy pipeline picker, then prompt
pipelines run "bug fix"                 # prompt composer
pipelines run "bug fix" "Fix the layout" # explicit execution confirmation
pipelines run "bug fix" "Fix the layout" --yes

The composer supports multiline typing/paste: Enter adds a newline, Ctrl+S or Alt+Enter continues. The current directory is recorded as the run workspace. After confirmation, the live run inspector opens. --yes requires a supplied name and nonempty prompt and does not approve tools. Use --allow-tools with --yes to explicitly approve declared tools; --write-paths "internal/example.go" grants exact existing Go-file edits. Current edit tooling is Go-specific, not arbitrary repository editing.

Installer workspace roots default to the user's home directory. Restrict them using repeatable --workspace-root ~/repos on initial setup. Runs outside those roots (including symlink escapes) are rejected by the server. Raw native servers default to their working directory; add -workspace-root to permit other repos. Do not expose the unauthenticated pipeline server to untrusted users.

Templates and data

New databases are empty. Press b on Home or use :templates to browse optional examples, with rendered Markdown previews and v for source. Select a template, choose a unique name, edit it in $VISUAL/$EDITOR (or an available fallback), then explicitly submit. Existing names cannot be overwritten by this flow. Submitting a scheduled template activates its schedule; previewing never does.

Uninstall retains pipeline history, credentials, and the isolated ntfy volume:

./uninstall.sh
# Explicitly delete this installation's retained data too:
./uninstall.sh --purge

Reinstall at the same prefix to reuse retained data. Host OpenCode remains separate. Partial installations require inspection or explicit purge before retry. Use --prefix PATH --bin-dir PATH --server-port PORT --ntfy-port PORT for isolated testing; each prefix has its own Compose project and volume.

Tester archives

python3 scripts/package.py --platform darwin-arm64 --version 0.1.0-beta.1
# Also: darwin-amd64, linux-amd64, linux-arm64, source

Outputs go to dist/ with a SHA-256 checksum. Archives include only allowlisted source, examples, docs, installation scripts, and optional release binaries—no databases, runtime drafts, .env, logs, or secrets. Extract, then run ./install.sh. Cross-built Linux binaries, Linux systemd, system PATH installation, and automatic npm installation require separate execution tests; build success is not a runtime test.