Install Zeroshot

Install the zeroshot command and its agent skills through the npm delivery package, which requires Node.js 18 or newer. The installer selects the release target declared for the current system and checks the downloaded archive against SHA256SUMS before writing the native executable.

npm install --global @the-open-engine-company/zeroshot

A canonical CLI release can update its executable and managed agent skills in place. The command selects the newest GitHub release for the current platform, verifies its archive and skill assets against that release's SHA256SUMS, and verifies the new executable before replacing the old one:

zeroshot update

The update does not elevate privileges; the current executable must be writable by the caller. Unchanged managed skill copies are installed or refreshed for Codex, GitHub Copilot, Pi, and Claude Code. A user-edited or conflicting skill is preserved, and the command fails with its exact path after completing any safe updates.

An older updater that only installs the zeroshot skill needs a second zeroshot update after replacing the executable to install zeroshot-memory-init. The new updater refreshes skills even when the executable version is already current.

Release builds cover Linux x64 and arm64, macOS x64 and arm64, and Windows x64. Node.js is only an installer dependency; the command itself is a Rust executable.

The package installs the zeroshot and zeroshot-memory-init skills for Codex, GitHub Copilot, and Pi under $HOME/.agents/skills/<name>, and for Claude Code under ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/<name>. No agent selection or per-project installation is needed. npm 7 and newer do not run uninstall hooks; after removing the package, remove only unmodified managed skill directories from these locations. When set, CLAUDE_CONFIG_DIR must be absolute so the global skills have stable locations.

See Active Memory storage and backups for the local lesson database and how to preserve it when moving or reinstalling Zeroshot.

On Windows, the CLI and local in-process runs work natively from PowerShell or Command Prompt. Install Git for Windows and put Git and your chosen harness on PATH; npm-installed .cmd launchers are supported. Local configuration defaults to %LOCALAPPDATA%\zeroshot and run state to %LOCALAPPDATA%\zeroshot\state. ZEROSHOT_CONFIG_DIR and ZEROSHOT_STATE_DIR can override these with absolute paths. The hosted target image requires Linux.

For Codex, complete its native Windows sandbox setup if your Codex permission settings require it. Workers and reviewers use the same permission handling; Zeroshot does not install the sandbox.

Connect Zeroshot Platform

The Platform target is built in. Sign in once; organization selection happens in the browser:

zeroshot target login platform

Platform runs use --target platform. Omit --target for local execution. The Zeroshot Platform docs cover organizations, the GitHub App, and saved connections.

Open the workspace UI

zeroshot ui

Open http://127.0.0.1:4173/ui/ to edit profiles and inspect live or completed local runs. Use --listen 127.0.0.1:4185 to choose another loopback port. Ctrl-C stops the UI server; active runs continue. Restart the command to reconnect.

To inspect runs on a configured target while keeping profiles in the local CLI store:

zeroshot ui --target docker

Use --target platform after signing in to inspect Platform runs through the same local UI.

Profiles edits graphs and runtime settings; the info icon explains authoring defaults. Saved profiles share the CLI's configuration store (ZEROSHOT_CONFIG_DIR); without --target, run history uses ZEROSHOT_STATE_DIR. Start a saved local profile from the CLI:

zeroshot run --title "My task" --profile local:my-profile --input input.json

Open Runs for live monitoring and replay. The Docker target serves its own profiles and runs at /ui/. Platform embedding remains tracked in zero-cloud #301.

Release executables embed the UI. To build it from source:

npm --prefix ui ci --ignore-scripts
npm --prefix ui run build
cargo build --release --package zeroshot --features ui
./target/release/zeroshot ui

Node.js is needed for this build, not to serve the resulting UI. Library consumers can leave the ui feature disabled.

Prepare a local run

Choose an existing working folder with --cwd FOLDER, or use the invoking folder. Local runs without Git delivery do not need a repository. Install each agent harness named by the runtime plan:

