Skip to content
CompanyWizard

Command-line tools (CLI) in the assistant — overview & limits

User

Some tasks the assistant handles not through a built-in function but by calling an external command-line program (a CLI) — a version-control or conversion tool, say. This CLI command tool is deliberately kept on a short leash: it runs only in the desktop edition, starts vetted, version-pinned programs only, and runs nothing state-changing until you have approved it.

What it is — and what it isn’t

Section titled “What it is — and what it isn’t”
  • Skill-driven. The assistant calls a CLI only within a capability meant for it, not on a whim.
  • Manifest, not shell. Every invocation is described as a manifest — the program plus its arguments as a fixed list (argv). The assistant never assembles a free shell line; there is no sh -c, arguments are validated, not interpolated.
  • Desktop only. The tool exists in the desktop edition only. → Two deployment modes — web vs. desktop
  • Pinned programs only. Only programs registered in an allowlist with a fixed version and a verified checksum will launch. Setting that up is the admin how-to → Release, pin & license-review a CLI tool.

Read, write — and the dry run

Section titled “Read, write — and the dry run”

As with every tool, the effect is what matters (→ The assistant’s tools — overview & model):

  • Reading calls only retrieve information and change nothing.
  • Writing or network-reaching calls — anything that changes state or reaches the network — are shown to you beforehand. In the dry run you see the exact command (argv) that would run, before it runs.

Approval is yours (HITL)

Section titled “Approval is yours (HITL)”

Before a state-changing or network-reaching command starts, the approval dialog appears: it shows the exact argv and the dry run. The command runs only after you approve. This human approval (human-in-the-loop) is not a formality — it is the tool’s core security boundary.

A run’s output then passes through the PII shield before the assistant or you get to see it. → The PII shield

How far the guarantee reaches

Section titled “How far the guarantee reaches”

The tool contains each run as well as it can without a virtual machine — the guarantee is best-effort containment plus egress control, explicitly not VM isolation. A bundled virtual machine was deliberately ruled out because it often can’t be rolled out at corporate clients (hypervisor disabled by policy, no local admin rights). The host process is hardened instead.

The load-bearing security boundary is credential-scoping + your approval (HITL), not the OS sandbox. A tool only ever sees the credentials explicitly scoped to it, and a changing run does not start until you approve it.

What containment enforces:

  • Writing only inside the declared workdir, reading only within the declared roots.
  • No network access unless a host allowlist explicitly permits it (everything else is denied).
  • A timeout that kills the whole process tree.
  • Output through the PII shield; every run produces an audit record.

What it explicitly does not provide (an honest limit beats over-claiming):

  • No resistance to a kernel-level sandbox escape by a determined local attacker — the sandbox raises the bar, but it is not a perimeter to bet a hostile program on.
  • No execution of untrusted code — bundled CLIs are vetted, pinned programs, not arbitrary binaries.
  • No multi-tenant execution — which is why web mode is excluded by design; the tool is desktop-only, one user on their own machine.

In one sentence: Sandboxed, least-privilege command execution with default-deny networking and mandatory human approval — best-effort OS containment, not a virtual machine.

Section titled “Related”