The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
security
The trust boundary of the core. This folder decides whether an agent may run a
command or touch a path, parks tool calls that need a human yes or no, stores
credentials and secrets, scrubs secrets and PII out of anything persisted, and
guards the RPC listener when it binds beyond loopback. security/mod.rs calls
it the kernel security family. None of its submodules is feature-gated: every
build carries all of it.
Callers are spread across the core. Every acting tool consults
SecurityPolicy before it runs, the agent harness asks the approval gate
before a prompted call, the credentials domain owns the auth.* RPC
namespace, and the RPC server asks pairing.rs whether a bind needs a token.
How it works
The policy and its off switch
SecurityPolicy (policy/types.rs) is the value every tool receives. It is
built once per agent session by SecurityPolicy::from_config
(policy/enforcement.rs) from the [autonomy] config block, the workspace dir
and the action dir. That constructor is the single chokepoint between config
and policy, so it also injects the default trusted roots: the projects home
(~/OpenHuman/projects) as read-write, the configured action_dir as
read-write (skipped when the action dir sits at or above workspace_dir), the
tool-result artifacts directory as read-only, and the namespaced scratch dir
(/tmp/openhuman, never /tmp itself) as read-write.
The policy is off by default. AutonomyConfig::enabled
(config/schema/autonomy.rs) defaults to false, and from_config copies it
onto SecurityPolicy::enabled. Agents here run inside containers, platform
jails and Docker sandboxes that already give the isolation this in-process
policy approximated, and a shell tool that refuses ordinary shell syntax is
not a usable shell. from_config logs a line at info level when it builds a
disabled policy.
Every enforcement entry point checks the flag first and returns the permissive answer when it is off:
| Function | File | Disabled result |
|---|---|---|
gate_decision |
policy/command_checks.rs |
GateDecision::Allow |
check_gated_command |
policy/command_checks.rs |
Ok(class), no structural guard |
validate_command_execution |
policy/command_checks.rs |
Ok(risk), no allowlist |
is_command_allowed |
policy/command_checks.rs |
true |
can_act |
policy/enforcement.rs |
true |
record_action, is_rate_limited |
policy/enforcement.rs |
never limited |
is_path_string_allowed |
policy/path_checks.rs |
true after the floor checks |
is_resolved_path_allowed_for |
policy/path_checks.rs |
true after the floor check |
check_resolved_against_forbidden |
policy/path_checks.rs |
Ok(()) after the floor check |
So with the policy disabled, command classification still runs (callers get a
CommandClass back) but nothing is gated on it: no approval prompt, no
command allowlist, no hourly action budget, and no workspace_only,
forbidden_paths, trusted-root or workspace-internal containment.
A floor survives the off switch. These checks run before the enabled test
and hold in every configuration:
is_always_forbidden(policy/path_checks.rs). Credential stores are matched by path segment, case-insensitively:.ssh,.gnupg,.aws,.azure,.kube,keychains, and the Windows pairsMicrosoft\{Protect,Credentials,Crypto,Vault}. System roots are matched by absolute prefix:/etc,/root,/boot,/proc,/sys,/system,C:\Windows,C:\Program Files,C:\Program Files (x86),C:\ProgramData. A trusted-root grant cannot reach these either, and the per-turn workspace grant is checked after this test, so it cannot either.- In
is_path_string_allowed: a null byte, a..path component, and URL-encoded traversal (..%2f,%2f..) are rejected. A bare relative name that matches one of the reserved workspace files (WORKSPACE_INTERNAL_FILESinpolicy/types.rs, such as.env) is also rejected.
SecurityPolicy::default() is the opposite of the shipped default: it sets
enabled: true. It is the fallback for a policy built with no config at all
(tests, examples, a few internal call sites), where failing closed is right.
Only from_config carries the shipped false.
With the policy enabled
Set [autonomy] enabled = true and the full policy applies. Commands are
classified, then gated by tier:
shell command string
|
v
strip_quoted_heredoc_bodies quoted heredoc body is data, blanked
|
v
classify_command highest class across ; | && || segments,
| redirect or tee lifts to >= Write
v
class.max(declared) model may raise the class, never lower it
|
v
gate_decision(class)
|
+----+--------------+-------------------+
v v v
Allow Prompt Block
run the tool ApprovalGate park refused with
(10 min TTL) POLICY_BLOCKED_MARKER
The tier matrix in gate_decision: ReadOnly allows only Read and blocks
everything else; Supervised allows Read and prompts on every acting class;
Full runs Read and Write silently and prompts on Network, Install and
Destructive.
The invariants that hold with the policy enabled:
action_diris the agent's permitted read and write root. Tools resolve relative paths and default their working directory there, andfrom_configgrants it as aReadWritetrusted root so a non-default working folder is writable. The grant is skipped when the action dir is an ancestor ofworkspace_dir, because a trusted root overridesforbidden_pathsand a working directory should not buy that over the whole workspace.workspace_dirstores internal state and is never an acting-tool target.is_workspace_internal_pathcoversWORKSPACE_INTERNAL_DIRS,WORKSPACE_INTERNAL_FILES, thememory-,memory_tree-andsession_raw-prefixes, per-artifact directories underartifacts/(but notartifacts/tool-results/), and the accountconfig.tomlbeside the workspace. A trusted-root grant does not weaken this.- Unknown commands classify as writes.
classify_commandis fail-closed: a command that is not provably read-only is at leastCommandClass::Write. The body of a quoted heredoc (<< 'EOF' ... EOF) is blanked first bystrip_quoted_heredoc_bodies, since the shell expands nothing there. An unquoted delimiter (<< EOF) is expanded and is still scanned. - Outside
Full,check_gated_commandrejects hidden execution (command or process substitution, backticks, background&) that could smuggle a command past the approval the human read. - Interactive approval requests expire as denied after ten minutes
(
DEFAULT_APPROVAL_TTLinapproval/gate.rs; the Flow Canvas copilot path uses a three-minute window).
The TinyBox module owns shell-string scanning and returns CommandAnalysis
facts over the tinybox-bus contract. policy/command_checks.rs
applies the host's autonomy tier and protected-path policy to those facts.
Hot-swapping the policy
A session builds its policy once and shares it immutably with every tool, so a
settings change would otherwise wait for a new session. live_policy.rs holds
the current policy in a process-global cell. install is called at bootstrap
(core/runtime/bootstrap.rs) and at channel startup, and reload_from is
called by the config save path (config/ops/agent.rs) so current() reflects
the new [autonomy] block immediately. The approval gate reads the user's
"Always allow" list (autonomy.auto_approve) through current(). Today tools
observe the swap at the next session boundary.
Approval
approval/ is the human-in-the-loop gate for calls the policy prompts on.
The gate persists a pending row, publishes DomainEvent::ApprovalRequested so
the UI can show a card, parks the tool future on a oneshot, and wakes on the
approval_decide RPC or a typed chat reply. Timeouts and denials fail closed.
approval_gate_boot_decision (core/types.rs, applied in
core/runtime/bootstrap.rs) always installs the gate for
HostKind::TauriShell and ignores OPENHUMAN_APPROVAL_GATE=0 there; CLI,
Docker and library hosts may opt out. When no gate is installed, the harness
bridge (agent/tinyagents/host/security_gate.rs) warns and allows a Prompt
decision. See approval/README.md.
Layout
| Path | What it does |
|---|---|
policy/ |
SecurityPolicy, autonomy tiers, command classification and path checks. |
approval/ |
The approval gate, its SQLite store, argument redaction and the approval_* RPCs. |
credentials/ |
The backend credential slots, auth profiles, provider OAuth and the auth.* RPC namespace. |
devices/ |
Mobile device pairing and the end-to-end encrypted tunnel to iOS clients. |
egress/ |
Descriptors for every external data transfer and the LocalOnly enforcement chokepoint. |
encryption/ |
AES-256-GCM at-rest encryption for memory storage and the encrypt/decrypt RPCs. |
keyring/ |
OS keychain backend with an encrypted-file fallback, and the SecretStore config-field codec. |
keyring_consent/ |
Consent gate for falling back from the OS keychain to local encrypted storage. |
tinymemory_api::safety (upstream contract) |
Fully local PII and identification-risk detection. scan and redact_identifiers require the API's opt-in local-safety feature; detection results and policy decisions remain separate. |
prompt_injection/ |
Deterministic prompt-injection screening (Allow, Review, Block). |
live_policy.rs |
Process-global, hot-swappable current SecurityPolicy and privacy mode. |
scrub.rs |
Secret and PII scrubbing with the host's policy (Policy::corroborated) over TinyMemory's scrubbers. |
audit.rs |
Append-only JSON audit log of agent actions (AuditLogger). |
pairing.rs |
Non-loopback bind guard for the core RPC token; re-exports channel pairing helpers. |
core.rs |
redact(), the 4-character-prefix log redaction. |
ops.rs |
security_policy_info_for_config and load_and_get_security_policy_info. |
schemas.rs |
The security.policy_info controller. |
tools.rs |
SecurityPolicyInfoTool, the only agent-callable tool in this domain. |
secrets.rs |
One-line re-export of keyring::encrypted_store for older import paths. |
Key types and entry points
SecurityPolicy(policy/types.rs): the policy value. Build it withSecurityPolicy::from_config. Its methods are the enforcement entry points listed above, plusenforce_tool_operation(tier plus hourly budget for an acting tool) andvalidate_path-style helpers inpolicy/path_checks.rs.AutonomyLevel(ReadOnly,Supervised,Full),CommandClass(Read,Write,Network,Install,Destructive) andGateDecision(Allow,Prompt,Block), all inpolicy/types.rs.TrustedRootandTrustedAccess(Read,ReadWrite): user-granted subtrees that overrideworkspace_onlyandforbidden_paths, never the floor or the workspace-internal boundary.POLICY_BLOCKED_MARKERandPOLICY_DENIED_MARKER: prefixes on refusal strings so the harness and model can tell a policy refusal from a tool failure.validate_path_within_root,openhuman_scratch_dir,ensure_openhuman_scratch_dir(policy/enforcement.rs).live_policy::{install, current, reload_from, reload_privacy, set_action_dir}(live_policy.rs).scrub::{sanitize_text, sanitize_json, has_likely_secret}(scrub.rs): used by the approval store, memory writes, flow memory tools and artifact offload, so they all redact the same way.AuditLoggerandget_or_create_workspace_audit_logger(audit.rs).is_public_bindandensure_core_rpc_token_for_bind(pairing.rs): refuse a non-loopback RPC bind without anOPENHUMAN_CORE_TOKEN(CORE_TOKEN_ENV_VAR).PairingGuard,constant_time_eqand the token helpers are re-exported fromtinychannels_bus::security.SecretStore(re-exported fromkeyring/): encrypted-on-disk secrets whose master key lives in keychain-backed storage.- The
egressre-exports at the crate root:enforce_egress,emit_external_transfer,local_only_blocks,local_only_tool_block,EgressDescriptor. OpenHuman's agent stop-summary code directly consumestinymemory_api::safety::redact_identifiers; this security module does not re-export the safety API.
RPC surface
This file registers one controller through core/all.rs:
security.policy_info: the effective policy (autonomy level,workspace_only, allowed commands, hourly budget, approval and high-risk flags), computed from the loaded config.
SecurityPolicyInfoTool (security_policy_info, deferred exposure) returns
the same payload to the agent. Command and path gating is enforced inside the
engine and is never an agent-callable tool.
The subfolders register their own namespaces: approval.* (approval/),
auth.* (credentials/), devices.* (devices/), encrypt.secret and
decrypt.secret (encryption/), and
keyring_consent.* (keyring_consent/). Their READMEs list the methods.
Boundaries
- Sandbox backends do not live here.
crates/openhuman-core/src/sandbox/picks a backend per session and delegates native confinement and process ownership to the loaded TinyBox module (vendor/tinybox). - Shell parsing and command classification run inside the loaded TinyBox module;
its
CommandAnalysisresponse is the bus boundary. Policy over those facts stays here. - Secret and PII scrubbers are TinyMemory's
(
tinymemory_integrations::safety,vendor/tinymemory); this folder only pins the policy. - Channel pairing primitives (
PairingGuard, token hashing) belong totinychannels(vendor/tinychannels). - The core never obtains, validates, exchanges or refreshes a credential.
Login-token exchange and
/auth/mebelong to the host's session owner (openhuman_tinyhumans::session).credentials/only accepts one throughauth.set_credential. - The tinyagents runtime holds no authority. The bridge that answers its
"may this tool run?" question is
agent/tinyagents/host/security_gate.rs.
Gotchas
- Tests that exercise the allowlist, the tier or containment must build their
config with
enabled: true. With the shipped default they pass vacuously.policy/policy_disabled_tests.rspins the contract of the disabled path. - Do not move a floor check below the
if !self.enabledreturn. The floor is the part a future edit is most likely to take with it. SecurityPolicy::default()is enabled,AutonomyConfig::default()is not. Code that builds a policy withoutfrom_configgets the strict one.enforce_tool_operationrecords an action as a side effect. The harness gate readsis_rate_limitedinstead, so a call is not counted twice.- A user's "Always allow" entry only suppresses the human prompt. The tier, the class and the floor still run before the gate.
Tests
Each file has a sibling <module>_tests.rs; the policy suites live in
policy/ (policy_tests.rs, policy_disabled_tests.rs,
policy_trusted_roots_tests.rs, policy_workspace_internal_tests.rs,
proptest_tests.rs and others). Run them with
cargo test -p openhuman security:: or pnpm debug rust security.