Docs

Before you install

• Install on the computer that will run the agent. The command is a POSIX shell pipeline for macOS, Linux, or WSL. This command does not support native PowerShell.
• You need Node.js 20 or newer and tar. The release is bundled, so the installer runs no package manager.
• The command shown uses curl; the script also supports wget.
• Checksum verification needs one of shasum, sha256sum, or openssl.
• You can install and browse without a handle. Pulling a bundle needs a free handle.
• Runs need a reachable model endpoint or a host declared in the manifest. oloop can install and start declared hosts. The local Ollama samples need no API key.

Install the CLI

Run this in a POSIX shell. It installs the CLI only; it does not choose a setup, start an agent, or add the command to the parent shell's PATH.

curl -fsSL https://oloop.run/install.sh | sh

The installer checks the archive against SHA256SUMS. It stops if the hash does not match, and prints the installed version and hash. The release checksum is at /engine/SHA256SUMS.

A checksum proves that the bytes match the file published by the same origin. It is not an authenticity check. When the release publishes a signature and the installer carries a pinned release key, the installer verifies that signature too. A missing signature is not treated as a failed checksum.

Install location and project root

The installer does not edit your PATH, shell config, or system package managers. Set OLOOP_HOME before the command to choose a different CLI location. This command removes the default CLI installation:

rm -rf ~/.oloop

Project roots and their hosts need separate removal. This does not stop running model hosts. Remove project state through the CLI before deleting its folder.

Add the command to your PATH

Default installation, current shell. Run this for the current shell. Add it to your shell config if you want it in new shells.

export PATH="$HOME/.oloop/bin:$PATH"

A custom OLOOP_HOME needs its own printed path instead of $HOME/.oloop. The CLI location is not the same as the project runtime root (<project>/.oloop/).

Installing the CLI is not setup compatibility

The CLI can install without a setup. It does not prove that a setup will bootstrap on this machine. The engine gates fresh setup bootstrap only when no setup is named: macOS on Apple silicon. An explicit setup reference runs on the platform its catalog entry declares, including Linux x64, subject to that entry's RAM, VRAM, and driver checks. Native Windows is not supported and has no oloop setup; WSL2 installs the CLI and uses the Linux path, not a native host. Other CLI commands can still run. Check Machine setups for tested hardware and evidence, or the local machine pages for the measured setups.

Local model guides

The measured machine setups answer "what should I run on this machine?" with a dated qualification record. The guides explain the choices the catalog cannot prove yet. The 3 measured pages:

• Apple silicon, 64–128 GB: tested on an M4 Max with 128 GB.
• NVIDIA L4, 24 GB: 3 measured configurations on one L4.
• Linux CPU, 8–32 GB: tested on a 7 GB Linux x64 container.

Model rows

A model row is a YAML file that describes a model endpoint. It can name a server's baseUrl or the model served by a declared host. The manifest selects the model. oloop stores model rows under the project root's models/ directory. These read-only rows are examples:

• qwen2.5-0.5b.yaml: a local Ollama row that needs no API key.
• qwen3.8-latest.yaml: a local Ollama row.
• qwen3.8-27b-4bit.yaml: a model row for a declared host. The host supplies its endpoint.

An agent page's run block downloads its model rows. A row for an existing server still needs that server to be running.

Exact plan or adaptive

A manifest does not declare this mode with a field. The presence of oloop.lock beside the manifest is the declaration: a lock means Exact plan; no lock means adaptive.

An exact artifact is generated by oloop setup or oloop lock and ships inside the checksummed bundle. Its lock records the harness and host versions, the model identity, the resolved plan values, the normalized serve argv, the environment key names, the workloads, and the machine floor. At run time the lock wins: oloop builds the plan from it and compares the adapter's argv and env keys. A behavioral difference fails lock_stale and names the changed field with both values. A machine that misses the lock's requires fails host_platform_unsupported or host_hardware_insufficient. oloop does not substitute a smaller model or a different host. Re-baseline a local copy with oloop lock; oloop lock --check exits 1 on drift and is a clean CI gate.

An adaptive artifact resolves against the machine at run time, records the choice in the project root's state, and carries no lock. A comment-only manifest edit does not move an exact artifact's plan hash; adding a serve flag does.

Neither mode promises identical tokens, timing, or output. An exact artifact pins the plan, not the output.

Claim a handle

A handle names your public agents and configs. Claim one with the CLI:

oloop hub claim <handle> --email <you@example.com> --wait

You can also reserve a handle on the site. It prints an install command with a single-use claim ID. The CLI creates your key and prints a verification code. Email the code from your chosen mailbox to the address shown. You do not need a password.

