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 0.5.5 (Python distribution version 0.5.5). 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.

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.

Related MCP server: Mobile MCP Command Bridge

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, current source stage, 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.

Current project handoff: docs/agentos/HANDOFF.md.