Installation

Documentation · Getting started

Install native binaries#

Native v0.9.5 packages target macOS Apple silicon and Intel, GNU/Linux x86-64, and Windows x86-64 (MSVC, preview). Use the version-pinned GitHub release for signed assets, exact-source CI and public-install receipts. Use only channels recorded as available there; unsigned development artifacts are not a release. The v0.9.5 notes separate shipped scope from unqualified acceptance. The experimental Pi compatibility extension is not shipped.

Windows support is a preview. On Windows x86-64, download the version-matched install-octet.ps1 from that release and run it in PowerShell. It checks the ZIP against the checksum manifest, but does not independently verify its Sigstore signature. Native MSVC artifact qualification is separate from GNU test builds.

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/skaft-software/octet/releases/download/v0.9.5/install-octet.sh | sh
octet --version   # octet 0.9.5

When moving from Ygg, install octet afresh. Older installations and data stay untouched, and there's no automatic migration. Homebrew, crates.io and SDK registries remain separate, unpublished channels. CLI installation with Bun is unqualified.

Install from npm#

v0.9.5 is not yet published to npm.

After approved npm publication, Node.js can install the same signed platform package on macOS Apple silicon and Intel, GNU/Linux x86-64, and Windows x86-64:

npm install -g @skaft/octet@0.9.5
octet --version   # octet 0.9.5

This installs the @skaft/octet launcher plus the matching platform package (@skaft/octet-darwin-arm64, @skaft/octet-darwin-x64, @skaft/octet-linux-x64-gnu, or @skaft/octet-win32-x64) with npm provenance, from the same verified release assets as the native installer. The launcher has no install-time lifecycle scripts. To pin an exact version instead of tracking latest, use npm install -g @skaft/octet@0.9.5 (distribution). npm publication is separate from native publication; do not use this command until v0.9.5 registry publication and provenance are recorded on the release page. See Windows for native versus unsigned test-build boundaries. Distribution channels has the exact boundaries. The historical Ygg instructions describe older releases, not a way to install or migrate to octet.

The repository is now skaft-software/octet, and the existing v0.7.0 signatures and assets are unchanged. For a source install, use a checkout or the Git-tag Cargo command in distribution. The immutable v0.7.0 installer's --from-source mode expects the old repository archive directory name and isn't supported after the rename. Its default native mode is unchanged.

Installer progress#

On an interactive terminal, the installer and octet update show the monochrome octet byte mark and the target version, with progress on stderr. The mark uses your terminal's default foreground, with an ASCII fallback outside UTF-8 locales and a compact layout on narrow terminals. Redirected output and a missing or dumb TERM get plain stage messages without animated terminal controls.

Update and release notes#

Run octet update to update through the channel that installed the binary, then restart octet. On Windows, an install-octet.ps1 installation in its default %LOCALAPPDATA%\Programs\octet\bin directory is updated by re-running the version-pinned PowerShell installer. octet update --check checks without installing. Starting an interactive session also makes one quiet, bounded release check unless --offline is set. A newer stable release adds an octet update hint to the splash, or a single notice at the live tail if the splash is already in history. Failures don't block startup or show an error. There's no automatic installation, provider request, credentials, periodic polling or persistent update cache. Proxy-only networks don't get this optional direct-HTTPS startup notice.

From 0.7.5 onward, /changelog opens the current binary's bundled release notes in the TUI as rich Markdown. Up and Down, PageUp and PageDown, Home and End scroll, and Escape or Left returns to the input. It works offline and doesn't send the notes or the command to the model.

Build from a checkout#

This checkout targets octet 0.9.5. Check octet --version, and use matching source extension manifests from this checkout. A source build isn't a signed release artifact and doesn't replace an installed binary.

On macOS or GNU/Linux, install Rust 1.88+. ripgrep is optional: content search prefers rg when available and falls back to grep. From the source checkout:

cargo build --release --locked -p octet-coding-agent --bins
./target/release/octet --safe-mode

This builds octet and octet-host under target/release without replacing an installed copy. For only the terminal binary, use cargo build --release --locked -p octet-coding-agent --bin octet. Normal builds use the checked-in model metadata and never refresh the catalog over the network. Next, connect a model.

On Windows, build the x86_64-pc-windows-gnu target with a MinGW-w64 toolchain as described in Windows. Bash commands there need Git for Windows or another Bash-compatible shell.

Optional packages#

Executable extension bundles are pinned to the host version. After publication, install assets matching octet 0.9.5 from its version-pinned release. Until then, run reviewed source extensions from this checkout with --extension-dir ./extensions. The 0.8.0 bundles need their 0.8.0 host.

octet extension install octet-web-search
octet extension list

For a reviewed local archive instead, use octet extension install --path ./bundle.tar.gz. Installing is inert: it doesn't enable a package, save a trust grant, start code or set up dependencies. Full access implicitly trusts selected executable extensions, but enabling stays explicit. Safe mode starts only enabled extensions with host authority for their selected source; ungranted sources stay stopped. --trust-extension, an explicit --extension-dir, or a source-bound trusted_extensions grant can supply that authority, but never enables a bundle. --no-process/--no-shell, workspace trust, and compatibility/integrity checks still apply. Granted code runs with your OS permissions outside the tool-effect broker: safe mode is not an OS sandbox. Executable bundles are separate from the terminal binary. Resource discovery covers source selection, and extensions covers packaging, trust, atomic update and removal. Catalog install and update select the package that matches the running octet version. The command forms are in the CLI reference.

The five shipped executable-bundle manifests declare API 0.4, distribution version 0.9.5, and require octet =0.9.5. Older bundles stay pinned to their host. Distribution and host versions are independent boundaries, and an API number doesn't bypass the exact host pin. See current authoring for the Python API 0.4 process recipe and the retained API 0.3 conformance example. Generated contract bindings alone aren't a process runtime. octet-pi-compat is source-only experimental work and is excluded from the v0.9.5 catalog; previously installed experimental copies are not automatically removed.

Container#

The included linux/amd64 image is a source-build route, not evidence of a published image. These local-only commands label the source checkout and don't pull a published image:

scripts/build-octet-image.sh octet:local
docker run --rm -it \
  -e ANTHROPIC_API_KEY \
  -v "$PWD:/workspace" \
  octet:local --model claude-sonnet-4-6

The script builds a clean copy of your tracked Git files, refuses tracked changes and leaves out untracked workstation content. It uses digest-pinned base images and Debian package snapshots, runs unprivileged, and needs an explicit workspace mount. Pass only the credentials and paths you need. The packaged docs are read-only at /usr/local/share/octet, exposed through OCTET_PACKAGE_DIR. Read Security before granting access to sensitive files.