Getting started

Documentation · Installation · Providers

This is the shortest safe path from an installed octet to a first useful, tool-using coding task. Choose an installation lane, choose one provider lane, verify it with a read-only request, and only then allow edits or commands. Shell commands are in sh blocks; text in text blocks is entered inside the interactive Octet UI, not in your shell.

Version boundary. This guide targets octet 0.8.0. Check octet --version and octet --help for the binary you will run. Source builds are not signed release artifacts, and older binaries may not include these options.

1. Choose an installation lane#

macOS or GNU/Linux x86-64: published native binary#

The current native release supports macOS Apple silicon/Intel and GNU/Linux x86-64. Install from the version-pinned release, then check the version:

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

Expected output includes octet 0.8.0. The release page is authoritative for signed assets and availability; npm, Homebrew, crates.io, and SDK registries are separate unpublished channels.

Intentional source checkout: macOS or GNU/Linux#

Use this lane only when you intentionally need the checkout under test. Install Rust 1.86+ and ripgrep, then build and run the binary by its full path:

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

A source build does not replace an installed copy or establish release publication. Use the matching binary consistently for the rest of this guide.

Native Windows#

There is no published native Windows download or support claim in this release snapshot. Do not treat WSL, cross-compilation, or a macOS/Linux check as native Windows qualification. Stop at this availability gate and use a separately qualified Windows instruction when one is published; do not invent a download URL.

2. Start in the repository you want to change#

Run the following shell commands from the target repository root, not from the Octet installation directory:

cd /path/to/project
octet --workspace "$PWD" --help

The --workspace form is optional when the shell is already in the repository. Relative tool paths and the default command working directory use this workspace.

For a repository you have not reviewed, begin without --workspace-trusted. That keeps project .octet configuration, AGENTS.md, and project resources out of the initial context. After reviewing those files, add --workspace-trusted on a later launch if you want them loaded; it does not grant executable-extension trust or relax safety floors.

Use --safe-mode for the first run. It asks before every workspace mutation and shell call, disables external paths, and keeps executable extensions stopped. It is an approval policy, not an operating-system sandbox; use an isolated account, container, VM, or platform sandbox for untrusted code. Full access is the default when --safe-mode is absent and is appropriate only inside a boundary you chose.

3. Choose one provider lane#

Provider setup, model availability, and connection verification are separate. No extension is needed for this first coding task: installing an extension, enabling it, trusting it, configuring it, and verifying its capability are separate actions. Never put a credential value in a prompt, URL, repository file, shell command, history, or session fixture.

Interactive setup#

For an unconfigured octet 0.8.0 installation, start without --model:

octet --safe-mode

Choose Add an API key (the first choice), Sign in with ChatGPT / other supported OAuth subscriptions, or Local/self-hosted models. You can also continue without a provider. Existing model inventories and explicit model selections do not reopen this onboarding flow; print/RPC never open it.

For an API key, select a listed provider, paste into the masked secret input, and review Save API key. Do not paste it into the conversation composer. Octet saves a recoverable key in owner-private storage: this is not a hash or an encrypted vault. No environment variable is required for this path. Saving a key and discovering models are separate from verifying inference; if discovery fails, the saved key can remain for retry. Select a model from the refreshed picker, then follow the read-only verification step below.

For subscription sign-in, choose ChatGPT (OpenAI Codex) or GitHub Copilot and authorize on the provider's device-login page. Only those two subscription flows are offered; availability depends on your account and supported routes. Restart without --offline to sign in. For a local server, select the explicit endpoint and review the model/credential policy before saving.

See first-run privacy and limits. The following shell alternatives also work when you do not use onboarding.

A. API key (OpenRouter example)#

Prerequisite: an OpenRouter account, a usable API key, and a model available to that account. Load the key into the environment without putting its value in a command. On a Bash-compatible shell, this value-free pattern reads it at a hidden prompt:

read -r -s OPENROUTER_API_KEY
export OPENROUTER_API_KEY

If the shell does not support that pattern, use its password manager or secret manager integration. Never replace the commands with a literal key.

Start from the repository root and choose a model from the live OpenRouter inventory or the /model picker:

octet --safe-mode --model 'openrouter/PROVIDER/MODEL'

The quoted ID is a placeholder. openrouter/anthropic/claude-sonnet-4.6 is an example of the shape only; account, model, and endpoint availability are specific to OpenRouter. OpenRouter uses its built-in route and OPENROUTER_API_KEY; do not turn it into a custom endpoint merely to copy a credential value into a URL. Initial discovery is optional but useful for the picker; --offline skips it and still does not disable inference traffic.

B. Subscription login#

Prerequisite: an account that can use the hosted Codex subscription flow and a browser (or a second device) for device authorization. Run this in a shell; the command exits after login:

octet --login codex

