moltbot/elevated.md at 7544beea17943fa16b43bba670ffe089ba00091f

mirror of https://github.com/moltbot/moltbot.git synced 2026-05-07 07:58:36 +00:00

Files

Vincent Koc 180e295dc6 docs(tools): rewrite loop detection, code execution, and tighten elevated/skills

Loop detection (docs/tools/loop-detection.md): substantial rewrite.
Fixed the post-compaction guard default story — the guard runs whenever
tools.loopDetection.enabled is not explicitly false, even with no
config block at all (verified in src/agents/pi-embedded-runner/run.ts
near line 800: 'enabled: resolvedLoopDetectionConfig?.enabled !==
false'). The previous doc framed it as opt-in. Added the missing
unknownToolThreshold field (default 10) sourced from
src/config/schema.help.ts, a complete fields table, and a CardGroup
related links section.

Code execution (docs/tools/code-execution.md): rewrote with
Steps-driven setup, code-verified defaults from
extensions/xai/src/code-execution-shared.ts (default model
grok-4-1-fast, default timeout 30 s, optional maxTurns), the
missing_xai_api_key structured error documented as JSON, and a
properties summary table. Replaced the trailing bullet list with a
CardGroup pointing at exec, exec-approvals, web tools, and the xAI
provider page.

Elevated (docs/tools/elevated.md): converted Related to a CardGroup
and added a Note that the bash chat command (! prefix / /bash alias)
also requires tools.elevated, sourced from
src/config/schema.help.ts:1375.

Skills config (docs/tools/skills-config.md): renamed the
'Sandboxed skills + env vars' subhead to remove the brittle '+'
character per docs/CLAUDE.md, promoted the host-only env warning to a
Warning block so the most common skill-config footgun stays visible,
and converted Related to a CardGroup including a config-reference
link.

2026-05-05 16:49:29 -07:00

4.8 KiB

Raw Blame History

summary, read_when, title

summary

read_when

title

Elevated exec mode: run commands outside the sandbox from a sandboxed agent

Adjusting elevated mode defaults, allowlists, or slash command behavior

Understanding how sandboxed agents can access the host

Elevated mode

When an agent runs inside a sandbox, its exec commands are confined to the sandbox environment. Elevated mode lets the agent break out and run commands outside the sandbox instead, with configurable approval gates.

Elevated mode only changes behavior when the agent is **sandboxed**. For unsandboxed agents, exec already runs on the host.

Directives

Control elevated mode per-session with slash commands:

Directive	What it does
`/elevated on`	Run outside the sandbox on the configured host path, keep approvals
`/elevated ask`	Same as `on` (alias)
`/elevated full`	Run outside the sandbox on the configured host path and skip approvals
`/elevated off`	Return to sandbox-confined execution

Also available as /elev on|off|ask|full.

Send /elevated with no argument to see the current level.

How it works

Elevated must be enabled in config and the sender must be on the allowlist:

```json5
{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        discord: ["user-id-123"],
        whatsapp: ["+15555550123"],
      },
    },
  },
}
```

Send a directive-only message to set the session default:

```
/elevated full
```

Or use it inline (applies to that message only):

```
/elevated on run the deployment script
```

With elevated active, `exec` calls leave the sandbox. The effective host is `gateway` by default, or `node` when the configured/session exec target is `node`. In `full` mode, exec approvals are skipped. In `on`/`ask` mode, configured approval rules still apply.

Resolution order

Inline directive on the message (applies only to that message)
Session override (set by sending a directive-only message)
Global default (agents.defaults.elevatedDefault in config)

Availability and allowlists

Global gate: tools.elevated.enabled (must be true)
Sender allowlist: tools.elevated.allowFrom with per-channel lists
Per-agent gate: agents.list[].tools.elevated.enabled (can only further restrict)
Per-agent allowlist: agents.list[].tools.elevated.allowFrom (sender must match both global + per-agent)
Discord fallback: if tools.elevated.allowFrom.discord is omitted, channels.discord.allowFrom is used as fallback
All gates must pass; otherwise elevated is treated as unavailable

Allowlist entry formats:

Prefix	Matches
(none)	Sender ID, E.164, or From field
`name:`	Sender display name
`username:`	Sender username
`tag:`	Sender tag
`id:`, `from:`, `e164:`	Explicit identity targeting

What elevated does not control

Tool policy: if exec is denied by tool policy, elevated cannot override it.
Host selection policy: elevated does not turn auto into a free cross-host override. It uses the configured/session exec target rules, choosing node only when the target is already node.
Separate from /exec: the /exec directive adjusts per-session exec defaults for authorized senders and does not require elevated mode.

The bash chat command (`!` prefix; `/bash` alias) is a separate gate that requires `tools.elevated` to be enabled in addition to its own `tools.bash.enabled` flag. Disabling elevated locks `!` shell commands out as well. Shell command execution from the agent. Approval and allowlist system for `exec`. Gateway-level sandbox configuration. How the three gates compose during a tool call.

4.8 KiB Raw Blame History