Samosya Layout presets
Conversation, Planning, Development and Review are presets of one workspace, not separate applications. Splits are resizable and restorable per user and project.
Technical documentation · v0.1
Samosya — architecture, integrations and runtime model
One server container, one durable data area, one thin web client. Below: the system model, the module catalogue, the integration points, and the deployment status — separated from the planned scope.
Samosya-core
Ubuntu 24.04.5 LTS
Docker · single container
Web GUI / PWA
Data: /data
Architecture
Server–client, with state on the server
The client renders state and sends intent. Sessions, tasks, agents, consoles and checkpoints live in the server container, independently of the user's connection.
People · owner · team
Desktop and mobile browser · installable PWA. No local AI engine; browser permissions are respected, not bypassed.
↓ intent / state
Samosya Web GUI
Conversations · Tasks · Code · Knowledge · Review · Consoles · Guild Designer · Skills · Inspector
↓ API · real-time updates
Samosya Server · single container · Ubuntu LTS · Docker
Agent Runtime
Sessions & Tasks
Skills Engine
Knowledge & Canon
Model & Context
Budget Guard
Integrations / MCP
Vault & Permissions
Files & Consoles
Review & Events
Persistent data · /data — sessions · tasks · documents · skills · artefacts · checkpoints
↓ outbound, policy-controlled
Forgejo / Git
Repositories and pull requests
Cloud / MCP / OAuth
Models and external services
Host / workers
Optional execution environments
Reference architecture for the v0.1 scope. The diagram describes intended responsibilities, not confirmed deployment of every module.
Execution model
Durable queues, checkpoints, explicit states
intentA user request enters a session and is bound to a task within the actor's permissions.
planA coordinating agent splits the work, creates delegations and declares dependencies.
runExecution uses skills and tools; progress is reported without invented percentages.
checkpointState is persisted at a controlled point; resumption starts from a safe state.
reviewThe result is submitted with evidence: artefacts, commits, tests, cost, sources.
Closing the browser does not stop the work. A container restart does not imply automatic replay of a process — checkpoints and retry policy govern that.
Object model
One shared conceptual model
Every module uses the same identifiers. There is no parallel registry of projects, tasks or artefacts.
| Object | Meaning |
|---|---|
| Organization | Environment owner, users and global rules |
| Project | Work area with its own goals, knowledge, tasks and resources |
| Guild | Configured team of agents and the rules of collaboration |
| Agent | Role or execution instance with defined competences, model and permissions |
| Session | Durable conversation between people and/or agents |
| Task | Unit of work with goal, scope, ownership and state |
| Plan / Release | Ordered set of goals, stages, tasks and dependencies |
| Run | A concrete execution by one or more agents |
| Knowledge Item | Document, rule, specification, decision or source material |
| Skill | Reusable method for performing a piece of work |
| Integration | Connection to an external system or service |
| Credential / Grant | Secret and the permission to use it |
| Artifact | Result: file, code, report, screenshot, recording |
| Review | Control and decision on a result or change |
| Budget | Limit and consumption history for resources |
| Console | Durable interactive terminal session |
Modules
Twenty modules, one responsibility each
| Module | Responsibility | GUI surface |
|---|---|---|
| 5.1 Guild Hall | Organisation, projects, models, global budgets, policies | Guild Hall, global header |
| 5.2 Project Workspace | Durable project space and working context | Workspace, project switcher |
| 5.3 Sessions | Parallel conversations, delegation from the conversation | Conversation tabs, composer |
| 5.4 Guild Designer | Roles, models, skills, permissions, autonomy | Guild editor |
| 5.5 Agent Runtime | Execution, delegation, checkpoints, retries | Guild Flow, Activity Inspector |
| 5.6 Tasks & Planning | Goals, roadmaps, tasks, dependencies, acceptance criteria | Tasks, board, plan |
| 5.7 Knowledge | Documents, versions, sources, relations | Knowledge Explorer |
| 5.8 Canon | Binding rules, source hierarchy, contradictions | Canon, approvals |
| 5.9 Skills Engine | Create, test and version skills | Skills Library |
| 5.10 Prompt Composer | Prompts, dictation, refinement, attachments | Composer |
| 5.11 Voice & Whisper | Recording, transcription, editing, task from transcript | Microphone, transcript editor |
| 5.12 Context Manager | Context window, sources, compaction, checkpoints | Context Inspector |
| 5.13 Model & Budget | Providers, models, cost, limits and blocks | Budget Inspector |
| 5.14 Files, Code & Forgejo | Files, Git, commits, diffs, history | Code Explorer |
| 5.15 Review & QA | Verification, evidence, approval, correction requests | Review Room |
| 5.16 Consoles | Durable PTY sessions on the server | Terminal, console tabs |
| 5.17 Integrations & MCP | Connections, tools, grants, usage history | Integration Center |
| 5.18 Identity & Vault | Users, roles, secrets, OAuth, audit | Vault, Access Inspector |
| 5.19 Notifications | Decisions, blocks, budgets, reports | Owner Attention |
| 5.20 System Administration | Services, data, backups, updates, workers | System, diagnostics |
Integrations
Points of contact with the outside
| System | Scope | Access model |
|---|---|---|
| Forgejo / Git | Repositories, commits, PRs and review without leaving the app | Default repository integration; Samosya does not replace the Git server |
| Model providers | Models assigned to roles; tokens, cost, budget | Credentials in the vault, grants per agent |
| MCP | MCP client and server; tool registry and usage history | Tools exposed under policy |
| Google Workspace | Sign-in and services through OAuth | Consent scope visible and revocable |
| External APIs | Task, documentation, mail and calendar systems | Connections configured in Integration Center |
| Workers / host | Remote execution environments | Separately authorised, optional |
Rule: an agent does not receive every secret in the organisation, and a skill cannot widen its own permissions.
Interface model
Two navigation levels, one operating surface
Guild Hall configures the environment; the Project Workspace is where the work happens. Both use the same objects, so a reference in a conversation opens the real task, file or review.
LeftSessions · consoles · pinned places · workspace state
CentreConversation, task, code, document, review or terminal — tabs and splits
RightInspector: context, budget, activity, approvals, sources
Durable panels
Closing a tab does not end an agent, a run or a console. Hidden panels stop polling — state is reconciled from the server when shown again.
Status semantics
Running, waiting for a decision, paused by budget, failed and reconnecting are distinct states with explicit meaning — never one spinner.
Deployment
One container and one durable volume
The product is a standalone Docker image based on Ubuntu LTS. Installation does not require a separate Compose stack — application components run as processes of the same product.
Target distribution channels: Docker on Ubuntu Server, Unraid Community Applications, manual installation from an OCI registry.
# target runtime model (image not published) docker run -d --name samosya-core \ -p 8080:8080 \ -v /mnt/user/appdata/samosya:/data \ <samosya-core-image> # durable state: settings, projects, knowledge, # sessions, skills, artefacts, costs, checkpoints
Requirements
Linux with Docker; Ubuntu Server as the reference environment. Resources depend on parallel runs and model choice.
Data
A single /data volume. Updating or recreating the container must not lose data; backup and migration are supported.
Access
GUI and API through the browser; PWA as an application window. OAuth for external providers is planned.
Port, image tag and registry name are provisional — the v0.1 specification leaves them to be decided (§14).
API and MCP
Interfaces are not published yet
Server API
The web GUI consumes the server API and a real-time update channel. API version, resource shape and compatibility policy remain open (§14). We do not publish a contract that does not exist.
MCP
Samosya is specified as both an MCP client (external tools) and an MCP server (its own capabilities). Connection registry, grants and usage history belong to Integration Center.
Until an API is published, the integrations above describe intended scope, not an available SDK.
Distribution
No public artefact yet
No image, installer or package is published until an official distribution channel exists. Planned forms below — without dates and without promises.
OCI registry
samosya-core image with version tags and a stable channel.
Unraid CA
Application template with /data volume and port mapping.
CLI configurator
Installer and configurator for Ubuntu Server, with diagnostics.
Status
What exists and what is planned
| Area | State | Note |
|---|---|---|
| Core container | Running | Ubuntu 24.04.5 LTS, Docker; environment bootstrap |
| Object model and modules | v0.1 scope | Twenty modules; implementation order is iterative |
| Server API | Not published | Version and contract to be decided (§14) |
| MCP | Designed | Client and server in scope |
| OCI image / installer | None | Distribution channels planned |
| Review and evidence model | Defined | Approval bound to a result version, not to a message |
Product success criterion: define a goal, configure a team, grant the right knowledge and permissions, delegate the work, close the browser, and return to a clear picture of actions, results, decisions and costs — in one environment.