From d04f622317259ad017dc4777a27ffae46f7f36fb Mon Sep 17 00:00:00 2001 From: ajspig <46900795+ajspig@users.noreply.github.com> Date: Wed, 26 Aug 2026 11:39:58 -0400 Subject: [PATCH] docs: adding honcho start (#1073) * docs: make honcho start the documented local path honcho-cli 0.1.3 can run a personal stack without cloning the repo; point the README, self-hosting, and CLI reference at that, and drop the community installer callouts. Co-authored-by: Cursor * docs: updating with new CLI language * docs: drop compatibility-guide changes from this PR Leave that file on main; CLI version cards are updated at release time. Co-authored-by: Cursor * docs: small language changes --------- Co-authored-by: Cursor --- CONTRIBUTING.md | 5 ++- README.md | 37 +++++++++++++++---- SECURITY.md | 2 +- docs/v3/contributing/guidelines.mdx | 6 ++- docs/v3/contributing/self-hosting.mdx | 29 +++++++++++---- docs/v3/contributing/troubleshooting.mdx | 28 +++++++++++++- .../documentation/introduction/overview.mdx | 3 ++ .../documentation/introduction/quickstart.mdx | 4 +- .../documentation/introduction/vibecoding.mdx | 13 ++++--- docs/v3/documentation/reference/cli.mdx | 28 ++++++++++---- docs/v3/guides/integrations/hermes.mdx | 4 -- honcho-cli/README.md | 15 ++++---- 12 files changed, 127 insertions(+), 47 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7b131f70..b3e00a27 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -200,8 +200,9 @@ conventions, and is worth skimming even if you are not using an agent. ## Local setup -Get a stack running first — [Self-hosting in the README](./README.md#self-hosting) covers -both the Docker path and a manual Postgres setup. Then, for development: +To run a personal instance, install the CLI (`uv tool install honcho-cli`) and then run `honcho start --setup` (Docker + an LLM provider key — not the Honcho API key from `honcho init`) — [CLI in the README](./README.md#cli). + +To **develop this repo**, clone it and: ```bash uv sync # create the venv and install dependencies diff --git a/README.md b/README.md index 7c66cca3..2d354c66 100644 --- a/README.md +++ b/README.md @@ -11,11 +11,12 @@ ![Static Badge](https://img.shields.io/badge/Server-3.1.0-blue) [![PyPI version](https://img.shields.io/pypi/v/honcho-ai.svg)](https://pypi.org/project/honcho-ai/) [![NPM version](https://img.shields.io/npm/v/@honcho-ai/sdk.svg)](https://npmjs.org/package/@honcho-ai/sdk) +[![CLI](https://img.shields.io/pypi/v/honcho-cli.svg?label=honcho-cli)](https://pypi.org/project/honcho-cli/) [![Discord](https://img.shields.io/discord/1016845111637839922?style=flat&logo=discord&logoColor=23ffffff&label=Plastic%20Labs&labelColor=235865F2)](https://discord.gg/honcho) **Honcho is memory infrastructure for building stateful agents that understand changing people, agents, groups, projects, and ideas over time.** -Store messages and events, let Honcho reason in the background, then query peer representations, session context, search results, or natural-language insights from any model or framework. Use it managed at [api.honcho.dev](https://api.honcho.dev) or self-host the FastAPI server yourself. +Store messages and events, let Honcho reason in the background, then query peer representations, session context, search results, or natural-language insights from any model or framework. Use it managed at [api.honcho.dev](https://api.honcho.dev), run a local stack with [`honcho start`](#cli), or self-host the FastAPI server yourself. Using Honcho as your memory system will earn your agents higher retention, more trust, and help you build data moats to out-compete incumbents. @@ -29,6 +30,7 @@ Using Honcho as your memory system will earn your agents higher retention, more - [Quickstart](#quickstart) - [What Honcho Gives You](#what-honcho-gives-you) - [Integrations](#integrations) +- [CLI](#cli) - [Core Concepts](#core-concepts) - [Benchmarks & Evals](#benchmarks--evals) - [Self-hosting](#self-hosting) @@ -39,7 +41,7 @@ Using Honcho as your memory system will earn your agents higher retention, more - [Contributing](#contributing) - [License](#license) -The Honcho project is split between several repositories, with this one hosting the core service logic — implemented as a FastAPI server. Client SDKs for Python and TypeScript live in the [`sdks/`](./sdks) directory. +The Honcho project is split between several repositories, with this one hosting the core service logic — implemented as a FastAPI server. Client SDKs for Python and TypeScript live in the [`sdks/`](./sdks) directory. The [`honcho-cli`](./honcho-cli) package lives here too. ## Start Here @@ -47,7 +49,9 @@ The Honcho project is split between several repositories, with this one hosting | -------------------------------------- | ---------------------------------------------------------- | ----------------------------- | | Give my coding agent persistent memory | Claude Code, OpenCode, OpenClaw, Hermes, or any MCP client | [Integrations](#integrations) | | Add memory to my product | Python or TypeScript SDK | [Quickstart](#quickstart) | -| Self-host Honcho | Docker / local development | [Self-hosting](#self-hosting) | +| Run Honcho locally | Install CLI, then `honcho start --setup` | [CLI](#cli) | +| Inspect a deployment | `honcho workspace inspect`, `honcho doctor` | [CLI](#cli) | +| Self-host from source | Docker Compose or local development | [Self-hosting](#self-hosting) | ## Why Honcho @@ -56,7 +60,7 @@ The Honcho project is split between several repositories, with this one hosting | Reasoning-first memory | Extracts conclusions from conversations and events, not just matching chunks. | | Peer-centric model | Tracks users, agents, groups, projects, and ideas as entities that change over time. | | Multi-peer perspective | Models what one peer knows about another when configured. | -| Managed or self-hosted | Use `api.honcho.dev` or run the FastAPI server yourself. | +| Managed or self-hosted | Use `api.honcho.dev`, `honcho start` locally, or run the FastAPI server yourself. | | Agent-tool integrations | MCP, Claude Code, OpenCode, OpenClaw, Hermes, Cursor-compatible clients. | ## The Honcho Loop @@ -70,7 +74,7 @@ Concretely: workspaces hold peers, peers participate in sessions, messages live ## Quickstart -Get an API key at [app.honcho.dev](https://app.honcho.dev) — when you sign up you'll be prompted to join an organization, which gets its own dedicated Honcho instance and $100 free credits. Or [self-host](#self-hosting) and run against `http://localhost:8000`. +Get an API key at [app.honcho.dev](https://app.honcho.dev) — when you sign up you'll be prompted to join an organization, which gets its own dedicated Honcho instance and $100 free credits. Or install the CLI and run [`honcho start --setup`](#cli), then point the SDK at `http://localhost:8000`. ### Python @@ -226,12 +230,27 @@ For wiring the Honcho SDK into an existing application, install the integration npx skills add plastic-labs/honcho ``` -Then invoke `/honcho-integration` in Claude Code (or `/honcho-dev:integrate` via the plugin marketplace). The same command also installs the memory skills — `honcho-memory` (concepts: the recall/record loop, session and peer strategy, plus how to connect and drive an MCP-connected Honcho) and `honcho-cli` (inspecting and debugging a deployment). Details: [agentic development guide](https://honcho.dev/docs/v3/documentation/introduction/vibecoding). +Then invoke `/honcho-integration` in Claude Code (or `/honcho-dev:integrate` via the plugin marketplace). The same command also installs the memory skills — `honcho-memory` (concepts: the recall/record loop, session and peer strategy, plus how to connect and drive an MCP-connected Honcho) and `honcho-cli` (inspecting a deployment, or running a local stack with `honcho start`). Details: [agentic development guide](https://honcho.dev/docs/v3/documentation/introduction/vibecoding). ### Other MCP clients The same `claude mcp add` form (or its client-specific equivalent) works in any MCP-compatible client. See [MCP guide](https://honcho.dev/docs/v3/guides/integrations/mcp). +## CLI + +[`honcho-cli`](https://pypi.org/project/honcho-cli/) inspects a Honcho deployment from the terminal, or runs a personal local stack with Docker. + +```bash +uv tool install honcho-cli +honcho init # Honcho API key or browser login + server URL +honcho start --setup basic # local stack: LLM provider key + Docker +honcho doctor +``` + +`honcho init` authenticates the CLI against a Honcho server. `honcho start --setup` is a separate step: it writes the LLM provider key the local deriver needs and starts API + deriver + Postgres + Redis. + +Full commands and local-stack details: [CLI reference](https://honcho.dev/docs/v3/documentation/reference/cli) · [`honcho-cli/README.md`](./honcho-cli/README.md). To develop the server from source, see [Self-hosting](#self-hosting). + ## Core Concepts Honcho organises everything around **peers** — humans and AI agents alike are first-class entities. The peer model enables: @@ -275,9 +294,9 @@ Honcho's evals span LongMemEval, LoCoMo, and other long-conversation benchmarks. ## Self-hosting -Honcho is open source under AGPL-3.0. You can run the full server locally with Docker, then point the SDKs at `http://localhost:8000`. +Honcho is open source under AGPL-3.0. To **run** a personal instance, install the CLI (`uv tool install honcho-cli`) and then [`honcho start --setup`](#cli). The paths below are for building from source, contributing, or deploying without the CLI. -### Quick start (Docker) +### Quick start (from source, Docker) ```bash git clone https://github.com/plastic-labs/honcho.git @@ -633,6 +652,7 @@ For low-latency use cases, Honcho provides access to a `representation` endpoint - **Python** — [`honcho-ai`](https://pypi.org/project/honcho-ai/) on PyPI · source in [`sdks/python/`](./sdks/python) - **TypeScript** — [`@honcho-ai/sdk`](https://www.npmjs.com/package/@honcho-ai/sdk) on npm · source in [`sdks/typescript/`](./sdks/typescript) +- **CLI** — [`honcho-cli`](https://pypi.org/project/honcho-cli/) on PyPI · source in [`honcho-cli/`](./honcho-cli) · [CLI reference](https://honcho.dev/docs/v3/documentation/reference/cli) SDKs are versioned independently of the server. Current SDK versions track each other; the server badge above reflects the deployed server version. @@ -641,6 +661,7 @@ See the [SDK Reference](https://honcho.dev/docs/v3/documentation/reference/sdk) ## Learn More - [Developer documentation](https://honcho.dev/docs/) — full API surface, guides, integrations. +- [CLI reference](https://honcho.dev/docs/v3/documentation/reference/cli) — local stack, inspect/debug commands, scripting. - [Plastic Labs blog](https://blog.plasticlabs.ai/) — design philosophy and history of the project. ## Contributing diff --git a/SECURITY.md b/SECURITY.md index 1b71cb45..18d0ebfb 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -33,7 +33,7 @@ one. Test against an instance you operate. Do not run security testing against `api.honcho.dev` or against any Honcho deployment that is not yours — self-hosting is a first-class path and -takes a few minutes to set up, see [Self-hosting](./README.md#self-hosting). +takes a few minutes to set up — install the CLI (`uv tool install honcho-cli`) then run `honcho start --setup` (Docker + an LLM provider key), or see [Self-hosting](./README.md#self-hosting). ## What to Expect diff --git a/docs/v3/contributing/guidelines.mdx b/docs/v3/contributing/guidelines.mdx index b98bd5c9..92c42fcf 100644 --- a/docs/v3/contributing/guidelines.mdx +++ b/docs/v3/contributing/guidelines.mdx @@ -189,8 +189,10 @@ conventions, and is worth skimming even if you are not using an agent. ## Local setup -Get a stack running first — [Self-hosting](/v3/contributing/self-hosting) covers -both the Docker path and a manual Postgres setup. Then, for development: +To run a personal instance, install the CLI (`uv tool install honcho-cli`) and then run +`honcho start --setup` (Docker + an LLM provider key) — [CLI reference](/v3/documentation/reference/cli). + +To **develop this repo**, clone it and: ```bash uv sync # create the venv and install dependencies diff --git a/docs/v3/contributing/self-hosting.mdx b/docs/v3/contributing/self-hosting.mdx index 41a439f2..02d361f1 100644 --- a/docs/v3/contributing/self-hosting.mdx +++ b/docs/v3/contributing/self-hosting.mdx @@ -7,6 +7,8 @@ icon: 'computer' This guide helps you set up a local environment to run Honcho for development, testing, or self-hosting. +**Just want a running instance?** `uv tool install honcho-cli` only installs the `honcho` command. Then run [`honcho start --setup`](/v3/documentation/reference/cli#local-stack) (Docker + an LLM provider key) — that pulls a published image and starts API, deriver, Postgres, and Redis. The rest of this page is for building from source, contributing, or deploying without the CLI. + ## Overview By the end of this guide, you'll have: @@ -22,7 +24,7 @@ Before you begin, ensure you have the following installed: ### Required Software - **uv** - Python package manager: `curl -LsSf https://astral.sh/uv/install.sh | sh` or `brew install uv` - **Git** - [Download from git-scm.com](https://git-scm.com/downloads) -- **Docker** (required for Docker setup, not needed for manual setup) - [Download from docker.com](https://www.docker.com/products/docker-desktop/) +- **Docker** - required for the CLI local stack and the compose-from-source path; not needed for a fully manual setup. [Download from docker.com](https://www.docker.com/products/docker-desktop/) ### Database Options You'll need a PostgreSQL database with the pgvector extension. Choose one: @@ -59,13 +61,22 @@ DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1 For recommended model tiers per feature, using multiple providers, or direct vendor API keys, see the [Configuration Guide](./configuration#llm-configuration). - -**Community quick-start**: [elkimek/honcho-self-hosted](https://github.com/elkimek/honcho-self-hosted) provides a one-command installer with pre-configured model tiers, interactive provider setup, and Hermes Agent integration. - +## Personal local stack (CLI) -## Docker Setup (Recommended) +Recommended if you want Honcho running locally without cloning this repo or building an image. Install the CLI, then run the setup wizard: -Docker Compose handles the database, Redis, and Honcho server. The compose file **builds the image from source** (there is no pre-built image on Docker Hub). This requires Docker with BuildKit enabled — see [Troubleshooting](./troubleshooting#docker-build-fails-with-permission-errors) if the build fails. +```bash +uv tool install honcho-cli +honcho start --setup basic # prompts for LLM provider + key, then starts Docker +``` + +`honcho start` pulls `ghcr.io/plastic-labs/honcho:latest`, pins that digest, and starts API + deriver + Postgres + Redis. Stack files live under `~/.honcho/profiles/local/`. It does **not** rewrite `environmentUrl` in `~/.honcho/config.json` (that file is shared with plugins). Talk to the stack with `HONCHO_BASE_URL=http://127.0.0.1:8000`, or run `honcho init --base-url http://127.0.0.1:8000` to persist local as the CLI default. + +See the [CLI reference](/v3/documentation/reference/cli#local-stack) for `--setup`, profiles, `--image`, ports, `honcho status` / `stop`, and pointing the CLI at local. + +## From source (Docker Compose) + +Docker Compose in this repo handles the database, Redis, and Honcho server. The compose file **builds the image from source** so you can develop against local code. A pre-built image is published at `ghcr.io/plastic-labs/honcho:latest` (what `honcho start` uses); it is not on Docker Hub. Building from source requires Docker with BuildKit enabled — see [Troubleshooting](./troubleshooting#docker-build-fails-with-permission-errors) if the build fails. The compose file is production-oriented by default (ports bound to `127.0.0.1`, restart policies, caching enabled). For development, uncomment the source mounts and monitoring services inside the file. @@ -321,6 +332,7 @@ const client = new Honcho({ ### Next Steps - **Configure Honcho**: Visit the [Configuration Guide](./configuration) for model tiers, provider options, and tuning +- **Use the CLI**: install with `uv tool install honcho-cli`, then [`honcho start --setup`](/v3/documentation/reference/cli#local-stack) for a local stack; inspect with `honcho workspace inspect` / `honcho doctor` - **Explore the API**: Check out the [API Reference](../api-reference/introduction) - **Try the SDKs**: See our [guides](../guides) for examples - **Join the community**: [Discord](https://discord.gg/honcho) @@ -334,11 +346,12 @@ Running into issues? See the [Troubleshooting Guide](./troubleshooting) for deta - Deriver not processing messages - Database connection and migration issues - Docker and Redis problems +- CLI local stack (`honcho start`) — missing LLM key, health timeout, still talking to api.honcho.dev **Quick checks:** - Verify the server is running: `curl http://localhost:8000/health` -- Check logs: `docker compose logs api` (Docker) or check terminal output (manual setup) -- Ensure migrations ran: `uv run alembic upgrade head` +- Check logs: `docker compose logs api` (from-source Docker), `docker compose -p honcho-local logs` (`honcho start`), or terminal output (manual setup) +- Ensure migrations ran: `uv run alembic upgrade head` (from-source only; `honcho start` runs them in the image entrypoint) ## Production Considerations diff --git a/docs/v3/contributing/troubleshooting.mdx b/docs/v3/contributing/troubleshooting.mdx index ffb73417..e40917ab 100644 --- a/docs/v3/contributing/troubleshooting.mdx +++ b/docs/v3/contributing/troubleshooting.mdx @@ -316,11 +316,37 @@ docker compose build --no-cache docker compose up -d ``` +## CLI local stack (`honcho start`) + +The CLI local stack lives under `~/.honcho/profiles/` (default profile `local`) and uses the published image `ghcr.io/plastic-labs/honcho:latest`. Logs: `docker compose -p honcho-local logs`. Full flags: [CLI reference](/v3/documentation/reference/cli#local-stack). + +### `MISSING_LLM_KEY` + +**Cause:** No provider key in the environment or the profile `.env`. + +**Fix:** Export `LLM_OPENAI_API_KEY`, `LLM_ANTHROPIC_API_KEY`, or `LLM_GEMINI_API_KEY`, or run `honcho start --setup basic` in a TTY (not with `--json`). + +### Timed out waiting for `/health` + +**Cause:** The API container started but did not become ready within `--timeout` (default 180s). + +**Fix:** Check `docker compose -p honcho-local logs api` and `... logs deriver`. Increase `--timeout`. Confirm Docker is running. A first-time GHCR pull happens *before* this wait (during image pin) — if that step hung, look at Docker pull logs instead. + +### CLI still talks to `api.honcho.dev` + +**Cause:** `honcho start` does not rewrite `environmentUrl` in `~/.honcho/config.json`. + +**Fix:** Prefix commands with `HONCHO_BASE_URL=http://127.0.0.1:8000`, or run `honcho init --base-url http://127.0.0.1:8000` to persist local as the default. `honcho status` prints the one-shot hint. + +### Port already in use + +The CLI remaps 8000/5432/6379 automatically unless you pinned them with `--api-port` / `--db-port` / `--redis-port`. Pass those flags if you need a specific host port. + ## Getting Help If your issue isn't covered here: -- **Check the logs** — most issues are diagnosed from server or deriver logs +- **Check the logs** — most issues are diagnosed from server or deriver logs (`docker compose logs` for from-source compose; `docker compose -p honcho-local logs` for `honcho start`) - **GitHub Issues** — [Report bugs](https://github.com/plastic-labs/honcho/issues) - **Discord** — [Join our community](https://discord.gg/plasticlabs) - **Configuration** — See the [Configuration Guide](./configuration) for all available settings diff --git a/docs/v3/documentation/introduction/overview.mdx b/docs/v3/documentation/introduction/overview.mdx index 29cc2815..bc4ebd9f 100644 --- a/docs/v3/documentation/introduction/overview.mdx +++ b/docs/v3/documentation/introduction/overview.mdx @@ -94,6 +94,9 @@ Welcome to Honcho. We're excited to have you at the frontier of AI with us 🫡. Build your first stateful agent in minutes + + Inspect a deployment, or `honcho start --setup` a local stack + Deep dive into how Honcho's primitives fit together diff --git a/docs/v3/documentation/introduction/quickstart.mdx b/docs/v3/documentation/introduction/quickstart.mdx index 85884a67..d3bbe01b 100644 --- a/docs/v3/documentation/introduction/quickstart.mdx +++ b/docs/v3/documentation/introduction/quickstart.mdx @@ -11,9 +11,11 @@ Let's get started with Honcho. In this quickstart, you will: - Query the reasoning Honcho produces to get synthesized insights about the user -Running the code below requires an API key. Create and account and get your API key at [app.honcho.dev](https://app.honcho.dev) under "API KEYS". +Running the code below requires an API key. Create an account and get your API key at [app.honcho.dev](https://app.honcho.dev) under "API KEYS". Every new tenant gets \$100.00 in free credits on sign up. The code below costs ~\$0.04 to run, so don't worry--still plenty of free credits for iterating. + +To run against a local stack instead, install the CLI (`uv tool install honcho-cli`) and then run `honcho start --setup` (Docker + an LLM provider key). See the [CLI reference](/v3/documentation/reference/cli#local-stack). #### 1. Install the SDK diff --git a/docs/v3/documentation/introduction/vibecoding.mdx b/docs/v3/documentation/introduction/vibecoding.mdx index cd5e8ac6..be2a7362 100644 --- a/docs/v3/documentation/introduction/vibecoding.mdx +++ b/docs/v3/documentation/introduction/vibecoding.mdx @@ -68,16 +68,19 @@ claude mcp add honcho \ ## CLI -Inspect and debug a running Honcho deployment from your terminal. The honcho CLI wraps the Python SDK with agent-friendly defaults — JSON output, structured errors, and commands for every primitive (workspaces, peers, sessions, messages, conclusions). +Inspect and debug a running Honcho deployment from your terminal, or run a personal local stack. The honcho CLI wraps the Python SDK with agent-friendly defaults — JSON output, structured errors, and commands for every primitive (workspaces, peers, sessions, messages, conclusions). **Get started:** ```bash uv tool install honcho-cli -honcho init # configure apiKey + environmentUrl -honcho doctor # verify connectivity +honcho init # Honcho API key / browser login (talk *to* a server) +honcho start --setup basic # local stack: LLM provider key + Docker +honcho doctor # verify connectivity ``` +`honcho start --setup` pulls the published GHCR image — no clone required. It does not rewrite `environmentUrl` in the shared config file; prefix commands with `HONCHO_BASE_URL=http://127.0.0.1:8000` to talk to local. + The CLI also ships an agent skill. Install it with `npx skills add plastic-labs/honcho` and pick `honcho-cli` from the list. See the [full CLI reference](/v3/documentation/reference/cli) for all commands, flags, and environment variables. @@ -147,7 +150,7 @@ Invoke with `/honcho-integration` in your coding agent. #### honcho-cli -**For inspection & debugging.** Teaches your coding agent the right commands and flags for the [honcho CLI](#cli) — peer memory, session context, queue status, dialectic quality. +**For inspection & debugging, and for running a local stack.** Teaches your coding agent the right commands and flags for the [honcho CLI](#cli) — peer memory, session context, queue status, dialectic quality, `honcho start` / `status` / `stop`. Invoke implicitly when you ask your agent to inspect a Honcho deployment. @@ -170,7 +173,7 @@ I want to start building with Honcho - an open source memory library for buildin - Core repo: https://github.com/plastic-labs/honcho - Python SDK: https://github.com/plastic-labs/honcho-python - TypeScript SDK: https://github.com/plastic-labs/honcho-node -- CLI (inspect & debug a deployment): https://github.com/plastic-labs/honcho/tree/main/honcho-cli +- CLI (inspect, debug, or `honcho start` a local stack): https://github.com/plastic-labs/honcho/tree/main/honcho-cli - Discord bot starter: https://github.com/plastic-labs/discord-python-starter - Telegram bot example: https://github.com/plastic-labs/telegram-python-starter diff --git a/docs/v3/documentation/reference/cli.mdx b/docs/v3/documentation/reference/cli.mdx index 5df031d6..71a14305 100644 --- a/docs/v3/documentation/reference/cli.mdx +++ b/docs/v3/documentation/reference/cli.mdx @@ -18,18 +18,24 @@ uvx honcho-cli ``` +This only installs the `honcho` command. It does not start a server. Use `honcho start --setup` (Docker + an LLM provider key) when you want a local stack. + ## Quick Start ```bash -honcho init # confirm/set apiKey + Honcho URL in ~/.honcho/config.json -honcho start # optional: local API + deriver + Postgres + Redis (Docker) -honcho doctor # verify your config + connectivity -honcho # show banner + command list +honcho init # Honcho API key or browser login + server URL (talk *to* Honcho) +honcho start --setup basic # local stack: LLM provider key + Docker (not set by init) +honcho doctor # verify your config + connectivity +honcho # show banner + command list ``` +`honcho init` authenticates the CLI against a Honcho server. It does **not** configure the LLM key a local stack needs — that is `honcho start --setup`. + ## Local stack -`honcho start` runs a personal Honcho server on your machine via Docker (API, deriver, Postgres, Redis). It is not the managed service at `api.honcho.dev`. Deriver and dialectic call your cloud LLM provider (OpenAI, Anthropic, or Gemini) with a key you supply. Stack files live under `~/.honcho/profiles/local/`. The first start writes `config.toml` there from the image; later starts leave that file alone so your edits persist. +`honcho start --setup basic` is the fastest way to run Honcho on your machine. It does **not** require cloning the Honcho repo. The wizard prompts for an LLM provider and API key, writes them into the profile `.env`, pulls `ghcr.io/plastic-labs/honcho:latest`, **pins that digest**, and starts API + deriver + Postgres + Redis via Docker. + +Default profile is `local` (`--profile` / `HONCHO_PROFILE`). First start copies the image `config.toml.example` into the profile directory; later starts leave that file alone so your edits persist — including when you re-pin the image. Delete `config.toml` yourself if you want a fresh copy from a new image. Pass `--image` to pin a different tag or digest. Ports bind to `127.0.0.1`; if 8000/5432/6379 are taken, the CLI remaps them (or pass `--api-port` / `--db-port` / `--redis-port`). Auth is off (`AUTH_USE_AUTH=false`). Pass `--setup basic` or `--setup advanced` for an interactive wizard that writes curated LLM/feature overrides into the profile `.env` (environment variables win over `config.toml`). This is TTY-only. `basic` covers provider and chat model; `advanced` also covers embeddings, deriver/dialectic models, dreams, and deriver flush. Re-running `--setup` while the stack is up recreates the API and deriver containers. @@ -37,16 +43,20 @@ This does **not** change `environmentUrl` in the shared config file. To talk to ```bash HONCHO_BASE_URL=http://127.0.0.1:8000 honcho workspace list +honcho init --base-url http://127.0.0.1:8000 # persist local as the CLI default ``` ```bash -LLM_OPENAI_API_KEY=sk-... honcho start honcho start --setup basic +honcho start --setup advanced +LLM_OPENAI_API_KEY=sk-... honcho start # skip the wizard if the key is already in the env honcho status honcho stop # keep data honcho stop --wipe # also delete volumes ``` +To **develop the server** (live reload, from-source image), see [Local Environment Setup](/v3/contributing/self-hosting). + ## Configuration The CLI resolves config in this order: **flag → env var → config file → default**. @@ -59,12 +69,16 @@ The CLI resolves config in this order: **flag → env var → config file → de | Peer | — | `HONCHO_PEER_ID` | `-p` / `--peer` | No | | Session | — | `HONCHO_SESSION_ID` | `-s` / `--session` | No | | JSON output | — | `HONCHO_JSON` | `--json` | No | +| Local stack | — | `HONCHO_PROFILE` | `--profile` | No | ### Persisted config -The CLI shares `~/.honcho/config.json` with sibling Honcho tools. It owns only +The CLI shares `~/.honcho/config.json` with sibling Honcho tools. It owns `apiKey` and `environmentUrl` at the top level — everything else (`hosts`, `sessions`, etc.) is written by other tools and left untouched on save. +On managed servers that advertise the device grant in OAuth metadata, +`honcho init` can log you in via the browser; tokens auto-refresh +and are stored under `oauth` without deleting a shared `apiKey`. ```json { diff --git a/docs/v3/guides/integrations/hermes.mdx b/docs/v3/guides/integrations/hermes.mdx index 9fe46973..d06f650a 100644 --- a/docs/v3/guides/integrations/hermes.mdx +++ b/docs/v3/guides/integrations/hermes.mdx @@ -67,10 +67,6 @@ Or manually create/edit the config file (checked in order: `$HERMES_HOME/honcho. For the full list of config fields (`recallMode`, `writeFrequency`, `sessionStrategy`, `dialecticReasoningLevel`, etc.), see the [Hermes memory provider docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#honcho). - -**Community quick-start**: [elkimek/honcho-self-hosted](https://github.com/elkimek/honcho-self-hosted) provides a one-command installer with pre-configured model tiers and Hermes Agent integration. - - ## Verifying the integration ### 1. Check status diff --git a/honcho-cli/README.md b/honcho-cli/README.md index f1585a89..06898b5c 100644 --- a/honcho-cli/README.md +++ b/honcho-cli/README.md @@ -22,19 +22,19 @@ uv tool install honcho-cli ## Quick Start ```bash -honcho init # confirm/set apiKey + Honcho URL in ~/.honcho/config.json -honcho start # optional: local API + deriver + Postgres + Redis (Docker) -honcho doctor # verify your config + connectivity -honcho # show banner + command list +honcho init # confirm/set apiKey + Honcho URL in ~/.honcho/config.json +honcho start --setup basic # local stack: LLM provider key + Docker +honcho doctor # verify config + connectivity +honcho # show banner + command list ``` -`honcho init` reads `apiKey` and `environmentUrl` from the top-level of `~/.honcho/config.json` (the same file other Honcho tools — plugins, host integrations — share). If both are present, it confirms them with you; if either is missing (or you decline), it prompts for the missing value(s) and writes them back. Host-specific entries under `hosts` are left untouched. +`honcho init` writes `apiKey` and `environmentUrl` to the top-level of `~/.honcho/config.json` (the same file other Honcho tools — plugins, host integrations — share) so the CLI can call a Honcho server. If both are present, it confirms them with you; if either is missing (or you decline), it prompts and writes them back. Host-specific entries under `hosts` are left untouched. It does **not** set the LLM provider key the local deriver needs — that is `honcho start --setup` (or `LLM_*_API_KEY` in the environment). Per-command scoping (workspace / peer / session) is handled via `-w` / `-p` / `-s` flags or `HONCHO_*` env vars — not persisted as CLI defaults. ### Local stack -`honcho start` runs a personal Honcho server on your machine (API, deriver, Postgres, Redis) via Docker. Inference is cloud-side: set `LLM_OPENAI_API_KEY`, `LLM_ANTHROPIC_API_KEY`, or `LLM_GEMINI_API_KEY` (env overrides `config.toml`). Stack files live under `~/.honcho/profiles/local/` and are not committed to a project. +`honcho start --setup basic` runs a personal Honcho server on your machine (API, deriver, Postgres, Redis) via Docker. The wizard writes the LLM provider key into the profile `.env` — `honcho init` cannot do this; its `apiKey` is for calling a Honcho server, not for deriver/dialectic inference. You can also pass `LLM_OPENAI_API_KEY`, `LLM_ANTHROPIC_API_KEY`, or `LLM_GEMINI_API_KEY` in the environment and skip `--setup`. Stack files live under `~/.honcho/profiles/local/` and are not committed to a project. On first start, the CLI pulls `ghcr.io/plastic-labs/honcho:latest` and **pins that digest** in `profile.json`, then copies the image's `config.toml.example` to `config.toml` in the same directory. `honcho start` never overwrites `config.toml` after that — including when you re-pin the image. Delete the file yourself if you want a fresh copy from a new image. @@ -49,7 +49,6 @@ HONCHO_BASE_URL=http://127.0.0.1:8000 honcho workspace list To make local the default, run `honcho init --base-url http://127.0.0.1:8000`. ```bash -LLM_OPENAI_API_KEY=sk-... honcho start honcho start --setup basic honcho start --setup advanced honcho status @@ -63,7 +62,7 @@ honcho stop --wipe # also delete volumes | Command | Description | |---------|-------------| -| `honcho init` | Confirm/set `apiKey` + `environmentUrl` in `~/.honcho/config.json` | +| `honcho init` | Confirm/set `apiKey` + `environmentUrl` in `~/.honcho/config.json`. | | `honcho start` | Start a local Honcho stack (API, deriver, Postgres, Redis). Requires Docker and a cloud LLM key. `--setup basic` / `--setup advanced` runs an interactive config wizard (TTY only). Does not change `environmentUrl`. | | `honcho stop` | Stop the local stack. `--wipe` also deletes volumes. | | `honcho status` | Show every local stack (or `--profile` for one). |