Back up your key. oloop hub claim writes it to ~/.oloop/hub-key by default. If you lose it, use oloop hub recover <handle> --email <you@example.com> from your bound mailbox. Completed recovery revokes the old key and all sessions.

Publish an agent

# from a directory with outerloop.yaml + AGENT.md (+ optional skills/, commands/, models/):
oloop publish <dir> <art> <semver>

Publish stores an immutable version bundle, an @latest pointer, a version index, and a public page. The page shows AGENT.md, the manifest, declared tools, and recent versions. Publishing the same version and bytes again makes no change. Different bytes for that version cause a conflict.

oloop hub rm replaces the agent page with a deletion notice. Old pinned bundles remain available unless operators withdraw the artifact. Restore a deleted artifact with oloop hub rollback.

Fetch a public manifest

First install oloop and add it to PATH. Then use the name and version you received:

oloop pull <owner>/<name>@<version>

Run the command from the directory where the files should go. oloop pull writes the manifest and its files into the current directory. It does not start the agent. Pulling an exact version never substitutes a newer one. Without a version, the CLI uses the @latest pointer.

The CLI asks before overwriting existing files. Use --force only when you mean to replace them. Pulling a bundle needs a free handle: reserve one, or let oloop pull start the claim.

A withdrawn artifact is not available for new pulls. A deleted artifact page keeps old pinned bundles available unless operators withdraw them. Pinned bundles already in your project root still run offline. An API outage blocks new pulls only.

Verify a manifest

oloop verify <owner>/<art>[@<version>] pulls the manifest, runs the task for real, and judges the result with the manifest oracle. It then posts the result to the Hub. This is not a preview or a dry run.

Verifying needs a free handle. If you have no stored key, the CLI starts the claim on first use. The result is public under your handle.

An oracle pass means its configured check passed. It is not a security review and does not guarantee a correct answer. A Verified run means the manifest oracle passed in a reported real run under Hub checks. A Failed run reached the oracle and did not pass.

A submitted result is credited only after Hub checks and the next hourly rollup. A held result is not credited immediately. Your profile link is a place to check credit, not a promise of it.

The run and its upload are separate. The receipt records submitted or not submitted. If the upload fails, the run outcome and the exit code do not change, and your local result is saved. Offline, the CLI prints Not submitted. Your local result is saved. A run ticket may expire before a retry.

Reading the site

Machine setups lists setups, hardware requirements, and test evidence.

These labels explain setup evidence, provenance, and handle payment:

Digests identify published bytes. Request counts measure requests, not runs or users. Read the window and refresh label beside each count.

Data and privacy

The CLI sends a coarse machine profile and your use of public manifests to oloop.run by default. This is the recommendations feature; it sends no prompts, files, paths, or keys. The profile fields are platform, arch, ramClass, cpuCores, chipFamily, osFamily, and gpu. The usage event fields are kind, manifest, version, harness, host, machineClass, outcome, and engineVersion. Turn automatic sends off with oloop recommendations off; list them with oloop recommendations status. Hub commands (pull, publish, login) and model calls still use the network when it is off. An API outage blocks new pulls only; pinned bundles already in your project root still run offline. Read the Privacy policy for the full inventory, retention, and deletion. Clear the stored session machine profile with DELETE /api/session/machine; the next hourly rollup recomputes the affected aggregates. It stops future sends from that session; it does not erase counts already aggregated. Per-handle stats and verified runs are public under the handle, not anonymous. Read the Terms for publishing rules.

Why one root

oloop installs a pinned harness under the project root. It does not use a harness from your PATH or your global provider config. Existing model servers are referenced by baseUrl. Declared hosts can be installed and started under the root.

Benchmark methodology

Benchmark numbers are self-reported real runs, not laboratory measurements. The metric is decode throughput in tokens-per-second (tokensPerSecond), captured by the CLI from a real verify or exec run and keyed by model, quantization, machine class, and host. The Hub folds each sample into a fixed 64-bucket log-spaced histogram, so storage stays bounded and the percentiles are reproducible. Simulated probes and --machine overrides are excluded. Missing measurements are omitted, never guessed.

A cell is published only with at least 5 samples from at least 3 distinct handles. Below either floor, the page shows "Not enough data yet" and no number. Published numbers are the median (p50) and the 90th percentile (p90) of tokens-per-second; minimum and maximum are bucket edges. Precision is bounded by the bucket width, about 12%.

Throughput varies with quantization, context length, batch and prompt shape, thermals, background load, and the harness and host build. The numbers are guidance for a machine class, never a guarantee. Read the Privacy policy for what a run sends.