> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiloop.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Drive hiloop from your coding agent

> Let a host-side coding agent use the CLI with a least-privilege credential.

A coding agent can operate hiloop through the same CLI you use. Install the skills for the
harness, give the host process a least-privilege hiloop credential, and require explicit project
selection.

## Install the skills

```sh theme={null}
curl -fsSL https://hiloop.ai/install.sh | sh
hiloop skills install <harness>
```

Supported harness names include `claude-code`, `codex`, `cursor`, `gemini`, `copilot`, and `all`.
Restart the agent after installation so it discovers the skills. The skills teach the agent the
current command surface, including which verbs are still landing and how their refusals read.

## Authenticate the host-side agent

For a supervised session, run `hiloop login`. For unattended automation, inject a scoped
`HILOOP_API_KEY` into the host-side agent process through your secret manager. The agent should
begin with:

```sh theme={null}
hiloop whoami
hiloop projects list
```

Never put a hiloop key or a model-provider key into a sandbox command, image, or metadata.

## Give it an outcome

A useful prompt is:

```text theme={null}
Use the hiloop CLI to work in project demo. Create a sandbox from
ghcr.io/acme/research-agent@sha256:..., run the repository tests in it, report the result, and
delete the sandbox when finished. If a command is refused with an explicit capability error,
stop and report the exact error.
```

The important operating rules are:

* select at most one source on create, `--image <ref>` or `--from <snapshot>`; omitting both
  selects the platform default image;
* pass `--idempotency-key` on creates the agent may retry;
* treat fail-closed refusals (`unsupported_capability`, `unavailable`) as real; never work
  around them by weakening the request;
* record sandbox and snapshot ids as they are returned, and poll with a bounded deadline;
* delete sandboxes when the task is finished.

## Long-running and interactive work

For an attached terminal, or to run one command in a running sandbox, `hiloop sandbox ssh` connects
with stock OpenSSH; a remote command's exit code becomes the CLI's exit code, so an agent can branch
on it directly. The shell runs inside the workload container, so it sees the same filesystem `exec`
does, and
several SSH features are refused by design (see
[interactive access](/sandboxes/commands-executions#interactive-access)). The verb needs the sandbox
SSH endpoint, which is off unless your deployment enables it, so treat an
`unsupported_capability` refusal as "not enabled here" rather than a transient fault to retry.
A `sandbox_session_unavailable` refusal is the different case: SSH is enabled, but this sandbox has
no running instance to reach right now.

`hiloop sandbox exec` runs bounded commands, and splitting unattended jobs into bounded steps lets a
branch resume from the last good state.

## Model access

Platform-managed provider keys are never injected into a sandbox. The approved
[model gateway](/deployment/model-gateway) target keeps them outside the guest and authorizes each
request from a short-lived workload proof, but that sandbox path is not deployed today. The
existing Rust body proxy is operator-only. Direct provider access is not a supported fallback, so
clean sandbox model access remains unavailable.

To keep work across a stop and start, create the sandbox with `--storage-class durable` and write
under `/workspace`; files there survive, though processes do not resume.

Snapshot and branch (`hiloop sandbox snapshot create`, then `hiloop sandbox create --from <snapshot>`) is the way to preserve work *between* sandboxes: a snapshot outlives the sandbox it was
taken from, and several sandboxes can start from one and diverge. See
[snapshots and branching](/concepts/workspaces) for the model and
[what's live today](/sandboxes/overview#whats-live-today) for current status.