Security and execution boundaries

Holon runs agents that can execute shell commands, delegate work, and wait for external events. Understanding what boundaries Holon provides — and what it does not — helps you run agents safely.

The host-local runtime

Holon runs as a user-level process on your machine. It is not a sandbox:

Agents can run any command your user account can run.
File operations use your user permissions.
Network access follows your host's network configuration.
There is no container, VM, or seccomp isolation built into the runtime.

What this means: scope workspaces intentionally, use dedicated user accounts or containers when running untrusted agent workloads, and treat agent command execution with the same care you'd give a shell script running as your user.

Execution environment summary

Every agent receives an execution environment summary in context. This summary describes the current policy snapshot and what is enforced:

Boundary	Level	What it means
`cwd_rooting`	runtime_shaped	The runtime allows workdir outside the workspace root when explicitly requested; sandboxing is the responsibility of the execution backend
`projection_rooting`	hard_enforced	Filesystem views are constrained to the projected root
`path_confinement`	not_enforced	The runtime does not prevent access outside the workspace by path
`write_confinement`	not_enforced	Write operations are not restricted to the workspace
`network_confinement`	not_enforced	Network access is unrestricted by default
`secret_isolation`	not_enforced	The runtime does not isolate secrets from agent commands

Key takeaway: boundaries marked hard_enforced are runtime guarantees. Boundaries marked not_enforced rely on the operator's host configuration (filesystem permissions, firewall rules, container isolation).

Workspace binding

Holon provides workspace binding that constrains where the agent operates:

Workspace root — the agent's default working directory. The runtime defaults commands to start inside this root, but an explicit workdir may point outside the workspace when the execution backend allows it.
Projection root — constrains the filesystem view presented to the agent. When enforced, the agent only sees files under the projection root.
ApplyPatch targets — file mutation tools resolve relative paths against the active workspace by default.

These bindings are organizational guardrails, not security boundaries: an agent that can execute arbitrary shell commands can cd /etc or read files outside the workspace if your OS permissions allow it. For true confinement, pair Holon with a container, VM, or dedicated user account.

Remote access (`holon serve`)

holon serve exposes the Holon control plane over HTTP. This is a powerful surface and must be protected:

# Secure: local-only access on Unix socket (default daemon mode) — no
# additional protection needed beyond filesystem permissions
holon daemon start

# Caution: LAN-accessible — always require a token
holon serve --access lan --token "your-secret-token"
holon serve --access lan --token-file ~/.holon/remote.token

# Caution: tunnel access — the tunnel provider can route traffic to
# your Holon instance
holon serve --access tunnel --token "your-secret-token"

Rules for remote access:

Always use --token or --token-file when exposing Holon beyond localhost.
Prefer --access local or the default daemon Unix socket unless you have a specific integration need.
Treat the token as a credential: rotate it, don't commit it, and don't share it through unencrypted channels.
Tunnel mode exposes Holon through a tunnel provider; understand the provider's security model before using it.

Capability-secret URLs

Holon generates callback URLs for external triggers and wake events. These URLs contain capability secrets:

http://host:7878/callbacks/wake/cb_<secret>

Anyone who knows this URL can wake the agent. Treat these URLs as secrets:

Do not log them, commit them, or share them in public channels.
Rotate them when rotating other credentials.
Use HTTPS and token-protected serve for production deployments.

Trust and provenance

Holon classifies every input by its origin and trust level:

Trust level	Example sources	What it means
`trusted-operator`	CLI, TUI, authenticated HTTP	You initiated this input
`trusted-system`	Internal runtime events, scheduled timers	The runtime generated this
`trusted-integration`	Authenticated webhook from a known service	A trusted external system sent this
`untrusted-external`	Public webhooks, user-submitted content	The source is unknown or unverified

Trust metadata is a policy signal, not a security guarantee. The agent sees the trust level and can adjust its behavior (e.g., refusing destructive commands on untrusted input), but trust labels do not replace sandboxing. External content marked untrusted-external still runs with your user's privileges unless you add OS-level confinement.

Practical recommendations

Use dedicated workspaces — give agents a specific project directory rather than your home directory.
Protect remote access — always use tokens, prefer local Unix sockets.
Guard capability URLs — treat wake/callback URLs as credentials.
Don't rely on trust labels alone — they inform agent behavior, not OS security.
Add OS-level isolation for high-risk work — containers, VMs, or dedicated user accounts.