faramesh apply

faramesh apply is the production command. It runs check, compiles governance.fms to a deterministic AST, downloads any registry-imported provider binaries (verifying signatures), starts the daemon (or hot-swaps policy if it's already running), and writes the artifacts that drive the agent supervisor and the OS-tier sandbox.

After apply, the daemon is the only thing trusted to enforce policy on this host. governance.fms is read once at apply time; the daemon does not re-read it between applies.

Usage

faramesh apply [--dir DIR] [--force] [--check-uid] [--require-uid-separation] [--stop]

What happens, in order

1.  faramesh check        (parse + type-check)
2.  resolve registry imports + verify signatures
3.  download provider binaries (idempotent, cache-aware)
4.  compile governance.fms → .faramesh/policy.bin
5.  write .faramesh/runtime/agent.env
6.  write .faramesh/bin/agent (launcher)
7.  write .faramesh/runtime/cli.path
8.  start (or hot-swap) the daemon
       ├─ STARTING
       ├─ INITIALIZING (open WAL, replay, init providers, verify DPR chain)
       └─ READY → socket opens → SDK calls evaluated
9.  optional: agent supervisor launches runtime { supervised_command }
10. optional: lock governance.fms (chattr +i / uchg) if immutable_config = true

apply is idempotent. Running it twice with no policy change is a no-op (it returns immediately after step 4 once it sees the AST hash hasn't changed).

After apply, start your agent

You have two options:

Option A. Generated launcher

apply writes .faramesh/bin/agent for you:

.faramesh/bin/agent -- python your_agent.py

The launcher loads .faramesh/runtime/agent.env, applies the OS sandbox if configured, strips ambient credentials, and execs your command. You don't need to remember any flags.

Option B. Daemon-supervised agent (recommended)

Set runtime { supervised_command = "python your_agent.py" } and the daemon launches the agent itself after reaching READY:

runtime {
  os_tier                   = true
  agent_enforce_profile     = "full"
  supervised_command        = "python your_agent.py"
  strip_ambient_credentials = true
}

faramesh apply
# That's it — the daemon starts the agent for you with the sandbox applied.

→ Detail: Architecture: agent supervisor and OS-tier sandbox.

Runtime fields that change apply behavior

→ Full table: Stack reference → runtime.

Output

$ faramesh apply
✓ governance.fms valid
✓ governance.fms compiled
✓ providers verified (vault, kms, splunk)
→ runtime started (pid=42189)
→ Unix socket: /Users/you/.faramesh/runtime/faramesh.sock
→ agent launcher: ./.faramesh/bin/agent -- python your_agent.py
→ OS tier: Seatbelt sandbox-exec (runtime { os_tier = true }) via .faramesh/bin/agent
→ config locked: ./governance.fms

Stopping the daemon

faramesh apply --stop

This sends SIGTERM, waits for clean shutdown, removes the runtime socket, and clears the supervisor's child PIDs. If the daemon is supervising an agent, that agent receives SIGINT first.

If the daemon doesn't exit cleanly within the timeout, --stop will report it and leave you to resolve manually. The daemon's PID is in ~/.faramesh/runtime/daemon.pid.

Hot-swap (reapply)

Running faramesh apply while the daemon is already running performs an atomic AST swap:

1. Parse and compile the new governance.fms.
2. Validate that every referenced provider and identity resolves.
3. Replay history against the new AST (same as plan).
4. If validation passes, swap the in-memory AST in a single pointer write.
5. Persist the new policy version into the WAL with a hash so audit verify continues unbroken.

In-flight calls that have already passed step 3 of the pipeline finish under the old AST. New calls see the new AST. There is no window where some rules are old and some are new for the same call.

Failure modes

apply always fails closed. A failed apply leaves the previous policy enforcing, never an empty AST.

What's next

• Architecture: daemon lifecycle, supervisor, sandbox.
• faramesh status: confirm the daemon is READY and providers are healthy.
• faramesh plan: preview before apply.
• From dev to production: full migration guide.