Local-first, vault-native, edge-friendly. Full control over a team of local agents, without hidden state or heavyweight frameworks.
Piren starts with Pi Coding Agent and adds the missing local-first runtime layer: inspectable state, explicit tools, safe gateways, and edge-device operations. Everything lives in a Markdown vault you can read and debug.
npm install -g @odiobill/piren
A short walkthrough of Piren: the vault, the inspectable tools, and a fleet sharing one substrate.
A team of local agents works best when everyone shares one source of truth: a plain Markdown vault, not a hidden database or a private memory layer.
Piren keeps agent identity, tasks, skills, logs, and cumulative knowledge in that vault. Explicit tools read and write it; nothing is hidden, and you can debug the whole team from a terminal.
That is what Piren is. A local-first, vault-native runtime for a stewarded team of agents, built so you stay in charge and only carry the complexity you actually need.
Piren merges LLM-Wiki and Second Brain workflows with explicit multi-agent task execution. Boring on purpose, transparent by design.
Agent identity, memory, tasks, logs, skills, and cron jobs live in plain Markdown. Obsidian can be the source of truth. Nothing is hidden in a database.
No transparent shell or file interception. Agents call named tools like vault_read and project_append_log that you can read and audit.
Agents update handoffs, decision records, runbooks, and skill candidates as visible artifacts, not hidden memory mutations. Everything is reviewable.
Lightweight enough for a Raspberry Pi or UDOO X86. Transparency and debuggability over maximal framework surface area.
Lower token cost in practice. Heavier frameworks load agent personas, tool definitions, and persistent context into every request. Piren keeps startup context lean and loads only what the current task needs: skills on demand, vault reads as explicit tool calls. The context stays small because you control what enters it.
Point several installations at one shared vault. Each machine keeps its own local runnable-agent policy.
Think of the vault as the office building and each Piren installation as an office in the same building on the same network. The agent is an employee whose identity, memory, and tools live in the building, not in any single office.
So when an engineer has the laptop and skills they need, they can do their job from any office. Install Piren on a Raspberry Pi in the closet, a desktop, and a laptop, point all three at one synced vault, and atlas is the same agent on every machine: same SOUL.md, same pending inbox, same skills, same cron jobs.
Work does not fail over by itself. An eligible device that is running the scheduler can explicitly claim eligible pending work or a due cron job, but only after the active-device and stale-heartbeat rules permit it. Claims are visible vault file renames and always claim-first.
Synchronized vault copies do not provide a distributed claim-exclusivity guarantee: asynchronous sync means two machines can briefly observe different states. Local claim-first renames and stale-heartbeat checks are the coordination Piren provides.
What does not happen: no automatic failover, no silent re-execution, no resumed interrupted work, and no cross-agent rerouting.
Which machines may host which agents is an installation policy (allowed_agents), kept outside the vault. The vault carries the team; the installation decides which office it runs in today.
Four ways to reach your agents, one inspectable substrate underneath, plus the coordination primitives a fleet needs.
A steward workspace for durable multi-agent Conversations: Dashboard, streaming chat with approval gates and scoped abort, a read-only Vault Explorer, truthful per-agent context cards, and a typed Settings page with write-only tokens.
Telegram and Discord bots route conversations to your local runnable agents. One bot, many agents, local allowlists for access control.
A drop-in /api/v1/chat/completions endpoint. Point any OpenAI-compatible client at Piren and it just works.
Scheduled work is Markdown job files with active-device ownership, atomic claiming, and inspectable run records. No central database.
The vault follows Open Knowledge Format v0.1: concepts carry typed frontmatter, piren doctor audits conformance, and other OKF-aware tools can read the bundle.
Keep gateway, Telegram, Discord, and the scheduler always-on with one command. Piren generates systemd user units, with a tmux plus @reboot cron fallback for DietPi and stripped-down SBCs. Inspectable, reversible, no root.
Run piren setup after signing in to Pi: it creates or reuses a vault and writes local configuration. Add Telegram or Discord later with their separate, explicit configure commands. Plus --help on every command.
Reusable procedures in vault/skills/, cataloged at startup and loaded on demand. Group-scoped skills sit between shared and agent-specific, so a team shares a skill pack without duplicating it.
Group agents by role to share skills and a fallback policy. When an agent can't pick up a task, piren agents --fallback recommends an eligible teammate, filtered by local policy. Read-only: nothing changes hands silently.
A device-local scheduler for inbox tasks and cron jobs, driven by heartbeat priorities and atomic claims. piren scheduler --dry-run previews the next claims with zero LLM calls, --once runs a single bounded tick, and piren scheduler runs the opt-in loop until you stop it. Claim-first, one item per tick, every run recorded in the vault. No hidden autonomy.
Add capabilities through npm packages declared in local config, loaded as Pi extension flags. Piren core stays minimal.
The Workbench: a Dashboard with your local agent roster, streaming Conversations with approval gates and scoped abort, a read-only Vault Explorer, and a typed Settings page. No live-session model controls and no browser token storage, by design.
Every action is an explicit, inspectable tool call: vault_read, decision_record, flag_steward. The agent's work leaves artifacts in the vault, not hidden memory.
One visible workspace for a team's Conversations: the Dashboard, a durable timeline, and a scoped live stream.
The Dashboard lists your vault's agents and marks which are runnable on this installation. Start a Conversation with one agent you select, or a peer Conversation with two to eight locally runnable agents.
A peer Conversation is created with its initial audience recorded, but no agent is dispatched: no greeting, no lead, and no fan-out. An agent starts working only when a message mentions it.
Each Conversation shows an immutable whole-history timeline plus a scoped live stream. When a member is not locally runnable, it opens as read-only inspection instead.
Approve or reject requests with Confirm, Cancel, or a value, and abort one agent's active run. Recipient mentions are validated at the gateway, never in the browser, and the browser never fabricates an agent outcome.
Archive a Conversation to make it read-only, or reopen an archived one. Neither action cancels a running turn.
Three focused tabs edit your configuration through typed workflows; services stay separate, explicit commands.
This installation (transport tokens and scheduler gates), Agent settings (model, context, self-improvement), and Agent groups. Each tab edits a specific configuration family through typed, validated workflows.
Transport bot tokens are write-only: the browser never shows them after saving. Non-secret values are prefilled from a redacted read.
Settings never edits provider credentials or the gateway token, and it never changes the runnable-agent policy. Those stay in their own local or Pi-native locations.
The Workbench shows a read-only service snapshot, but install, start, stop, and restart are explicit piren service commands.
The bearer token stays in browser memory only. It is never written to storage.
Groups share procedures by scope; execution authority stays local and explicit.
Skills load shared, then group, then agent. An agent-specific skill always wins, and a group skill overrides a shared one of the same name.
Groups share skill packs and a fallback policy, never execution authority. Membership in a group does not let an agent run on a machine.
piren agents --fallback <agent> recommends an eligible teammate, filtered by local policy and same-group membership. It never reassigns or reroutes work.
Explicit inbox task files, and an opt-in scheduler that claims one item per tick.
Tasks are Markdown files in an agent's inbox. piren task lists, sends, shows, claims, completes, and cancels them; every step is a visible file change.
piren scheduler is off by default. --dry-run previews claims with no model calls, --once runs one bounded tick, and the loop runs until you stop it.
Each tick claims at most one item by atomic rename, then records the run in the vault. There is no automatic reassignment, no silent retry, and no resumption of interrupted work.
An optional per-agent fallback list for provider errors, scoped to one session.
A declared fallback rotates in order, at most once per entry, only after a run fully settles as an eligible provider error on the same session.
An absent, malformed, or disabled declaration does nothing. Nothing re-dispatches or reroutes to another agent.
An explicit live model selection disables automatic fallback for that session.
Several doorways into the same visible team state.
The web Workbench for Conversations, Settings, and the Vault Explorer.
Bots route conversations to your locally runnable agents with machine-local allowlists.
A drop-in /api/v1/chat/completions endpoint for any OpenAI-compatible client.
Transport authorization is machine-local and fail-closed; nothing is reachable unless it is explicitly allowed.
Piren natively merges LLM-Wiki and Second Brain workflows with multi-agent task execution, backed by an Open Knowledge Format v0.1 compliant vault that is portable outside Piren.
Piren now treats the vault as an OKF v0.1 bundle. Concept documents carry a required non-empty type: frontmatter field, Piren ships a pure conformance checker, and both piren doctor and the read-only vault_conformance_check() tool can audit drift without blocking work.
That matters because your agents' memory is no longer trapped in an app-specific database. It is plain Markdown, typed, linked, inspectable in Obsidian, cloneable with Git, and consumable by any future OKF-aware tool.
When one agent solves a problem, the next agent, or a future session, starts from the accumulated decision, runbook, or skill, not from rediscovery. The steward reviews and promotes; nothing is auto-applied. Raw traces stay evidence. Current project documents become synthesized truth. Skills become shared procedure.
One inspectable vault holds identity, tasks, sessions, skills, and knowledge for a whole team of agents.
Gateway transports are separate Pi RPC processes. The vault is always the source of truth.
Pi dependency, vault portability. Piren is built on Pi Coding Agent and tracks its public API surface. The vault is the stable layer: plain Markdown, Git-cloneable, readable without Piren. If the underlying engine changes, your agent state, knowledge, and task history remain intact and portable.
Sign in to Pi, install Piren, then let the guided setup create your first local workspace.
Upgrading from 0.1.3? Run npm install -g @odiobill/piren once. That older piren update command uses the retired GitHub install path.