Selfware Protocol#

text

A file is an app. Everything is a file.

Selfware defines a unified file protocol for the Agent era: within the same distributable unit (a single file or a .self package), data, logic, and views MAY be bundled together; through distributed, decentralized Agent collaboration and self-contained human–machine interaction, it forms collaboration relationships between human↔Agent and Agent↔Agent; returning files to users so they never become obsolete and can evolve indefinitely.

Version: 0.1.0 (Draft)

License (Optional): MIT — you MAY modify, redistribute, and create derivatives.

text

Edition note (Non‑Normative): selfware.md and selfware.en.md are the v0.1.0 Draft bilingual editions of the Selfware protocol. We aim to keep them in sync; if you find a mismatch, please open an issue or PR.

Unless marked as “Non‑Normative”, this document uses RFC-style terms:

text

MUST / MUST NOT
SHOULD / SHOULD NOT
MAY

1. Canonical Data Authority#

Selfware does not require that a “protocol/app” must be authored as a single file. Instead, it requires that every Selfware instance explicitly declares and strictly follows its Canonical Data Source.

For a Selfware instance, the source of truth (Canonical Data) MUST come from exactly one of these two sources:

text

Local Canonical Data: within the instance’s content/ scope (the default write scope).
Remote Canonical Data: a remote data source explicitly declared in manifest.md (e.g., an http(s)/git pointer), with sync/cache/merge policy defined by the runtime (and still subject to No Silent Apply + rollback requirements).

Constraints (MUST):

text

Kernel, Views, Assets, Skills, etc. are runtime implementations and MAY be replaced or regenerated by an Agent.
Views MUST NOT become a source of truth (i.e., MUST NOT hardcode Canonical Data into view files as the only source).
Any action that changes Canonical Data MUST land within content/ (or an equivalent canonical landing scope declared by the manifest) and be rollbackable; remote changes MUST NOT be silently applied without user confirmation.

Compared to traditional software: traditional software usually separates “data” and “logic/view”, where logic and view are controlled by a small number of vendors via closed clients/services, creating a de‑facto monopoly over files and ecosystems. Selfware removes this monopoly by allowing data + logic + views to optionally live in the same file (or the same distributable package) and by enabling decentralized running and distribution. The protocol itself is optionally MIT‑licensed: you can modify, redistribute, and create derivatives. This is a unified file protocol for the Agent era.

2. Canonical Data#

In this demo, Canonical Data is:

text

content/selfware_demo.md (text/Markdown; read/edit/save from the front-end)

Notes:

text

content/ is the instance’s canonical data scope / default write scope. Collaboration, saving, merging, etc. default to writing here.
An instance MAY declare Remote Canonical Data in manifest.md as a fetch/sync source for its Canonical Data.

Remote Canonical Data (examples; examples only; not defaults):

text

Remote Canonical: https://floatboat.ai/selfware.md
Remote Canonical: git:https://github.com/floatboatai/selfware.md

Implementation constraints (MUST):

text

If Remote Canonical Data is enabled, the runtime MUST declare its policy (read-only / sync / merge) and MUST follow 6.3 No Silent Apply (disclose logic + summary/diff + rollback point + user confirmation).

Selfware allows Canonical Data to be any type (non‑exhaustive):

text

Text / Markdown
JSON / YAML
Binary (images, audio, video)
Database files (SQLite, etc.)
Code and project files
Office documents (docx, etc.)

An implementation MUST define the read/write shape of Canonical Data (text, byte stream, or a named resource set).

3. View as Function#

Any view MUST be treated as a function:

text

View = f(Data, Intent, Rules)

Where:

text

Data comes from Canonical Data
Rules are defined by this file (or extensions allowed by this file)
Views MUST NOT become a source of truth (i.e., MUST NOT hardcode Canonical Data into view files as the only source)

4. Runtime API#

The Kernel MUST bind to loopback only (localhost/127.0.0.1/::1) unless the user explicitly configures a wider boundary.

This demo’s API:

text

GET /api/content -> { "content": "<content/selfware_demo.md>" }
POST /api/save with { "content": "<content/selfware_demo.md>" } -> { "status": "success" }
GET /api/self -> { "path": "...", "sha256": "...", "content": "<content/selfware_demo.md>" }
GET /api/manifest -> { "content": "<manifest.md>" }
GET /api/capabilities -> runtime capability declaration (see 4.1)
GET /api/check_update?url=... -> check whether a remote protocol source has updates (see 6)

