Learn the model

Concepts

The mental model behind manifests, canonical decisions, host plans and enforcement.

Sandboxing starts with a deceptively simple question: what must this program be able to reach to do its job, and what should remain impossible?

Maelys separates the answer from the operating-system mechanism. You describe one boundary; a later layer proves whether Seatbelt, Bubblewrap, Apple Container or another backend can honor it.

Four objects, four responsibilities

Object	Written or produced by	Purpose
JSON manifest	human, configuration compiler or policy engine	readable security intent
MIR decision	`maelys-policy` or the C builder	canonical, portable and hashable decision
SandboxPlan	Sandbox Policy plus trusted host context	paths and required capabilities resolved for one host
Execution plan and receipt	Warden	concrete launch mechanics and evidence of the outcome

CODE

human intent             portable truth              host-specific action
     │                         │                              │
JSON manifest ──compile──► canonical MIR ──resolve──► SandboxPlan ──► Warden

None of these layers silently invents missing permission. If a requested guarantee cannot be represented or enforced, the pipeline stops.

Begin closed, then open narrowly

Filesystem policy is always deny-by-default. A useful manifest usually follows this pattern:

allow the minimal runtime needed to start the executable;
allow reading the input tree;
allow writing only a dedicated output tree;
add explicit denies for secrets within broader readable trees;
choose none, mediated or direct networking;
require confinement of the complete process tree.

Write access implies read access. For the same target, conflict resolution is deny over write over read.

Symbolic roots make one decision portable

The manifest normally uses three roots:

workspace: the project or working tree selected by the trusted host;
temp: a private temporary area selected by the host;
minimal-runtime: the operating-system files required to load and start the program.

The JSON does not hard-code where these roots live. Warden can therefore apply the same MIR decision to a macOS workspace, a Linux namespace or a container environment without changing its meaning.

An absolute host path is supported for trusted deployment policy, but it deliberately sacrifices portability.

Three network postures

Mode	Meaning
`none`	the workload requires no network channel
`mediated`	connections must pass through an enforcement service and match explicit TCP destinations
`direct`	ambient network access is part of the decision

mediated is not merely documentation. The destination list is included in the decision fingerprint and Warden must refuse the policy if no compatible mediator is available.

The manifest is a decision, not a rule engine

The source says what has already been decided:

CODE

{ "protocol": "tcp", "host": "github.com", "port": 443 }

It does not express conditions such as “allow GitHub when this project is trusted.” Resolve such rules in Maelys Datalog or another policy decision point, then emit the concrete manifest or build MIR through the C API.

Useful mental model

Maelys Sandbox Policy is the contract compiler. Warden is the enforcer and supervisor. Netd is the mediated network engine. Datalog is an optional decision frontend.