# Samōsya — technical portal

> Architecture, runtime and deployment notes for Samōsya: the client and server split, the native harness, the objects that carry work, the model gateway, the permission boundary, the execution trace and what a self-hosted deployment contains.

This portal documents the system as designed and the parts already observed working. It is the technical companion to the product site at https://samosya.com/ and the full technical text at https://samosya.dev/llms-full.txt.

- Technical portal: https://samosya.dev/
- Full technical content for LLMs: https://samosya.dev/llms-full.txt
- Product content for LLMs: https://samosya.com/llms-full.txt

## Architecture and runtime

- [Overview](https://samosya.dev/#overview): React/TypeScript client, Python/FastAPI server, a durable `/data` area and a single container as the default shape. Samōsya has its own runtime; OpenCode is a development tool, not a dependency at run time.
- [The interface](https://samosya.dev/#interface): real Workbench 0.9.1 captures with build and date; threads pinned to context revisions, run totals, inspector and budget guard.
- [Run lifecycle](https://samosya.dev/#runtime): request → effective configuration → context builder → provider call → tool proposal → permission guard → executor → persisted result; states from `queued` to `cancelled`, waiting as a state, recovery rules and fail-closed behaviour.
- [Object model](https://samosya.dev/#objects): Organization → Project → Thread → Session/Conversation → Run → Step, and the related Guild, Task, Decision, Artifact, Review, Approval and Trace objects.

## Model and tools

- [Model gateway](https://samosya.dev/#gateway): selects a concrete provider offering, not a marketing model name; model and thinking effort are coupled; effort is mapped per protocol, and the effective value is recorded.
- [Tools, skills and permissions](https://samosya.dev/#tools): atomic versioned tools with risk class and budget; the permission guard checks identity and grants before execution; a model cannot widen its own grant or approve its own operation.
- [Context and provenance](https://samosya.dev/#context): layers L0–L4, `owner_decision` / `source_evidence` / `working_hypothesis` / `generated_summary`, thread memory pinned to a revision, contradictions surfaced.

## Evidence and security

- [Execution trace](https://samosya.dev/#trace): event history, timeline and forensic trace; model and tool calls, timing, usage, exports with credential redaction.
- [Approvals and security](https://samosya.dev/#security): approval scoped to an operation or artifact version with an immutable fingerprint; least privilege; no default host socket; the owner's shell is not an agent grant. Vault is planned (stage 013).
- [Status and evidence](https://samosya.dev/#status): the seven status labels and the evidence record a verified claim must carry (release, commit, image digest, test, date, real or mocked, scenario, limits).

## Surfaces and operations

- [Files, Git and Consoles](https://samosya.dev/#surfaces): what is preview today (two-panel Files, Consoles without PTY/SSH) versus planned stages 008 and 009.
- [Integrations and MCP](https://samosya.dev/#integrations): designed scope for stage 013; no SDK or published endpoints exist, and none is documented as if it did.
- [Deployment and backup](https://samosya.dev/#deploy): one container, `/data`, SQLite with additive migrations, backup of the whole data area, rollback that restores the matching snapshot.
- [Roadmap](https://samosya.dev/#roadmap): stages 001–007 form the delivered foundation; 008–016 are next, each ending at an owner acceptance gate.
- [Design system](https://samosya.dev/#design): Soil and Daylight tokens, typography, contrast targets and the dodecahedron logo rules.

## Current limits

- No public container image, installer, API or SDK is published yet; distribution is planned with stage 016.
- Files and Consoles are interface previews without write, PTY or SSH.
- A screenshot shows an interface, not a runtime guarantee; verified claims rest on the release evidence record.