Skip to main content

​
How Consuelo OS works

Consuelo OS wraps agents with a safe portal into the workspace. The model is intentionally small. Agents get context through one entry point and run approved skills through another. The rest of the system exists to make those two things safe, observable, and useful.

​
The mental model

agent
  -> Consuelo OS portal
    -> get workspace context
    -> choose approved skill
    -> run skill
      -> script executes focused work
      -> structured data comes from API facades
      -> files become artifacts
      -> risky actions request approval
      -> execution is logged with a trace ID
The agent should never need to know every internal implementation detail. It needs a clear map of what it can do and a safe way to do it.

​
The portal

The portal is the boundary between the agent and the company. It answers two questions:
  1. What should this agent know about this workspace?
  2. What approved action should this agent run?
That is enough for the first product surface. More entry points would make the system harder to reason about and harder to secure.

​
Context flow

When an agent starts work, Consuelo OS should return useful steering:
  • workspace identity
  • product language and rules
  • available skills
  • capability health
  • artifact and storage mode
  • approval rules
  • recent or relevant context where appropriate
  • links to deeper docs or references when needed
Context should be useful, not exhaustive. The goal is to guide the agent, not dump the whole company into the prompt.

​
Action flow

When an agent runs a skill, Consuelo OS should:
  1. Validate the skill name and input.
  2. Check required capabilities.
  3. Create an execution record and trace ID.
  4. Run the script or workflow behind the skill.
  5. Request approval if the skill reaches a high-impact action.
  6. Create artifacts through the artifact layer.
  7. Return a structured result.
A failed skill should still return useful information: status, safe error message, trace ID, and the capability or validation problem when possible.

​
Data flow

Structured records are the source of truth. Skills should read workspace records through GraphQL/API facades instead of direct database access. Memory and vector context can help with retrieval, summaries, preferences, and prior decisions. They should not replace structured records when exactness matters.

​
Artifact flow

Skills should not write important outputs to random paths. They should create artifacts. An artifact record tells the workspace:
  • who created it
  • which skill created it
  • which execution created it
  • what source records were used
  • where the output is stored
  • whether it is draft, published, archived, or deleted
Local OS can store bytes locally. Cloud OS can store bytes in cloud storage. The artifact model should stay the same.

​
Approval flow

Approvals let a skill pause before a high-impact action. 
skill prepares action
  -> OS creates approval request
  -> human approves or rejects
  -> skill continues or stops
The approval belongs to OS, not to the agent process. The human decision should be persisted so the skill can resume later or be re-run with the approval reference.

​
Local and hosted runtime

Local OS should run without Docker. It uses Bun, SQLite, a local OS home folder, and one or more connected agents. Hosted OS should live inside the regular OpenSaaS deployment path first. It should use the same product model with cloud storage, app auth, hosted observability, and shared team access.