Octet prints the OpenAI verification URL and a one-time code. Keep the code private and enter it only on the OpenAI page. If opening a browser is not available, use the same flow without a browser opener:

octet --login codex --headless

After authorization, start from the repository root with a model ID listed by your account-scoped inventory:

octet --safe-mode --model 'MODEL_ID'

MODEL_ID is a placeholder, not a promise of availability. For example, use gpt-5.6-luna only if it is listed for this account; Astra may be listed as codex/gpt-6-astra. A subscription plan or model name alone does not authorize an unavailable model. --offline can use fresh cached/fallback metadata but does not verify live availability or make inference local.

For GitHub Copilot, use the same first-run subscription menu or the CLI device flow:

octet --login copilot --headless
octet --safe-mode --model 'github-copilot/MODEL_ID'

Select only an eligible model discovered for your account. Offline startup adds no Copilot models; unsupported routes are not advertised. See the Copilot limits.

C. LM Studio or another local compatible server#

Prerequisite: start the local server, load a model, and note its API model ID. LM Studio's documented OpenAI-compatible default is http://localhost:1234/v1/. Compatible servers such as llama.cpp, vLLM, and SGLang may use another explicit /v1/ URL. This setup flow does not scan localhost or the network.

The current-checkout setup flow is review-first. --manual-model avoids the setup probe; the first command prints a receipt and does not write provider state:

octet setup --preset lm-studio --manual-model LOCAL_MODEL_ID

Review the endpoint, model, credential policy, and authority lines. Then repeat the command with --yes to commit the reviewed values:

octet setup --preset lm-studio --manual-model LOCAL_MODEL_ID --yes
octet --safe-mode --model 'custom/local/LOCAL_MODEL_ID'

To use one bounded /models discovery request instead, omit --manual-model in the preview, copy the discovered API model ID from the receipt, and commit only after review. The setup discovery pass sends at most one request to the selected endpoint; a confirmed rerun may probe again unless it also uses --offline --manual-model:

octet setup --preset lm-studio
octet setup --preset lm-studio --model LOCAL_MODEL_ID --yes

For another explicitly selected compatible endpoint, use --endpoint; no probe or write is the safest recovery when paired with --offline --manual-model:

octet setup --endpoint http://127.0.0.1:8000/v1/ \
  --no-auth --offline --manual-model LOCAL_MODEL_ID
octet setup --endpoint http://127.0.0.1:8000/v1/ \
  --no-auth --offline --manual-model LOCAL_MODEL_ID --yes

Replace --no-auth with --api-key-env LOCAL_API_KEY when the server requires a bearer key; never use both options. The variable name is stored, not its value. --manual-model supplies an explicit inventory and does not test inference; the first task below is the connection check. Setup stores custom provider state in an owner-private registry and saves the selected model preference only after catalog verification. In the CLI, --cancel returns before endpoint discovery; an interactive cancellation after discovery cannot undo that prior request.

4. Verify the route before allowing changes#

Inside the TUI, /status shows the selected model, route, and capabilities. It is an interactive command, not a shell command. Use the exact model ID from the provider lane you chose (custom/local/LOCAL_MODEL_ID for the manual local recipe). A narrow first request can verify provider inference and the read/search tool boundary without permitting edits or commands:

octet --safe-mode --tools read,search --no-edit --no-write --no-process \
  --no-context-files --model 'MODEL_ID'

Submit this in the TUI:

Read the repository's top-level manifest and locate one relevant source/test pair for my small coding task. Tell me which files you inspected, what the project uses to verify changes, and one narrow next step. Do not edit files or run commands.

Expected first outcome: a response naming real repository paths and a verification plan, with no file mutation and no shell call. A successful response is a useful live smoke check for the selected route, not proof of every model, provider, terminal, or network condition.

After reviewing the project instructions and that response, start the first change-capable session. Keep safe mode and approve each proposed effect yourself:

octet --continue --safe-mode --model 'MODEL_ID'

Then enter a small, bounded task such as:

Implement the smallest change needed for [my small coding task]. Inspect the
relevant source and nearest tests first. Ask before every edit or command, show
changed paths and the diff, and stop for my review before committing.

If you intentionally reviewed and want project instructions loaded, add --workspace-trusted to this launch. Trust is independent from tool enablement; --safe-mode still prevents executable extensions and asks for mutations and shell calls.

5. Recovery when setup or a model is missing#

For detailed transport, credential, discovery, and reasoning limits, see providers, CLI setup options, and tools and permissions. For durable session recovery, see sessions.

Source identity#

Octet source names are octet, octet-host, octet-*, OCTET_*, and .octet. An Octet installation does not migrate Ygg data automatically. Keep provider credentials and sessions in their owner-private stores, and keep all values out of prompts, screenshots, support reports, and issue bodies.