Crystal AgentOS Community Edition

A local, documentation-first foundation for agents and the people who direct them.

AgentOS gives a project a repeatable path from its current state to a verified change: project dossier → roadmap → documented stage → implementation → checks → updated documentation. A short intake selects only the relevant document layers. The CLI keeps the task, source, documents and check evidence bound to the same stage; ordinary read-only questions bypass intake entirely. Native hooks are excluded; explicit CLI checks do not intercept arbitrary tools.

This is the canonical public repository: crystalstrategysup-prog/agent-os. This source declares candidate 0.8.0rc2 (Python distribution version 0.8.0rc2). It is a local publication candidate until the canonical tag, release object and uploaded assets are independently read back. It is separate from any maintainer's private runtime, infrastructure and personal data.

Visit the public project website, read the changelog, or open an issue with a bug or technical review. Verify tag, release asset and website deployment separately.

Indexed results library

Stable 0.7.1 includes the reviewed indexed results, coordinator and model-policy source contracts. Read the indexed results format and limits. Source implementation is separate from live installation; physical session cleanup is not implemented.

Related MCP server: Mobile MCP Command Bridge

Two physical layers

See Foundation ↔ Overlay for versioning, conflicts and recovery. Project documents remain in their projects; the overlay indexes them without copying every project into the core. Project lifecycle records in a project's .agentos/ directory are a separate local state surface and are excluded from public source exports.

Profiles are optional files under the user overlay. agentos profiles inventory reports their hashes and overlaps; profiles select activates none, one, or all in an explicit order. Conflicting values need an owner choice. profiles interview prefills observed device facts and asks about missing user fields. Editing or removing a profile leaves the installed foundation unchanged.

Source verification and installation

Python 3.11+ is required. Review the exact source and diff, run the local tests and compare package resources before integration. A version string alone does not prove publication or activation. See Install and update for the separately authorized offline flow, overlay preservation and no-hook rollback. No global hooks, model/auth or client security changes are part of this release.

Ordinary read-only requests

Answer questions, search, inspect code and discover authorized API capabilities directly. No registration, answers file, profile interview, observe receipt or closeout is needed. Optional agentos workflow route --kind audit explains the route without reading overlay or changing files; calling it is not a prerequisite for answering a question.

Connection scenarios

The public foundation includes an indexed catalog of versioned connection scenarios. agentos setup list shows the available scenarios; agentos setup show telegram-owner-inbox opens the owner file inbox card. The catalog covers Telegram MTProto, Telegram Business, owner file inbox and SSH/VNC over SSH. All cards are guide_only: the commands return guidance and do not connect to devices, log in, create bots, grant rights or read user secrets. The SSH/VNC card starts with a known route and distinguishes transport from authenticated access. An interactive installer or provider adapter requires its own implementation and authority. See the authoring and maintenance protocol and the index.

For one existing SSH alias, agentos setup probe ssh-vnc --host ALIAS plans without network access; --apply checks authenticated SSH and optional RFB transport with a temporary private forward. It leaves VNC login and the desktop frame unverified. See the tested field procedure.

Work continuity

The work-continuity guide and packaged passport template help a user preserve a compact index of active projects, current handoffs, source and data locations, and recovery checks. A filled passport is private user knowledge. The template does not back up databases or prove that a cloud copy can be restored.

Instruction routing

Keep inherited project AGENTS.md short: define its scope, universal limits and links to the project documents or skills that explain each topic. Read detailed material only when the task requires it, and verify dated status against current source or runtime evidence. A size target such as 4 KiB is editorial guidance, not an entry or read-only gate. Reorganizing instructions is a separate project change; a read-only request does not authorize that edit. The public foundation stays host-neutral; owner and host details belong in the separate user overlay. See architecture and process.

Start a project task

agentos project questions --root /absolute/path/to/project
agentos project init --root /absolute/path/to/new-project --name Example \
  --type platform --feature public --context context.json