Write boundary (MUST):

text

POST /api/save MUST only write within content/ (canonical data scope)
The runtime MUST NOT write selfware.md unless the user has explicit intent and confirmation

4.1 Capability Declaration#

The runtime MUST declare its capabilities so users and other Agents can understand boundaries and interaction.

The declaration MUST include at least:

text

write_scope: where writes are allowed (in this demo: content/)
confirmation_required: actions that require user confirmation (e.g., pack, pull/merge, apply update, publish, send context)
endpoints: available endpoints and their purpose (content R/W, update checks, packaging, etc.)
modules: optional module status (e.g., whether git/discovery/self‑analysis is supported/enabled)

The declaration MUST be exposed via at least one carrier:

text

Machine-readable (e.g., GET /api/capabilities)
Human-readable (e.g., printed on startup, or a UI panel)

Interaction constraints (MUST):

text

If the runtime/Agent discovers “a capability is supported but not enabled / missing config / has multiple strategy branches” (e.g., enabling remote collaboration, enabling Discovery, performing publish, recording runs), it MUST ask the user and obtain explicit confirmation before performing any action that produces writes or outbound communication.
Any writes/applications triggered by such prompting MUST still satisfy: write scope (content/) and Change Record requirements.

5. Discovery#

Example Discovery endpoint (example only; not a default):

text

https://floatboat.ai/discovery/
https://github.com/awesome-selfware/awesome-selfware (a GitHub index repo for discovering Selfware/Skills/Practices ecosystem entries)

Goal: with user permission, carry “intent + partial context” to discover better solutions (not just search).

A Discovery request SHOULD include:

text

Intent: the current goal (e.g., update, recommend, fix_overflow, export_cards)
Partial Context: the smallest directly relevant info set, e.g.:
    goal
    state / progress
    logs (optional; MUST be trimmable and redactable)

Permissions (MUST):

text

Any Discovery request that includes context MUST be sent only with explicit user consent.
By default, it SHOULD send only the minimal necessary context; higher-granularity context MUST require additional authorization.

Discovery responses MAY return (non‑exhaustive):

text

a better Selfware (a complete solution file/template)
one or more Skills (reusable workflows)
code snippets / patch suggestions
other artifacts consumable by Agents (rule fragments, view templates, configs, etc.)

Discovery trigger points (runtime SHOULD; but MUST support explicit user trigger):

text

On Start
On Explicit Update Intent
On Missing Capability
On Error Recovery
On User Request

6. Official Protocol Source & Updates#

6.1 Protocol Source#

This file MAY declare an “official protocol source” (for update checks only; does not override local authority):

text

Protocol Source: https://floatboat.ai/selfware.md
Protocol Source (GitHub): https://github.com/floatboatai/selfware

6.2 Update Check#

If update checking is enabled, the runtime MUST check at one of:

text

On Start (every run), or
On User Request

Checks SHOULD use ETag/Last‑Modified or content hashes. This demo provides /api/check_update and a diff summary.

6.3 No Silent Apply#

If an update is detected, the runtime MUST:

text

Explain the update logic (where it’s fetched from, how it’s compared, how it’s applied, how to roll back)
Provide an update summary (at least title + summary; provide changelog/diff if available)
Ask for user confirmation (Accept/Reject/Defer)
Apply only after Accept; Reject MUST keep the current version runnable

7. Local Versioning (Git)#

Selfware local files SHOULD use Git for versioning (local repo is sufficient; remote optional):

text

Before applying any update (official source, Discovery, or collaboration backend), the runtime SHOULD create a rollback point (prefer Git commit/tag; otherwise backups).
Any “auto pull/merge remote” behavior MUST follow 6.3 (No Silent Apply).

8. Collaboration (Git / Custom)#

Beyond local versioning, Selfware MAY configure a collaboration backend for multi‑person sync. The backend does not change the definition of selfware.md as protocol authority. Writes land in content/.

8.1 Git Collaboration#

An instance (especially content/) MAY collaborate via Git (remote optional, e.g. GitHub):

text

Collaboration: git
Remote: <git remote url>
Ref: <branch|tag|commit> (optional; default main/master is implementation-defined)

If Git collaboration is enabled, the runtime MUST:

text

Check whether remote has updates on On Start or On User Request (implementation MAY choose one, but MUST support explicit user trigger).
If updates exist, follow 6.3 No Silent Apply before pulling/merging.
Create a rollback point before merge (prefer Git commit/tag; otherwise backups).
If conflicts occur, stop automatic apply and ask the user for a resolution strategy (manual/assisted/abort).

