Use Octopus in five minutes.

Install Octopus, run one Goal, open the local Goal/Need/Feed app, then use Doctor, Preflight, routes, and the pixel Octopus as evidence.

Read the docs tutorial or follow the steps below.

One local product path

1. Install

cargo install --git https://github.com/dangoZhang/Octopus octopus-core --locked --bin octopus --force
octopus --version

The binary includes the runtime, seed tentacles, local app, and state observer.

2. Give it a Goal

octopus first-run "make this repo easier to use"

The brain writes a Goal and one clean Need. A tentacle chooses how to observe, acts, returns compact Feed, and records feedback.

3. Open the local app

octopus start --open

The app reads local state and shows Goal, Need, Feed, Output, and pet status.

4. Keep steering by Goal

octopus chat "make setup clearer"
octopus goal refine "prefer small reviewable changes"

User input stays on Goal. Tool choice, repair, provider routing, and harness changes stay agent-internal or observable.

5. Read the evidence

octopus doctor
octopus report
octopus preflight
octopus pet desktop

Doctor shows readiness. Report shows capability and gaps. Preflight shows blockers. The native pet shows state after the first loop exists.

What a tentacle is

A tentacle is a local nervous system for tools. It receives a Need, handles the tool work locally, checks the result, and returns compact Feed. The seed tentacles start with repo work, computer use, maintenance, repair, write-and-run execution, and visual state.

What the brain sees

The clean brain sees only Goal, Mem, Need, and Feed. It asks for verification, comparison, reproduction, memory, forgetting, recall, or execution. The tentacle handles the implementation burden.

Add a model when ready

Octopus can use Codex login, direct API keys, local OpenAI-compatible servers, or a gateway such as LiteLLM. Provider setup is runtime plumbing, so Need text stays clean.

codex login
export OCTOPUS_LLM_BACKEND=codex
export OCTOPUS_LLM_CODEX_COMMAND=codex
octopus provider status
octopus first-run --live "make this repo easier to use"

export OCTOPUS_LLM_BACKEND=openai-compatible
export OCTOPUS_LLM_MODEL=gpt-4.1-mini
export OCTOPUS_LLM_BASE_URL=https://api.openai.com/v1
export OCTOPUS_LLM_API_KEY=<api-key>
octopus provider check

octopus provider status shows Goal chat, clean brain, tentacle planning, and harness evolution readiness. Codex OAuth and local models can be ready without an API key; provider check and preflight --live provide live proof.

When it learns

Feed traces, check history, and repair outcomes can become harness recommendations. High-risk changes stay reviewable under .octopus/ before any apply path.

octopus first-run "make this repo easier to use"
octopus chat "tighten setup from the latest Feed"
octopus beat 200
octopus report