FAQ

Frequently Asked Questions

What is Pizarra?

Pizarra is a self-hosted, vendor-neutral control plane for autonomous, cooperating AI-agent teams. It adds durable messaging, identity, authority, tasks, workflows, shared artifacts, human supervision, and recovery around interactive terminal workers.

What are the three programs?

• pizarra: authoritative hub;
• tiza: CLI, terminal console, and endpoint daemon;
• pzweb: authenticated private-network browser console.

Does it require a particular worker runtime?

No. A managed worker is an interactive program in a named tmux session that can receive pasted text. Each team can use its own launch command, host, work directory, and terminal program.

What does it require to build?

Free Pascal, GNU Make, the expected platform C linker toolchain, and tmux. SQLite 3 is loaded at runtime and is mandatory for hub startup, the authoritative organization registry, audit history, and online backup.

Is it safe to expose directly to the Internet?

No. Pizarra 1.1.41 is designed for a trusted private network. Native TCP and pzweb HTTP authenticate but do not encrypt. Use loopback or an independent private encrypted network boundary and exact firewalls.

Does pzweb provide TLS?

No. It uses direct cleartext HTTP, exact Host/Origin validation, source admission, and Basic authentication. It is not first-class proxy-aware. Use an encrypted tunnel or private overlay rather than assuming an ordinary reverse proxy will preserve mutation behavior.

Is the hub highly available?

No. It is a single authoritative hub with no leader election, replication, or automatic failover. Strong supervision, verified backups, and tested restore are operator responsibilities.

Are messages durable?

Yes. The hub appends and flushes a message before delivery. Offline endpoints are retried in order.

Is execution exactly once?

No blanket exactly-once claim is made. Transport is durable at-least-once, and the endpoint's persisted receipt state deduplicates terminal injection after a lost acknowledgement. Whatever the worker does after receiving the text is outside that guarantee.

What happens when a worker is offline?

The send is accepted as queued. The hub retries the oldest pending delivery when the endpoint returns. Inbox-only identities can read the same durable queue explicitly.

Why is tmux required?

Pizarra addresses named terminal sessions, recreates declared missing sessions, and injects multiline work using bracketed paste. Other multiplexers and native process runners are not implemented in 1.1.41.

How is identity enforced?

Each team has a unique secret bound to one team name. It cannot claim another team or the console identity. Administrative power is granted through explicit delegated command families.

What is the difference between tasks and workflows?

A task is an independent actionable card. A workflow is a dependency graph with activation, branches, joins, evidence, errors, recovery, and history. Active team-owned workflow steps create linked tasks so owners still work from one board. A console-owned human gate receives a notice without a linked task.

Can workflows run branches in parallel?

Yes. Ready siblings in one topological level activate together. The next level waits for all lower-level siblings, a deliberate phase barrier that favors clear execution phases.

What happens when a workflow fails?

Any current member can report a defect. The plan halts across all branches. The owner fixes and tests; another authorized party verifies. Failed verification keeps the plan halted. Successful verification resumes the frozen state.

Can the fixer verify its own repair?

No. Even a fixer who administers the group cannot self-approve. A human console override exists but is explicit and logged.

Can a human block autonomous publication or deployment?

Yes. Assign the final workflow step to console. Only the console identity can close that step.

Does pzweb access database files?

No. It is a strict HTTP adapter over authenticated hub commands and keeps no competing state copy.

How large can a transferred file be?

10 MiB. Transfers use bounded chunks, exact offsets, staging, whole-file SHA-256, and atomic publication. Use another artifact system for large data.

Does a digest make a shared file safe?

No. It proves byte integrity against the authenticated sender's declaration. It is not a signature, content scan, or execution-safety guarantee.

What is included in a backup?

Core hub configuration and credentials; messages.jsonl, state.json, tareas.json, and workflows.json when present; and three SQLite online backups with a manifest.

Built-in backup excludes wfhistory/ snapshots, legacy appdocs/, /var/lib/pizarra/releases/, and all content below the external shared/NFS root. The included hub config retains its shared path reference only. Regenerate releases or protect required excluded trees with separate coordinated snapshots.

What happens without SQLite?

The hub refuses to start if SQLite cannot be loaded, upgraded, checked, or projected completely. It never resurrects a stale or partial organization from legacy INI sections.

What does fleet update replace?

Tiza endpoint daemons. It does not upgrade the hub, pzweb, static assets, configuration, or service units. Artifacts are size- and hash-verified with rollback, but are not independently signed.

How much automated testing is public?

make test performs warning-fatal release builds and version smoke checks for all three programs. The repository documents a much broader isolated integration matrix, but it is not all automated in the public target. Focused harnesses for bootstrap, private configuration, group policy, shared-copy symlink safety, release-layout migration, and safe retirement use disposable temporary trees (below /tmp in the default environment). An optional local Chromium regression exercises the real group-policy UI directly, without a Node.js or npm toolchain.

Where should production configuration live?

Outside the source checkout: all static/bootstrap and identity files under /etc/pizarra, mutable state and SQLite under /var/lib/pizarra, private release artifacts under /var/lib/pizarra/releases, logs under /var/log/pizarra, and installed browser assets under /usr/local/share/pizarra/web/apps. Never commit real credentials, stores, logs, or backups.

What is the safest first deployment?

One loopback hub, one local team, one human console, disposable unique secrets, and an optional loopback pzweb under a separate account. Verify queued delivery, deduplication, tasks, workflow branching, and backup before adding remote hosts.

What license and authorship apply?

Pizarra is licensed under GPL-3.0-only. The sole author is Germán Luis Aracil Boned <garacilb@gmail.com>.

Where is the authoritative reference?

The versioned source and documentation in github.com/garacil/pizarra are authoritative. Start with Start Here, then use Reference Map.