Local-first execution-control reference runtime for AI agent builders.
Execution needs an explicit gate.
Make the decision visible. Record the approval. Execute—or stop.
简体中文 · Try it · What works today · How it grows · Documentation
Note
The main branch is the development line. Stable release candidates are
available from GitHub Releases.
PAIOS CE is a small, runnable foundation for building a personal AI system without starting from an unrestricted agent.
Today you can:
- run a deterministic local text-task loop with no API key;
- validate public and private configuration precedence;
- submit typed task and action fixtures through the CLI;
- observe permission decisions and redacted audit events;
- transcribe a local audio file through the optional Local ASR adapter when using the current main development line or a later release.
The point is not to expose every tool at once. The point is to provide a clean path from a local demo to a useful personal assistant:
local task loop
→ local speech input
→ one live Provider
→ one owner-only messaging channel
→ reversible tools
→ carefully scoped workers
Each step must remain explicit and independently testable.
git clone https://github.com/chengcheng-2006/paios-ce.git
cd paios-ce
python -m venv .venvWindows PowerShell:
.\.venv\Scripts\Activate.ps1Ubuntu:
source .venv/bin/activateInstall and run:
python -m pip install --upgrade pip
pip install -e ".[dev]"
paios-ce health
paios-ce demo
paios-ce validate-config
paios-ce run-task examples/demo_task.jsonNo API key is required for the bundled Mock Provider.
A request with an explicitly rejected unknown action is stopped before execution.
The demo shows decision: blocked, execution_attempted: false, and a blocked exit result.
On the current main development line, install the optional speech dependency:
pip install -e ".[dev,speech]"Then transcribe an audio file using a local or cached model:
paios-ce transcribe sample.wav \
--model tiny \
--language en \
--device cpu \
--compute-type int8Speech is disabled by default (speech.enabled = false). The default speech
path is local-files-only: a model identifier succeeds only when the model is
already cached locally. Model weights and audio files are not committed to the
repository.
CLI input
→ TaskEnvelope validation
→ Router
→ Mock Provider
→ TaskResult
→ redacted AuditEvent
local audio file
→ audio policy validation
→ SPEECH_TRANSCRIBE_LOCAL capability check
→ FasterWhisperAdapter
→ typed TranscriptionResult
→ metadata-only AuditEvent
The transcript is returned to the requesting user. It is not written into the audit event by default.
| Capability | Status | Default | What it means |
|---|---|---|---|
| Local text demo | Experimental | On | Deterministic Mock Provider; no network or API key |
| Typed tasks and actions | Experimental | On | Validated public contracts and JSON Schemas |
| Permission and risk decisions | Experimental | On | Unknown and forbidden actions fail closed |
| Secret references | Experimental | On | Secrets are represented by reference, not payload |
| Local file ASR | Experimental | Off | Optional faster-whisper adapter; no live channel; disabled by default |
| Live model Provider | Planned | Off | Not shipped |
| Feishu owner DM | Planned | Off | Next channel candidate; not shipped |
| WeCom / WeChat | Research | Off | No support claim |
| TTS | Planned | Off | Not shipped |
| Browser and system workers | Planned | Off | Must be narrowly scoped |
| Arbitrary shell / administrator | Blocked | Off | Not a general capability |
The authoritative status is maintained in
SUPPORT_MATRIX.md.
A low-risk request within the granted scope is allowed to proceed.
The demo shows decision: allow, risk_level: LOW, and a successful exit result.
PAIOS CE uses progressive capability admission:
flowchart LR
L0["L0<br/>Local mock"] --> L1["L1<br/>Read-only input"]
L1 --> L2["L2<br/>Low-risk output"]
L2 --> L3["L3<br/>Scoped tools"]
L3 --> L4["L4<br/>Reversible external writes"]
L4 --> L5["L5<br/>High-risk structured workers"]
A new capability is not accepted merely because it works once. It must define:
- a typed contract;
- required capabilities and scopes;
- default-off configuration;
- secret and network behavior;
- failure and rollback behavior;
- redacted audit evidence;
- deterministic tests;
- clean-machine validation; and
- an honest support status.
See docs/CAPABILITY_ADMISSION.md.
The current project is a release candidate and a public-core scaffold. It does not ship:
- live WeChat or Feishu channels;
- a production cloud-model Provider;
- microphone streaming;
- TTS;
- browser automation;
- arbitrary shell or administrator elevation;
- remote desktop control;
- production Hermes/OpenClaw integration.
Those are future adapters, not current support claims.
Detailed trust boundaries live in
docs/SECURITY_MODEL.md. The README keeps the safety
summary short so the runnable experience remains visible.
| Command | Purpose |
|---|---|
paios-ce health |
Safe local diagnostics |
paios-ce demo |
Deterministic local text-task loop |
paios-ce validate-config |
Validate and display redacted effective configuration |
paios-ce run-task FILE |
Run a typed task or evaluate an action fixture |
paios-ce transcribe FILE |
Experimental local-file transcription |
| Gate | Current baseline |
|---|---|
| Platforms | Windows + Ubuntu |
| Python | 3.11 + 3.12 |
| Existing test baseline | 298 passed + 1 filesystem skip |
| Line / branch coverage | 87.83% / 76.62% |
| Package | Wheel, sdist and clean-install smoke |
| Security | Credential scan, forbidden-content scan and dependency audit |
| Release | Public pre-release with anonymous source downloads |
Local ASR validation adds speech-specific tests while preserving all existing gates and workflow policy.
- Getting started and demo
- Local ASR
- Capability admission
- Architecture
- Security model
- FAQ
- Roadmap
- Support matrix
- Contributing
PAIOS CE evolves capability by capability while keeping typed contracts, explicit permission gates, and auditable results.
See ROADMAP.md for planned capabilities.
Apache License 2.0. Copyright 2026 Cheng Cheng.