• install and sign in to Codex for "harness": "codex";
• install and sign in to Claude Code for "harness": "claude";
• install GitHub Copilot CLI 1.0.86 for "harness": "copilot" with "provider": "github";
• install and sign in to Pi for "harness": "pi".

Local GitHub pull request delivery (--pr or --ship) also needs the GitHub CLI, gh, on PATH. Zeroshot runs the gh that PATH finds and rejects the run before any agent starts if there is none.

Local Codex/OpenAI, Claude/Anthropic, Copilot/GitHub, Pi/Anthropic, and Pi/OpenAI lanes reuse the installed harness's native login and configuration. Other provider lanes can read declared values from the current environment or the private Zeroshot connection store. For example, this command prompts without echo and keeps an OpenAI value out of runtime JSON for a contained target:

zeroshot connection set openai --field OPENAI_API_KEY

Use openrouter, anthropic, bedrock, or gateway as the connection key when the effective runtime declares that provider. Runtimes and connections lists the automatic requirements and explains the separation.

Other installation paths

Each GitHub release includes native archives, the canonical zeroshot-skill.md and zeroshot-memory-init-skill.md, and SHA256SUMS; archive names contain the release version and target triple.

The Python SDK requires Python 3.11 or newer and ships the matching executable inside each platform wheel. Download the wheel for your OS and CPU from Python SDK releases. Replace WHEEL_FILE with its local path:

python -m pip install WHEEL_FILE

For a long-running target, use ghcr.io/the-open-engine/zeroshot-target. See the targets guide for a Docker setup bound to loopback.

Validate and run a first task after installation.

GitHub Copilot

Copilot uses your GitHub user identity and Copilot entitlement. Local runs reuse the login stored by copilot login in COPILOT_HOME or the system credential store. Ambient COPILOT_GITHUB_TOKEN, GH_TOKEN, or GITHUB_TOKEN values stay in private RPC and are excluded from agent tool environments. For a contained target, store a user OAuth token or fine-grained personal token with Copilot Requests permission in the github connection's COPILOT_GITHUB_TOKEN field. A GitHub App installation token is not the user-backed route.

Local Copilot BYOK settings such as COPILOT_PROVIDER_BASE_URL, the static provider credential, headers, wire API, and wire-model mapping are also reused. Zeroshot transfers that provider configuration into the private headless RPC session and strips its credential fields and native credential-store locators from tools. Command-backed keys configured with COPILOT_PROVIDER_API_KEY_COMMAND cross that private provider contract, so the pinned CLI refreshes them for each provider request. Eligible helper-only invoking-shell fields are exhaustively marked through Copilot's --secret-env-vars, keeping them out of shell and MCP tools; runtime, auth, provider, and parent-process loader controls are excluded. Zeroshot also reads a bounded COPILOT_PROVIDERS_CONFIG or default COPILOT_HOME/providers.json registry and transfers its providers and models into the headless session; a nonempty registry takes precedence over legacy provider variables. An explicit declared GitHub token suppresses ambient BYOK and offline controls. Declared credentials replace other ambient credential forms, and a declared endpoint does not inherit ambient credentials or headers.

This is Copilot's native same-user boundary: secret fields are not inherited by ordinary shell or MCP environments and are redacted from output, but the flag is not OS isolation from an adversarial process running as your own user.

{ "harness": "copilot", "provider": "github", "model": "auto" }

Model IDs pass unchanged to the Copilot process. When a registry entry with apiKeyCommand must use Copilot's singular provider contract, its authored modelId becomes the RPC session model and its authored wireModel still names the provider request model. Zeroshot uses headless RPC schema output and validates each response locally, allowing at most two correction turns in the same session. Install the pinned CLI version above; the target image already includes it.

Hosted connection resolvers may additionally declare COPILOT_GITHUB_TOKEN_EXPIRES_AT (Unix seconds). Copilot then requests credentials through the resolver throughout a long execution. The callback must match COPILOT_GH_HOST (or GH_HOST) when configured. The resolver must return a refreshed token with more than one hour remaining. Static tokens without expiry metadata are supplied once when each provider process starts.