Skip to main content
← 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 .

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
ClassCommandsWhat a broker should do
Help and versionqurl with no arguments, a lone --help, -h or --version, help <command>, versionAllow. They open no state. In an evaluation, they never count as using qURL
Read statewhoami, list, status, inspect; grants, requests and publisher only through a separate read operationAllow, with the same state and environment as the publish, so a failed attempt can be inspected
Hand out accessshare (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 accesspublish, start, stop, restart, delete, approve, deny; grants with --add, --remove or --clear; requests with --on or --off; publisher set and clearGate each one. One publish per attempt until it is reconciled; delete only a CRID the attempt owns, after asking
Account and supervisoraccount, login, daemon, request, completionRefuse, unless your broker is the supervisor that owns that state
Anything elseCommands added after the release you classified, such as access, preview, payments and origin-header in later releasesRefuse, 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.

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 →

Book a pilot

Tell us what to hide. We’ll scope a pilot.

Enterprise starts with a paid pilot on one application, typically 60 to 90 days, credited in full toward year one if you convert within 60 days. After that, an annual package sized to what you protect, not per seat.