OKLMdocumentation v1.0.3
On this page

Permissions, sandbox and audit

What decides whether one of oklm agent's tool calls runs: the permission rules and modes, the calls that always ask, the audit log of every decision, and the sandbox that confines commands. Part of the agent harness (harness.md); the settings files that hold the rules are in agent-settings.md.

Status: implemented.

Permissions

include/oklm/harness/permissions.h, src/harness/permissions.c; the decisions of adr/0010-permission-rules.md.

oklm_perms* p;
oklm_perm_result r;
oklm_perms_new(".", &p);                 /* the project root */
oklm_perms_load_standard(p);             /* managed, project local, project, user settings */
oklm_perms_add_rule(p, OKLM_SRC_CLI, OKLM_PERM_ALLOW, "Bash(make:*)");
oklm_perms_check(p, "Bash", "make test && git log", &r);
/* r.decision, r.rule, r.source, r.reason */
  • Rules are Tool or Tool(pattern) in allow, ask and deny lists. deny beats ask, which beats allow, whatever the source; the result names the strongest rule of the winning decision.
  • On the command line oklm agent takes rules for the session, beside those of the settings files: --allow RULE, --ask RULE and --deny RULE, one rule each, and --allowedTools RULES / --disallowedTools RULES (--allowed-tools / --disallowed-tools), a list of allow or deny rules separated by commas or blanks (--allowedTools "Read Bash(git log:*)"). They are not written to any file.
  • Bash: the command line is split into simple commands at ;, &&, ||, |, |&, & and newlines outside quotes; quotes and backslashes are removed, whitespace collapsed, comments dropped, line continuations joined. Every command must match an allow rule for the call to be allowed; any command matching a deny rule denies it. prefix:* (or prefix *, the same) matches the prefix followed by a space or the end. Command or process substitution, parentheses and unbalanced quotes make the line unparsable: it then matches no allow pattern (deny and ask rules still apply to the whole line), and the call asks.
  • Paths (Read, Write, Edit, Read rules also for Glob and Grep, Edit rules also for MultiEdit and NotebookEdit): the argument is made absolute from the project root (~/ from the home directory), . and .. resolved, symbolic links of the longest existing prefix followed; the rule's glob is normalized the same way (its fixed part resolved). Globs follow gitignore: * and ? in one segment, ** across segments, classes; a glob naming a directory covers what is under it. So Read(./secrets/**) also denies src/../secrets/key and link/key when link points to secrets.
  • Domains: WebFetch(domain:example.com) matches the URL's host and its subdomains, not example.com.evil.net or a host named in the query.
  • Other tools match their main argument exactly or by prefix*; a tool name ending in * matches tools by prefix (mcp__server__*).
  • Tools denied whatever the arguments (a deny rule without a pattern: Bash, WebFetch, mcp__server for all that server's tools, a prefix ending in *, or --disallowedTools naming one) are left out of what the model is offered: the system prompt's tool definitions, the deferred list, ToolSearch and the tool-call grammar, so a small model does not spend turns calling them; a call written anyway is still refused. A rule with a pattern (Bash(rm:*), Read(./secrets/**)) keeps the tool.
  • Modes decide calls no rule matches: default (reads inside the project and its added directories run, the rest asks), acceptEdits (edits inside run too), plan (reads inside run, web fetches ask, everything else is denied, allow rules notwithstanding, until the user accepts the plan), bypassPermissions (everything runs; refused without the sandbox or when managed settings disable it; deny rules and dangerous calls still apply, and the terminal shows a warning banner). On the terminal Shift+Tab cycles them: default, acceptEdits, plan, then bypassPermissions when available; --dangerously-skip-permissions starts in bypassPermissions.

Dangerous calls

A pass after the rules and the mode turns an allow into an ask for calls on the dangerous-pattern list, whatever allowed them (a rule, acceptEdits, bypassPermissions); a deny stays a deny, plan mode still refuses. The result says why (r.dangerous, r.reason), and the question offers no "always". Built in:

Kind Entries
Trees and disks rm -r of /, the home directory, ., * or a system directory; rm --no-preserve-root; chmod/chown/chgrp -R of the same; mkfs*, mkswap, wipefs, fdisk, parted...; dd of=/dev/*; shred
The machine sudo, su, doas, pkexec; shutdown, reboot...; kill -1; crontab -r; a fork bomb; a download (curl, wget) piped into a shell or an interpreter, or substituted into one
Git and forges push --force (-f, --force-with-lease, --mirror, +ref), push --delete (:ref), reset --hard, checkout -- ., restore ., clean -f, branch -D, tag -d, stash drop/clear, --no-verify, --no-gpg-sign, core.hooksPath=, commit -n, filter-branch, filter-repo, update-ref, reflog expire, gc --prune=now; gh pr merge/close, gh release create/delete, gh repo delete/archive, gh api with a method or fields; npm/pnpm/yarn/cargo publish, gem push, twine upload
Integrations docker/podman system prune, volume rm, run --privileged, -v /:..., -v /var/run/docker.sock:...; kubectl delete, helm uninstall, kind/minikube/multipass delete, vagrant destroy, simctl erase, adb uninstall off emulators; terraform/tofu apply/destroy, pulumi up/destroy, aws/gcloud/az deletions; ngrok, cloudflared tunnel, ssh -R
Files written /etc, /boot, /usr, /bin, /sbin, /lib, /dev/sd*, /dev/nvme*, ~/.ssh, ~/.gnupg, the shell's startup files, ~/.gitconfig, ~/.config/git, ~/.config/oklm, .oklm/settings*.json, .git/hooks, .git/config: by Write, Edit, MultiEdit, and by a command's redirections, tee, cp/mv/install/ln/rsync destination, sed -i/perl -i

Commands are matched after variable assignments and wrappers (env, nohup, timeout, nice, xargs...), each simple command of the line, and in a line with substitutions every word as a possible command. The git entries needing the repository's state (a push to the default branch, amending or rebasing pushed commits, git config writes) come with git's own classifier (git_spec.md G2).

oklm_perms_add_danger(p, rule, why) adds entries, as integrations do: Bash(head token...) where the head's alternatives (a|b, wildcards) match the command's name and each token must match a later word (-x a cluster of short options holding x, --long alone or with =value, =text literally, other text as a wildcard pattern, !token none), or Edit(glob) / Write(glob) for paths.

Audit log

include/oklm/harness/audit.h, src/harness/audit.c. Each decision is appended to the session's log, .oklm/audit/<session>.jsonl, and flushed before the tool runs: time (UTC), session, tool, args (registered secrets replaced by ***), decision, by (rule or mode), source, rule, reason, answer (the user's answer to an ask).

oklm audit [--tool T] [--decision D] [--session S] [log.jsonl ...] lists them.

Sandbox

include/oklm/harness/sandbox.h, src/harness/sandbox.c; the decisions of adr/0011-sandbox.md. With a sandbox in the tool context, every Bash command and background job runs, on Linux, in new user, mount, process-id and IPC namespaces, and a new network namespace (only an empty loopback) unless network access is allowed:

  • every mount is remounted read-only (keeping the flags a user namespace may not drop), after the writable directories (the project, its added directories) were bound over themselves; /tmp is a private tmpfs (unless a writable directory lies under it);
  • the paths the Read deny rules name are hidden: an empty read-only tmpfs over a directory, /dev/null over a file (it reads empty, writes go nowhere); the paths the Write and Edit deny rules name are bound read-only, even inside the project. The list is taken from the rules when each command starts: a rule without wildcard gives its path, a rule with wildcards is expanded by walking the directory before its first wildcard (symbolic links and .git not entered, at most 100000 entries); a file created during the command is not covered;
  • the command is process 1 of its process-id namespace, with its own /proc: it sees and signals only what it started, and whatever it left running dies with it. The forked child waits for it and exits with its status;
  • resource limits (setrlimit): CPU time, address space, file size, open files and processes, each lowered, never raised; the process count is per user namespace (Linux 5.14 and later); and no core files, so a command killed by a limit leaves no dump behind;
  • the user's id is mapped to itself, so files written in the project are the user's;
  • no_new_privs, then a seccomp filter: calls of another architecture kill the process, x32 calls and mount, umount, the new mount API, unshare, setns, pivot_root, chroot, ptrace, bpf, keyctl and module loading fail with EPERM;
  • the network filtered by domain (proxy.h, proxy.c): without the network, when sandbox.allowedDomains or a WebFetch(domain:...) allow rule names a domain, a proxy thread listens on a Unix socket ($XDG_RUNTIME_DIR/oklm-proxy-PID.sock, else the project's .oklm). Inside the command's network namespace loopback is brought up, a relay process listens on 127.0.0.1:3128 and passes each connection to the socket. The relay works in the socket's directory, held by a descriptor opened before the mounts: the socket is reached whatever covers its path in the command's view (the private /tmp, a hidden directory), and a path of any length works (only the file name has to fit a Unix socket address's 108 bytes; the proxy binds a longer path through /proc/self/fd). The command gets HTTP_PROXY, HTTPS_PROXY, ALL_PROXY (and their lower-case forms; NO_PROXY for loopback). The proxy reads CONNECT host:port (https and any TCP) or an absolute http:// request, checks the host (host exactly, *.domain for it and every name under it, * for all; sandbox.deniedDomains and WebFetch deny rules win), connects and relays, else answers 403. The hosts it refused during a Bash call are added to the call's result for the model. A tool that ignores the proxy variables reaches nothing. The rules are read again before each request; an allowed name resolves on the host, so a domain pointing at a local address reaches it (allow domains you trust). /sandbox and the session's first line say which network the commands have;
  • the plan (mount table, flags, maps, filter) is prepared in the harness; the forked child only makes system calls, as fork() in a multithreaded process requires. A command that cannot be confined is not run (exit code 125).

oklm_sandbox_available() tries the namespaces once in a child. oklm agent confines commands whenever it can (--no-sandbox turns it off, --allow-network keeps the network), which also makes the bypassPermissions mode available; without the sandbox, bypass is refused and commands keep asking. --limit NAME=VALUE sets a limit (cpu seconds, memory, file bytes with an optional K, M, G or T, files, procs; 0 unsets); procs=4096 by default. Unconfined, the limits still apply but for the process count, which RLIMIT_NPROC would take over all the user's processes. Windows runs commands in a Job Object carrying the memory, process and CPU-time limits (a job's own memory and CPU limits too: § Declared services; cross-compiled, untested on Windows), without file or network confinement, and refuses to run a command asked to be confined; its output's CR LF line ends become LF.

In bypass mode, Qwen3-4B asked to run echo hi > ../escape.txt: sh: 1: cannot create ../escape.txt: Read-only file system, and it says the write failed.