The runtime model · files, sessions, and live MCP

How AgentStack actually runs.

The examples show what to write. This page shows how it behaves: the three ways capabilities reach an agent, when a profile takes effect, why session end exists apart from Ctrl+C, and which policy layers block at runtime versus only fail a check.

One product, two delivery mechanisms

AgentStack can compile intent into a CLI's native files, or serve capabilities live through its MCP gateway. Native-file changes normally take effect when the CLI launches; the gateway can discover and load capabilities during a running session.

1 · How capabilities reach the agent

Choose a delivery mode and a lifetime

A profile answers “what is allowed for this kind of work?” The delivery mode answers “how does it reach the agent?” The lifetime answers “when does it go away?” Keeping those questions separate makes the rest of AgentStack much easier to reason about.

the three supported operating modes

native · persistent

Static

Servers and selected skills are rendered into the CLI's native project files. They remain until another activation changes them.

agentstack use backend --scope project --write

native · temporary

Clean at rest

The same native files appear for a bounded session, then AgentStack restores the previous server config and removes skills it added.

agentstack run claude-code --profile backend

gateway · live

Zero files / MCP

Servers are proxied live. Skills are progressively disclosed: browse metadata first, then load only the instructions the task needs.

agentstack_list_loadable → agentstack_load

How progressive skill loading works today

small context first; verified instructions on demand

profile / library

names, pins, and sources

→

list_loadable

names + one-line descriptions only

→

load(name, reason)

verify the pin, then return SKILL.md

→

lease context

sticky and recorded in memory for this MCP connection

trust gate → in auto-project mode, an untrusted or changed repo exposes no project skill body and starts no project MCP server. A human reviews and trusts the manifest and lock before that runtime surface opens.

2 · Native-file activation

A native-file switch normally needs a restart

AgentStack assumes harness-native configuration is established when the CLI launches. use and session start write a profile's native MCP config and skills. A CLI that's already running may not see that change until it is relaunched.

the launch-time read

manifest

.agentstack/agentstack.toml — your intent

→

use / session start

writes the profile's config + skills to disk

→

CLI launches

establishes its native configuration

→

running: profile A

locked in for this process

switch while running → use profile-B --write rewrites the files on disk, but do not assume a running harness has reloaded them. Relaunch it for a deterministic switch. Live discovery belongs to the MCP path above.

Which command for which job

apply --writeRender manifest-wide servers, instructions, settings, and hooks. It never materializes skills; skills activate through a profile.persistent

use <profile> --writeActivate one profile's servers + skills, persistently, until you switch again. Global scope by default.persistent

session start <p>Activate a profile and record how to undo it, so session end restores the previous server config and removes skills the session added. Manual bookends.ephemeral

run <cli> --profile <p>Apply a profile, launch the CLI as a child, and auto-revert after a normal or managed child exit. Recovery is still available after an interrupted parent process.auto-revert

3 · Native-file sessions

Why Ctrl+C isn't `session end`

session start is a one-shot command: it writes the profile's files, records an undo entry in ~/.agentstack/sessions.json, and exits. It never holds your CLI — you launch that yourself, as a separate, unrelated process. So there are two very different lifecycles:

two ways to run a profile ephemerally

session start … end

manual bookends — you launch the CLI yourself

session start backend — writes files, records undo, then exits
you launch claude yourself (unrelated process)
Ctrl+C kills only the CLI. agentstack isn't running — the injected files stay on disk
session end — the revert: restores config, removes added skills

run --profile

one command holds the whole lifecycle

run claude-code --profile backend — applies the profile…
…spawns the CLI as a child and waits on it
you quit the CLI (or it exits)
auto-revert fires after a normal or managed child exit (--keep opts out)

so: session end is the undo button for a session start. Ctrl+C ends the CLI process; it does not undo the file changes agentstack made. Prefer run --profile when you want that undo to be automatic. session end --all is the safety hatch for any session you forgot to close.

Recovery and exactness

If the parent agentstack run process is force-killed or the machine stops, cleanup cannot execute; use session end or session end --all. Server files are snapshotted. For skills, the current implementation records names newly added by the session; replacing an already-managed skill with the same name is an edge case that should be snapshotted before the documentation promises a perfectly exact restore.

$ agentstack session start backend   # writes profile files, records undo, exits
$ claude                              # you launch it; Ctrl+C later kills only this
$ agentstack session list             # still active — files are still applied
$ agentstack session end               # NOW your prior config is restored

4 · The part people get wrong

What actually stops what

Not every [policy…] block is a runtime firewall. Some block a call as it happens; one only fails a check. Reading them as the same thing is the most common — and most dangerous — misunderstanding.

policy layers by what they actually do

[policy]
require / forbid
allowed_sources Governance. Checked by doctor --ci (fails the build) and blocks agentstack add (install path). It never sits in front of a running agent — Gateway::try_call doesn't consult it. validation · not runtime

[policy.tools] The MCP firewall. The gateway refuses a denied tool call before it reaches the upstream server, and hides it from discovery. Machine layer ∩ repo layer; no repo can loosen it. enforced · runtime

[policy.filesystem]
deny Reads/writes of denied paths. In host/gateway mode a pre-tool-use hook checks each one — but only because the harness chooses to call it. Under --sandbox the workspace is a kernel mount (coarse). cooperative · bypassable

[policy.egress] Outbound network. Under --lockdown the container's only route out is the egress-proxy sidecar, which allows/denies each host and records it. Confinement is topological. enforced · lockdown

"If I put it in global config, can no CLI access it?"

Not from [policy] governance — that only fails add / doctor --ci; it places no runtime block on anything. And if an agent directly reads a file, that's [policy.filesystem] deny, which in host mode is only the cooperative guard hook: it stops honest accidents, but "a malicious agent, or a harness that ignores its own hook protocol, bypasses it entirely" — that's the guard's own code comment. The only kernel-enforced guarantee is running the agent under agentstack run --sandbox / --lockdown.

The full, per-cell honesty — enforced vs. cooperative vs. coarse vs. unsupported, for host, gateway, sandbox, and lockdown — is the enforcement matrix.

5 · Zero-file profile leases

A live MCP session can now be genuinely zero-file

An MCP lease selects one profile for the lifetime of the current agentstack mcp process. It fences both proxied servers and loadable skills, records on-demand skill loads in memory, and writes no native harness configuration, skill directory, or sessions.json entry.

Two session types, two cleanup contracts

session start is still the native-file session and needs an undo. agentstack_lease_open is connection-local state; close it explicitly or let the MCP process exit. There are no native files to restore.

If trust changes, activity stops but the proposal trail can remain

A manifest or lock edit empties the live auto-project gateway. The in-memory lease may remain inspectable, and lease_freeze may still propose a manifest profile because it serves no bundle content, resolves no secret, spawns no server, and applies no file. Renewed activity still requires review, locking where needed, and fresh trust.

live zero-file lifecycle

connect once

→

lease_open(profile)

authorize this MCP connection in memory

→

list → load → call

fenced, verified, and audited

→

lease_close / disconnect

lease disappears; no generated files

Use agentstack_lease_status to inspect the in-memory trail and agentstack_lease_freeze to promote the skills actually loaded into a named profile for deterministic replay. Review the manifest change, then run agentstack lock to refresh the lockfile. The MCP control plane refuses to open a lease over an active native-file session (or vice versa). Because a lease is process-local, a separate shell cannot inspect it.

Keep going

Now the examples make sense.

With the runtime model in hand, the 25 examples read differently — you can see which ones write files, which serve live, and which actually enforce. Or walk the 10-minute path end to end. For the recommendation layer, use the primitives decision guide.