Getting started

Quickstart

Go from a task you want to confine to a reviewed policy and an enforced Warden run.

Maelys Sandbox Policy lets you describe what a program may reach before it starts. The JSON file is a manifest of permissions: it names readable and writable locations, the permitted network posture, and whether child processes must stay inside the same boundary.

This guide starts with a source-code audit: the tool may read the project, cannot modify it, cannot use the network, and cannot escape through a child process.

The idea in one picture

CODE

task you want to run
        │
        ▼
readable JSON manifest       "read this project, write nowhere, no network"
        │
        ▼
maelys-policy compile
        │
        ▼
portable policy.mir          exact normalized decision
        │
        ▼
Maelys Warden                enforces it when the process starts

The compiler does not guess permissions and does not launch the program. It turns a trusted, readable description into an immutable decision that Warden can enforce.

1. Install the compiler

PLATFORMInstall Maelys Sandbox Policy

Homebrew on Apple Silicon

brew install maelys-dev/tap/maelys-sandbox-policy
maelys-policy --version

2. Write your first manifest

Create audit.json:

CODE

{
  "$schema": "https://schemas.maelys.dev/mir-source/v2/schema.json",
  "formatVersion": 2,
  "filesystem": {
    "default": "deny",
    "rules": [
      { "access": "read", "path": { "special": "minimal-runtime" } },
      { "access": "read", "path": { "root": "workspace" } },
      { "access": "deny", "path": { "root": "workspace", "relative": ".env" }, "missing": "skip" },
      { "access": "deny", "path": { "root": "workspace", "relative": ".git" }, "missing": "skip" }
    ]
  },
  "network": { "mode": "none" },
  "process": { "treeConfinement": "required" }
}

Read it from top to bottom:

start with no filesystem access;
add the runtime files the executable needs to start;
allow reading the workspace;
hide .env and .git, even though the wider workspace is readable;
disable networking;
require every child process to remain confined.

workspace is symbolic: the manifest does not choose /Users/alice/project or /work. The trusted host binds it to the real project directory at execution time, so the same decision remains portable.

3. Compile the decision

CODE

maelys-policy compile audit.json -o audit.mir

On success the command is silent and writes audit.mir. On failure it writes a precise diagnostic to standard error and creates no usable policy.

4. Verify what was produced

CODE

maelys-policy validate audit.mir
maelys-policy inspect audit.mir
maelys-policy hash audit.mir

Expected forms of output:

CODE

valid MIR v2

CODE

{
  "inspectionFormatVersion": 1,
  "mirFormatVersion": 2,
  "filesystem": { "default": "deny", "rules": [] },
  "network": { "mode": "none" },
  "process": { "treeConfinement": "required" }
}

The real inspection contains your normalized rules. hash prints sha256: followed by the stable fingerprint of the exact binary decision.

5. Enforce it with Warden

CODE

maelys-warden run --plan audit.mir --receipt audit.receipt.json -- your-scanner .

Everything after -- belongs to the workload. Warden resolves the symbolic roots, selects an operating-system backend and refuses to run if the requested guarantees cannot be delivered.

Where to go next

Concepts explains source, decision, plan and enforcement.
JSON manifest documents every field and value.
CLI reference covers every command, output and exit status.
Playground lets you change several use cases without installing anything.