Installation and Deployment

This page is for Linux server maintainers. For the desktop one-click launcher, use Quick Start. The server commands and docker-compose.yml below match the current Core release; initialize in the browser without business environment variables. Current state: published.

Start the Linux server

Use Linux x86-64 and rootful Docker Engine 28+. One container serves the workbench, administration and first-time setup, with no environment variables or client CLI required:

This published image includes direct browser entry and web setup.

docker run --detach --init \
    --name piwork-core-quickstart \
    --network host \
    --restart unless-stopped \
    --stop-timeout 60 \
    --mount type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock \
    --volume /var/lib/piwork/quickstart/core:/var/lib/piwork/quickstart/core \
    docker.io/pphboy/piwork-core:0.0.13-c48a40daf766-19451f0a08fc

On this computer or another computer, open http://SERVER_IP:17891 using the server’s actual IP. An empty installation shows Create administrator; an initialized installation shows normal sign-in. No terminal authorization link is required.

Create the administrator with a password and matching confirmation, then sign in to Quick setup in Admin (/admin/setup). Follow the two-step guide: enter the model ID, API type, Base URL and API Key, or choose a saved model, then select Save and continue. This saves the model and binds CoreRuntime in sequence. The preparation page updates automatically; when all required components are Ready, select Open workbench to enter Piwork. The Agent image is embedded with the server release and supplied automatically; it has no input, selector or advanced override. Model Test is explicit and optional; saving does not call the model. Open the workbench to create a Work, chat, manage files or open Services. Return through Admin Overview → Quick setup to change configuration. The topbar Workbench link remains available while preparation finishes; the completion action waits for all components. Saved accounts, models and Works survive restart.

One process serves two HTTP listeners: UI defaults to 0.0.0.0:17891, Core to 0.0.0.0:17871. Browsers use only UI, including files, events and /services/<workId>/<serviceId>/<port>/; the backend calls Core over fixed loopback HTTP. External Linux CLI connects directly to the server Core port. Change ports only with --ui-port/--core-port. UI accepts actual local IPv4 addresses, localhost, loopback and the machine hostname, validates Host, Origin and CSRF, and ignores Forwarded. Each address needs its own login. HTTP only; no HTTPS, custom domain or reverse proxy configuration. Internal Agent callbacks retain container-reachable mTLS on 7172. User Services publish no host ports. Model endpoints must be reachable from Work networks.

Hosted Services share the workbench origin and must be trusted: scripts can use the current user’s UI permissions. Apps must support a dynamic Service URL prefix; old root-path apps, images and packages are not rewritten automatically. Services support server-side login using response Cookies, Basic/Bearer, HTTP, SSE and WebSocket. Response Cookies stay on the server, partitioned by browser session and Service; Secure Cookies are not forwarded through the HTTP entry. Apps that read/write document.cookie or Cookie Store (including script-read CSRF Cookies) are not guaranteed to work transparently. Script-written browser Cookies are not isolated across Services on the same IP and are never forwarded upstream. Hard-coded .work URLs, cross-site SSO and upstream HTTPS are outside transparent support. Application CSP/X-Frame-Options remain intact; open an application tab when embedding is denied.

Optional Compose (2.24+) and the single-host example open the same web application. CLI is an optional advanced tool. See the operations guide for recovery.

Platforms and persistence

For an optional CLI setup, see Single-host deployment and its example Compose.

Core Compose Demo

The optional Compose demo uses its own /var/lib/piwork/core directory. Stop an installation using the same ports normally before starting. Set up the administrator and model in the browser.

PIWORK_CORE_IMAGE=docker.io/pphboy/piwork-core:0.0.13-c48a40daf766-19451f0a08fc \
    docker compose -f compose.core.yaml up --detach --wait --wait-timeout 600 core

Terminal operations

