Merge remote-tracking branch 'origin/main' into abigail/cli-0.1.4
Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # docs/v3/documentation/reference/cli.mdx
This commit is contained in:
ajspig
commit
447305e995
|
|
@ -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
|
||||
|
|
|
|||
37
README.md
37
README.md
|
|
@ -11,11 +11,12 @@
|
|||
|
||||
[](https://pypi.org/project/honcho-ai/)
|
||||
[](https://npmjs.org/package/@honcho-ai/sdk)
|
||||
[](https://pypi.org/project/honcho-cli/)
|
||||
[](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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
</Info>
|
||||
|
||||
<Info>
|
||||
**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.
|
||||
</Info>
|
||||
## 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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -94,6 +94,9 @@ Welcome to Honcho. We're excited to have you at the frontier of AI with us 🫡.
|
|||
<Card title="Quickstart" icon="rocket" href="/v3/documentation/introduction/quickstart">
|
||||
Build your first stateful agent in minutes
|
||||
</Card>
|
||||
<Card title="CLI" icon="terminal" href="/v3/documentation/reference/cli">
|
||||
Inspect a deployment, or `honcho start --setup` a local stack
|
||||
</Card>
|
||||
<Card title="Architecture" icon="sitemap" href="/v3/documentation/core-concepts/architecture">
|
||||
Deep dive into how Honcho's primitives fit together
|
||||
</Card>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
<Note>
|
||||
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).
|
||||
</Note>
|
||||
|
||||
#### 1. Install the SDK
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -18,18 +18,24 @@ uvx honcho-cli
|
|||
```
|
||||
</CodeGroup>
|
||||
|
||||
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**.
|
||||
|
|
@ -60,12 +70,16 @@ The CLI resolves config in this order: **flag → env var → config file → de
|
|||
| Session | — | `HONCHO_SESSION_ID` | `-s` / `--session` | No |
|
||||
| JSON output | — | `HONCHO_JSON` | `--json` | No |
|
||||
| Update nag | — | `HONCHO_NO_UPDATE_CHECK` | — | 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
|
||||
{
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
||||
<Info>
|
||||
**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.
|
||||
</Info>
|
||||
|
||||
## Verifying the integration
|
||||
|
||||
### 1. Check status
|
||||
|
|
|
|||
|
|
@ -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). |
|
||||
|
|
|
|||
Loading…
Reference in New Issue