agentos project enter --root /absolute/path/to/project \
  --session ACTUAL_SESSION --turn ACTUAL_TURN --answers answers.json

questions shows verified project context and only missing supplied answers. Same-scope --resume-task reuses previous answers except current authority; enter --reuse-answers makes that reuse explicit. JSON inputs accept - for stdin. The required documents depend on project type and changed surfaces. A new project starts with a dossier and roadmap; every product stage has its own contract and acceptance checks before code changes. ready rejects draft or stale documents. check, assess and close require current source-bound evidence plus named semantic review. Optional audit recording uses project observe; ordinary investigation needs no receipt. project verify-closeout checks whether a CLOSED result still has current evidence. The process, documentation catalog and synthetic example show the full flow.

Interfaces and boundaries

• The stdio MCP server exposes six narrow planning/status tools. tools/list includes versioned input and output schemas; it does not expose arbitrary shell, SSH, file contents or credentials. See MCP contract.

• The CLI contract, data schemas and contracts guide describe the machine-readable surfaces. No HTTP server is provided, so OpenAPI is not applicable to this release.

• Codex AGENTS and namespaced skills can be integrated while preserving other owners' content. No native hooks are created or restored. Read back effective instructions in a fresh client session; do not claim a universal tool sandbox.

• The optional Telegram Session Hub remains owner-allowlisted and disabled by default. Read compatibility before replacing any existing connector.

• Existing model routing, current-evidence result assessment, Full Inventory and update advisory remain available through the CLI. Their contracts and limits are in architecture, result evidence, Full Inventory and update checks.

• The Codex in-app Browser and Chrome remain separate documented surfaces; see browser surfaces. The optional Telegram onboarding plan does not require a website or transmit credentials to this repository.

Develop and verify

python -m pip install -e '.[dev]'
python -m pytest -q
python tools/demo_lifecycle.py
python tools/verify_public.py

Start with the documentation index, project dossier, roadmap, public workflow, source release contract, architecture and developer onboarding. The changelog, release policy and public language policy state the release status and limits. GitHub Actions are not used.

Crystal AgentOS is Apache-2.0 software. Contributions and skeptical technical reviews are welcome; see Contributing, Security, Governance and the AI Stewardship Charter.

For current project handoff lookup, follow the handoff discovery contract and verify the selected index. Filled task handoffs remain outside the public source.

The 0.7.1 release package includes reviewed opt-in adapters and operator gates. It provides no running scheduler or persistent connected bridge. Host activation, manual client reload, voice validation and owner-policy adoption remain separate authorized stages.

The historical RC3 candidate packages metadata-only tracked directory aliases. Its inherited behavior has bounded predecessor coverage; the final stable artifact must be reviewed independently. This candidate does not claim an installed, running or published runtime.

Historical main coordinator candidate 0.7.0rc2

Use the single coordination knowledge index and work-management contract. The optional synchronous Python ledger records verified receipt/review/remainder/next ownership, protects original parent acceptance and reconciles missed results/unknown effects. It launches nothing. Private persona/owner knowledge stay outside core; live adoption, publication and session cleanup remain separate.

Guarded session launch in 0.7.1

Qualified creation now reads the exact approved Codex binary's inherited configuration and bounded model catalog before creating a thread. Actual startup metadata and harmless tool probes precede original work. Persistent GNU Screen retains the same worker, connection and thread after its caller exits. Selected context materialization returns verified document bodies; it does not prove compliance. Existing clients and private owner instructions require separate adoption. No model, provider, auth, sandbox, approval or native-hook setting is changed.

Completion and safe recovery candidate

The completion guide describes explicit bounded continuation, receiver fencing, independent acceptance, verified handoff and checkpoint recovery on the existing Coordinator store. This candidate does not install a scheduler or hooks. Only the scoped local POSIX registered-command adapter is qualified; remote/cloud completion and Goals activation require separate actual adapter qualification. The owner runtime and already-open sessions do not adopt source changes automatically.