Process health and runtime readiness are separate: /healthz is available before web setup finishes; /readyz remains unready. Manage users, models, runtime and dependency preparation in embedded Admin. Operator credentials and protected management APIs remain separate from user CLI credentials.

curl --fail http://127.0.0.1:17891/healthz
docker logs --tail 100 piwork-core-quickstart

Core also keeps a private process log in logs/core/ under its data directory. Each start writes a new core-<bootId>-<segment>.jsonl shard; shards rotate at 16 MiB, the installation retains at most 256 MiB for 7 days, and file writes sync about once per second plus on rotation, export boundaries and normal shutdown. Keep the Core data volume mounted to preserve these shards across container replacement. File coverage begins after the installation lock and includes managed diagnostics, performance events, standard application logs and startup/shutdown records. --help/--version, invalid startup, errors before that lock and native runtime crashes outside the application log writer remain console/stderr only; this is not a complete raw-stderr capture.

Before removing or replacing an Agent or Service instance, Core archives that exact instance's retained stdout/stderr under logs/works/ in the data directory. Archives are kept for 7 days, up to 512 MiB per Work and 2 GiB per installation, removing the oldest unreferenced archives first. Containers replaced or removed before this release cannot be backfilled; existing containers keep their actual log driver and only new Agent/Service instances use the bounded 16m × 4 json-file policy. Keep the data volume mounted.

Administrators can export Core safe platform logs plus all of their own Work logs from the Linux CLI or the Desktop account menu (Export logs). Export never stops or applies a Work. CLI: piwork-cli --core http://SERVER_IP:17871 login --account admin, then piwork-cli --core http://SERVER_IP:17871 logs export --output ./piwork-logs.zip; recover the original task with logs show EXPORT_ID and logs download EXPORT_ID --output FILE. Ready archives are kept for 24 hours; partial results keep complete=false and list gaps in manifest.json. Closing the UI panel or interrupting the CLI does not cancel an accepted Core task. The GUI flow requires no commands; download the ZIP and send it manually to a trusted maintainer. This feature does not upload it automatically.

Optional test bootstrap: paired PIWORK_ADMIN_ACCOUNT and PIWORK_ADMIN_PASSWORD initialize only the first administrator on an empty installation. Existing accounts are retained. Default setup needs no business environment variables; model and image settings are not read from initialization env.

On the Linux client, select an existing Core address and enter the password interactively. ACCOUNT and WORK_ID come from your account and creation result:

export PIWORK_CORE_URL=http://SERVER_IP:17871
piwork-cli login --account ACCOUNT
piwork-cli work create --name 'My Work' --wait
piwork-cli chat WORK_ID --message 'Hello, Piwork!'

Read back unknown writes and recover original Operation/Run IDs without resubmitting. Files and packages use local client paths, with no exchange volume.

piwork-cli operation show OPERATION_ID
piwork-cli run watch WORK_ID RUN_ID --after SEQUENCE

Normal Core shutdown stops this installation’s managed Works and preserves identities, history, volumes and desired state. Closing a browser or CLI does not stop Core or Works.

docker stop --time 60 piwork-core-quickstart
test "$(docker inspect --format '{{.State.ExitCode}}' piwork-core-quickstart)" = 0
docker start piwork-core-quickstart

docker compose -f docker-compose.yml stop core
docker compose -f docker-compose.yml up --detach --wait --wait-timeout 600 core

Retain the same Core directory and matching Work volumes. Stop normally and take a consistent backup before upgrading. Keep prior image references and manifests; roll back only with compatible formats. Do not use down -v or global prune. Work exports are not installation backups: Stop before export and explicitly Start after import.

Advanced and older-version entry points

For source/native builds, see Build from Source. The older 0.0.1 installer, release.env, templates and Desktop operations remain in the versioned upstream guide. Existing install/0.0.1 and install/0.1.0 links retain their older provenance.

Installation and Deployment ​

Start the Linux server ​

Platforms and persistence ​

Core Compose Demo ​