8.2 Custom Collaboration#

Selfware MAY use a custom collaboration service:

text

Collaboration: custom
Endpoint: <service url>

Regardless of backend:

text

write boundaries MUST remain (only write to content/ or an explicitly allowed subset)
any sync/merge that changes local selfware.md MUST be preceded by user confirmation and explanation (per 6.3)

9. Packaging (.self container)#

9.1 Container Format#

A .self file MUST be a ZIP container (compatibility first; it must be unpackable by standard unzip tools).

Inside, it MUST include:

text

self/manifest.md

self/manifest.md MUST include at least:

text

Selfware-Container: zip
Selfware-Container-Version: 1
Protocol-Source: https://floatboat.ai/selfware.md (example; replaceable)
Local-Protocol-Path: selfware.md
Canonical-Data-Scope: content/

The protocol MAY evolve to new container types/versions; implementations MUST handle compatibility via Selfware-Container-Version or fail explicitly.

9.2 Pack Policy#

Packing is writing a Selfware project directory into a .self container. Implementations MUST:

text

Declare pack scope: include/exclude rules (glob or explicit paths) and define a minimal required set.
User confirmation: before writing the .self, MUST show:
    final included file list (or tree) and total size
    exclude rules summary (and key excluded items)
    output target path (*.self)
    and allow Accept/Reject.
Write boundaries: pack MUST NOT modify selfware.md. If self/manifest.md is generated, generate it inside the container without writing back to the repo (unless user explicitly requests).

Default excludes (SHOULD as a safety baseline; instances MAY override/extend):

text

.DS_Store
__pycache__/, *.pyc
node_modules/, .venv/
dist/, build/
output/, *.log, *.tmp
.git/ (unless user explicitly includes)

9.3 Pack Plan Placement#

The pack protocol (format + policy) is defined by this file.

An instance’s “pack plan” SHOULD live in an instance self-description file (e.g., manifest.md, or a dedicated section inside Canonical Data) to:

text

avoid locking into a repo structure
allow different instances to declare different include/exclude/required

This demo places its pack plan in manifest.md.

9.4 Sharing / Distribution#

To share a Selfware project, you SHOULD pack the whole directory into a ZIP and name it with a .self suffix (e.g., my_project.self).

Benefit: you share a “living document / living app”. If the receiver is a trusted collaborator and has access to the collaboration backend within your permission boundary (e.g., GitHub repo access), then when they open the Selfware they can check for updates and, after user confirmation, pull/merge to stay aligned with the latest version.

10. Memory (Optional)#

Memory is a set of auditable context files maintained under content/, used to:

text

record conversations, decisions, changes, and run traces
support collaboration and retrospection (humans and Agents)
provide minimal necessary context for Discovery/update decisions, with user permission

Memory MUST NOT become the protocol authority; the protocol authority is selfware.md.

10.1 Placement#

If enabled, instances SHOULD use:

text

content/memory/

Implementations MAY use a single file (e.g., content/memory.md), but a multi-file structure is better for permission splitting and minimization.

10.2 File Self‑Description#

Each Memory file MUST include metadata at the top explaining “who I am / what I record / how to update me”.

Two allowed formats:

text

YAML front matter (recommended; still Markdown):

---

selfware: role: memory_chat | memory_changes | memory_decisions | memory_runs | custom title: "..." purpose: "..." scope: "what is included / excluded" update_policy: "append_only | editable | generated" owner: "user | team | agent" created_at: "YYYY-MM-DDThh:mm:ssZ" updated_at: "YYYY-MM-DDThh:mm:ssZ"#

text

A ## Meta section (same fields; key-value lines).

10.3 Change Metadata#

For any change to any instance file (including content/, views/, server.py, manifest.md, etc.), the implementation MUST record a Change Record to content/memory/changes.md (or an equivalent location).

Each Change Record MUST include at least:

text

id (unique)
timestamp
actor (user / agent / service)
intent
paths (affected file list)
summary (human-readable)
rollback_hint (how to roll back: git ref / backup / manual steps)

If Git is used locally, rollback_hint SHOULD point to a concrete Git rollback point (commit/tag/ref).

10.4 Discovery Consent & Minimization#

When Discovery carries context, Memory MAY be selectively referenced, but MUST:

text

