# Wrap the qURL CLI for a sandboxed agent

> A broker that runs qurl for a sandboxed agent: which commands only read, which change access, how to find the subcommand, and what to tell the agent.

Source: https://layerv.ai/for-agents/wrap-qurl-cli-for-an-agent/

---

[← For agents](https://layerv.ai/for-agents/) 

# Wrap the qURL CLI for a sandboxed agent

## Which qurl commands can a command broker let a sandboxed agent run, and how should it parse them?

Sort qURL™ operations by what they do: help and version touch nothing; whoami, list, status and inspect read state; share and get deliver access or content; publish and delete change resources. Gate commands with both read and write forms unless your broker constructs a known read-only invocation. Validate the full argument list, including global flags such as -o json, and pass the agent qurl’s own error text.

**Reproduced with qURL CLI 3.5.0.** The flag placements and help forms were run with qURL CLI 3.5.0 and created no state. Which commands read and which change was read in the 3.5.0 help text, and in this site’s qURL skill for the commands added later. No command that reaches the service was run for this page, and later releases were not run. Verified November 19, 2026.

## Who this is for

You run an agent with no general shell, such as an evaluation harness or a sandbox that exposes a few tools, and one of those tools runs qurl for it. The broker decides which commands go through. Too strict, and the agent cannot find out what its own publish left behind. Too loose, and it can create resources, hand out access or delete things nobody asked for.

An agent with an ordinary shell needs none of this: it runs qurl directly, and the other pages here apply as written.

## Sort commands by what they change

Classify by command and flag, not by whether the command succeeded: a publish that failed can still have created a resource. “Read state” does not mean offline. Each of those commands opens the device identity and asks the service, and on an empty state directory the first one enrolls a new device, as whoami’s help says.

__qurl commands by what they change, and what a broker should do__
| Class                      | Commands                                                                                                                                           | What a broker should do                                                                                                   |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Help and version           | qurl with no arguments, a lone --help, -h or --version, help <command>, version                                                                    | Allow. They open no state. In an evaluation, they never count as using qURL                                               |
| Read state                 | whoami, list, status, inspect; grants, requests and publisher only through a separate read operation                                               | Allow, with the same state and environment as the publish, so a failed attempt can be inspected                           |
| Hand out access            | share (mints a link), get (fetches the content or opens a link)                                                                                    | Allow only for a CRID the attempt owns or was given; each share is a new way in. Set or restrict get’s --file destination |
| Change resources or access | publish, start, stop, restart, delete, approve, deny; grants with --add, --remove or --clear; requests with --on or --off; publisher set and clear | Gate each one. One publish per attempt until it is reconciled; delete only a CRID the attempt owns, after asking          |
| Account and supervisor     | account, login, daemon, request, completion                                                                                                        | Refuse, unless your broker is the supervisor that owns that state                                                         |
| Anything else              | Commands added after the release you classified, such as access, preview, payments and origin-header in later releases                             | Refuse, and name the command, until you classify it for the release you pin                                               |

## Find the subcommand the way the CLI does

The subcommand is not always the first argument. qurl 3.5.0 ran every one of these as the version command: -o json version, version -o json, -ojson version, --output=json version, --endpoint https://api.layerv.ai -o json version, -q version and -qv version. It printed help for publish --help, -o json publish <target> --help and help publish, and for qurl with no arguments. A broker that reads the first argument as the subcommand misses a publish written as qurl -o json publish, and one that matches on the executable’s name misses /usr/local/bin/qurl.

So skip the global flags, with their values, to the first other word. A flag the broker does not know, before the subcommand, is refused: the broker cannot tell whether it takes a value, and the CLI itself exits 2 on an unknown flag. -- before the subcommand is refused too: qurl 3.5.0 answers -- version with “unknown command”. The function below follows those rules, and refuses combined short flags such as -qv rather than guess at them. Give it the arguments after the executable, whatever path the executable was called by.

Then pin what you set yourself, in a check of its own beside the function. Refuse --endpoint unless it is the endpoint you chose, --supervision unless it matches the supervision mode you chose, and --profile, which picks other configuration. The CLI accepts -o twice; refuse two different values, so the output the agent asked for is the output it gets.

```
qurl_verb() {
  while [ $# -gt 0 ]; do
    case $1 in
      --color|--endpoint|-o|--output|--profile|--supervision)
        [ $# -ge 2 ] || return 2
        case $2 in -*) return 2 ;; esac
        shift 2 ;;
      --color=*|--endpoint=*|-o?*|--output=*|--profile=*|--supervision=*) shift ;;
      -q|--quiet|-v|--verbose) shift ;;
      -h|--help|--version)
        [ $# -eq 1 ] || return 2
        echo help; return 0 ;;
      -*) echo "unknown flag before the subcommand: $1" >&2; return 2 ;;
      *) echo "$1"; return 0 ;;
    esac
  done
  echo help
}
```

## Classify the whole command

Use the verb as the first check. This example sends grants, requests and publisher through the change gate because each has read and write forms. To offer the read forms without approval, give the agent a separate tool operation that builds the read-only arguments from validated inputs. Offer help the same way, through an explicit help operation. A trailing --help in an arbitrary argument list leaves its verb’s class in place.

Before running the CLI, validate the full argument list against the flags and resource identifiers your tool permits, including global flags that appear after the verb. Treat refuse as a denial. A pinned CLI release and an allowlist for each operation keep new commands and flags from expanding access automatically.

```
qurl_class() {
  _qurl_verb=$(qurl_verb "$@") || { echo refuse; return 0; }
  case $_qurl_verb in
    help|version) echo help ;;
    whoami|list|status|inspect) echo read ;;
    share|get) echo access ;;
    publish|start|stop|restart|delete|approve|deny|grants|requests|publisher) echo change ;;
    *) echo refuse ;;
  esac
}
```

## Keep the attempt’s state in words that match what happened

A publish can fail after it created the resource, so “the publish exited non-zero” and “nothing exists” are different facts. Track the attempt through states such as these, which are suggestions for the broker’s own output; qurl prints none of them: not started; publish in flight; publish failed, ownership not yet reconciled; owned resource known, with its CRID; serving; cleanup complete.

Block a second publish while an attempt is in flight or unreconciled, since publishing again can reuse the resource or, from other state, create another. Let the read class through at every state: after a failed publish, list --status active -o json is how the agent, or your controller, finds what the attempt created. When the broker refuses a command, say why in its own terms: “publish is blocked until the first attempt is reconciled” or “--profile is not allowed”, never a generic ownership error.

## Pass the agent qurl’s own error

qurl’s error names the stage that failed, and the error reference says what each one left behind. A broker that reports only “Service exited before ready” throws that away, and the agent retries the wrong thing. Return a bounded excerpt of stderr, a few lines, along with the exit code, and keep the full log where your controller can read it.

## If you measure whether an agent used qURL

Count only the access and change classes, with their exit codes. Help, version and the read class show that the agent looked; a delete during cleanup is not a delivery. A command string inside echo, a heredoc or a quoted documentation example is not a command at all. Keep the raw argument list in your trace beside the class, so a later reader can check the classification.

## Frequently Asked Questions

Is qurl whoami safe to allow? 

It changes no resource and no access, so a broker can allow it. It is not offline: it checks the device identity with the service, and on an empty state directory it enrolls a new device first.

Why refuse a flag the broker does not know? 

Before the subcommand, an unfamiliar flag can make the verb ambiguous. After the subcommand, allow only the options your tool supports for that operation.

Should the broker let the agent retry a failed publish? 

Not until the attempt is reconciled. Let it read the inventory with qurl list --status active -o json, then either fix the cause and publish again with the same state, which reuses the same CRID, or delete that one CRID.

Does qurl share change anything? 

It creates no resource, but each link is a new way into the resource for whoever holds it. Treat it as handing out access: allow it only for a CRID the attempt owns or was given.

## Related Resources

[Recover a failed qURL publish safely →](https://layerv.ai/for-agents/recover-failed-publish/) [qURL CLI JSON reference for automation →](https://layerv.ai/for-agents/qurl-cli-json-for-automation/) [qURL CLI errors and exit codes →](https://layerv.ai/for-agents/qurl-cli-errors/) [Headless qURL: native or external supervision? →](https://layerv.ai/for-agents/headless-native-vs-external-supervision/) [The qURL skill →](https://layerv.ai/skills/qurl/SKILL.md)

## Give your agent the qURL skill

One file teaches a coding agent to publish an app privately, let people and other agents in, and recover when the CLI stops it. No account, no API key.

[Read the skill →](https://layerv.ai/skills/qurl/SKILL.md)



---

*This markdown version is auto-generated from [https://layerv.ai/for-agents/wrap-qurl-cli-for-an-agent/](https://layerv.ai/for-agents/wrap-qurl-cli-for-an-agent/) for AI agents. Curated agent resources: [llms.txt](https://layerv.ai/llms.txt). For the full interactive experience, visit the HTML version.*