be sent only with explicit user consent
default to minimal fragments (e.g., decision/change summaries rather than full runs/logs)
support trimming and redaction

11. Ecosystem (Optional)#

The Ecosystem module defines how Selfware-related artifacts (skills, practices, selfware files, patches) are described, distributed, published, and consumed—without requiring a single centralized vendor.

11.1 Artifact Metadata (MUST be self-describing)#

An artifact MUST carry metadata including at least:

text

id
title
type (e.g., selfware / skill / practice / patch / view / template)
version
protocol_version_range (compatible Selfware protocol versions)
applies_to (scope/platform/runtime)
license
sha256 (content hash for verifiability)
provenance (how it was derived; may include hashes)
distribution (one or more distribution entries: hosted URL, index pointer, git url+ref, etc.)

Optional fields (MAY):

text

trust (signing/publisher/verification info; not required, but implementations SHOULD be able to use it for local trust policy)

distribution constraints (MUST):

text

MUST include at least one resolvable “fetch hint” (e.g., URL or git: pointer)
MUST be human-readable, but SHOULD follow machine-extractable prefix conventions

Recommended distribution prefixes (SHOULD):

text

hosted: hosted content URL
index: index entry URL
git: decentralized pointer (e.g., repo#ref=...:path=...)
sha256: explicit hash (same as metadata sha256)

sha256 rules (MUST):

text

MUST be the SHA‑256 of the artifact content that is fetched and applied (lowercase hex).
If distributed as hosted text: hash UTF‑8 bytes (no implicit rewrites).
If distributed as zip/binary container: hash the container bytes.

11.2 Publish & Consume Boundaries#

Publish:

text

Before pushing local know‑how to any external destination (host/index/git), the runtime MUST obtain user confirmation.
Publish MUST write a Change Record (see 10.3), including where/how it was published and rollback strategy.

Consume:

text

Discovery MUST return a candidate artifact list + metadata; it MUST NOT silently apply anything.
Runtime/Agent MUST let the user (or their delegate) choose, and then follow 6.3 No Silent Apply (logic + summary/diff + rollback point + user confirmation).

11.3 Ecosystem Repo Convention (SHOULD)#

For decentralized ecosystem building and indexing, ecosystem repos SHOULD use top-level directories:

text

selfware/
skills/
practices/

This convention is for “ecosystem repos” (publishing/sharing repos), not mandatory for normal .self instances.

12. Self‑Analysis (Optional)#

Self‑Analysis is an optional module that extracts know‑how from an instance’s progress and changes, and—under user permission—closes an evolution loop with Discovery/ecosystem publishing.

This chapter defines only protocol boundaries and outputs; implementation details are runtime-specific and replaceable.

12.1 Inputs#

Self‑Analysis MAY read (non‑exhaustive):

text

Canonical Data (e.g., content/selfware_demo.md)
Memory files (e.g., content/memory/changes.md, content/memory/decisions.md) if enabled
manifest.md (pack plan, runtime conventions)
runtime files (e.g., server.py, views/) for consistency/boundary scanning

Self‑Analysis MUST respect write boundaries: it MUST NOT bypass the protocol to write selfware.md; any writes MUST land within the instance’s allowed scope (in this demo: content/).

12.2 Outputs (MUST be file-based)#

Self‑Analysis outputs MUST be materialized as files, auditable and rollbackable. Outputs MAY include:

text

insights (conclusions and executable recommendations)
drafts of practices/skills/selfware/patch artifacts (for local review before publishing)
discovery request drafts (intent + minimal context)
publish queues (artifact list with sha256 and distribution drafts)

Any output writes MUST be recorded as Change Records (see 10.3).

12.3 Consent & Loop#

Self‑Analysis may trigger Discovery or publishing, but MUST:

text

obtain explicit user consent before sending anything to external endpoints
default to minimal necessary context (and allow user selection/trimming)
apply updates only via 6.3 No Silent Apply

12.4 Trigger Freedom#

Trigger points are implementation-defined (On Start / On User Request / On Significant Change, etc.). The protocol requires:

text

MUST support explicit user trigger
MUST record key actions and rollback points (via Change Records)

Non‑Normative#

In this repository, views/, server.py, assets/, skills/ demonstrate a minimal loop: the same Markdown projected into multiple views + saved back.

The content/ directory is demo instance data (fixtures/experiments) and is the instance’s Canonical Data write scope, but it is not the protocol authority (the protocol authority is selfware.md).