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 <cursoragent@cursor.com>
This commit is contained in:
ajspig
parent
cccfa988f8
commit
311b21d153
|
|
@ -200,8 +200,7 @@ 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** Honcho locally without developing the server, `uv tool install honcho-cli` then `honcho start` is enough — see [CLI in the README](./README.md#cli). For development of this repo, [Self-hosting in the README](./README.md#self-hosting) covers the Docker Compose path and a manual Postgres setup. Then:
|
||||
|
||||
```bash
|
||||
uv sync # create the venv and install dependencies
|
||||
|
|
|
|||
77
README.md
77
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,8 @@ 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, or inspect one | `honcho start` / `honcho-cli` | [CLI](#cli) |
|
||||
| Self-host from source | Docker Compose or local development | [Self-hosting](#self-hosting) |
|
||||
|
||||
## Why Honcho
|
||||
|
||||
|
|
@ -56,7 +59,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 +73,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 run a local stack with [`honcho start`](#cli) and point the SDK at `http://localhost:8000`.
|
||||
|
||||
### Python
|
||||
|
||||
|
|
@ -226,12 +229,66 @@ 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/) is a terminal for Honcho: inspect workspaces, peers, sessions, and memory, or run a personal local stack. It wraps the Python SDK with agent-friendly defaults — JSON when piped, structured errors, and exit codes for scripts.
|
||||
|
||||
```bash
|
||||
uv tool install honcho-cli
|
||||
|
||||
honcho init # API key or browser login, plus server URL → ~/.honcho/config.json
|
||||
honcho doctor # verify config + connectivity
|
||||
honcho # banner + command list
|
||||
```
|
||||
|
||||
`honcho init` shares `~/.honcho/config.json` with plugins and other Honcho tools. It owns `apiKey` and `environmentUrl` at the top level; everything else (`hosts`, `sessions`, …) is left untouched. On managed servers that advertise the device grant, init can log you in via the browser instead of pasting a key. Workspace / peer / session scope is per-command (`-w` / `-p` / `-s` or `HONCHO_*` env vars) — never persisted as CLI defaults.
|
||||
|
||||
### Local stack (no clone)
|
||||
|
||||
`honcho start` is the fastest way to run Honcho on your machine. It pulls the published image (`ghcr.io/plastic-labs/honcho:latest`), **pins that digest**, and brings up API + deriver + Postgres + Redis in Docker. You do not need to clone this repo. Inference stays cloud-side: pass `LLM_OPENAI_API_KEY`, `LLM_ANTHROPIC_API_KEY`, or `LLM_GEMINI_API_KEY` (or run `--setup`).
|
||||
|
||||
```bash
|
||||
LLM_OPENAI_API_KEY=sk-... honcho start
|
||||
honcho start --setup basic # interactive provider + chat model
|
||||
honcho start --setup advanced # embeddings, deriver/dialectic models, dreams, flush
|
||||
honcho status
|
||||
honcho stop # keep data
|
||||
honcho stop --wipe # also delete volumes
|
||||
```
|
||||
|
||||
Stack files live under `~/.honcho/profiles/local/` (override with `--profile` / `HONCHO_PROFILE`). First start copies the image `config.toml`; later starts never overwrite it, including when you re-pin the image. `--setup` writes curated LLM overrides into the profile `.env` (env wins over `config.toml`). Auth is off. 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`).
|
||||
|
||||
`honcho start` does **not** change `environmentUrl` in the shared config — plugins keep pointing at `api.honcho.dev`. Talk to the local stack for one command, or make it the default:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
To develop the server itself (live reload, from-source image), see [Self-hosting](#self-hosting). Full flags, profiles, and `--image`: [CLI reference](https://honcho.dev/docs/v3/documentation/reference/cli).
|
||||
|
||||
### Inspect and debug
|
||||
|
||||
| Command | What it shows |
|
||||
| ------- | ------------- |
|
||||
| `honcho workspace inspect` | Peers, sessions, config |
|
||||
| `honcho workspace queue-status` | Whether the deriver is processing |
|
||||
| `honcho peer inspect <id>` | Card, session count, recent conclusions |
|
||||
| `honcho peer chat "<query>"` | Dialectic about a peer (`-p` / `-w`) |
|
||||
| `honcho session view <id> --last 20` | Read-only transcript table |
|
||||
| `honcho session context <id>` | Exactly what an agent would see |
|
||||
| `honcho conclusion list` | Observations (filter with `--observer` / `--observed`) |
|
||||
|
||||
Piped or `--json` emits JSON (arrays for collections, objects for single resources). `honcho doctor --json` is a machine-parseable health checklist.
|
||||
|
||||
The `honcho-cli` agent skill teaches coding agents these commands — install with `npx skills add plastic-labs/honcho` and pick `honcho-cli`. Source and extra examples: [`honcho-cli/README.md`](./honcho-cli/README.md).
|
||||
|
||||
## Core Concepts
|
||||
|
||||
Honcho organises everything around **peers** — humans and AI agents alike are first-class entities. The peer model enables:
|
||||
|
|
@ -275,9 +332,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, prefer [`honcho start`](#cli) — no clone, published GHCR image, Docker. 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,14 +690,16 @@ 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.
|
||||
SDKs are versioned independently of the server. Current SDK versions track each other; the server badge above reflects the deployed server version. The CLI is versioned on its own (`honcho-cli` 0.1.3+ includes `honcho start`).
|
||||
|
||||
See the [SDK Reference](https://honcho.dev/docs/v3/documentation/reference/sdk) for full API surface, the [API Reference](https://honcho.dev/docs/v3/api-reference/introduction) for the raw HTTP API, and per-SDK example folders for runnable demos.
|
||||
|
||||
## 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 — `uv tool install honcho-cli && honcho start`, or see [Self-hosting](./README.md#self-hosting).
|
||||
|
||||
## What to Expect
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ This guide helps you match the right SDK version to your Honcho API version. New
|
|||
|
||||
## Current Versions
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<CardGroup cols={3}>
|
||||
<Card title="TypeScript SDK" icon="js">
|
||||
**Latest:** v2.4.0
|
||||
|
||||
|
|
@ -23,8 +23,16 @@ This guide helps you match the right SDK version to your Honcho API version. New
|
|||
pip install honcho-ai
|
||||
```
|
||||
</Card>
|
||||
<Card title="CLI" icon="terminal">
|
||||
**Latest:** v0.1.3
|
||||
|
||||
```bash
|
||||
uv tool install honcho-cli
|
||||
```
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
CLI 0.1.3+ can start a local stack (`honcho start`) from `ghcr.io/plastic-labs/honcho:latest`. It talks to any v3 API — managed, self-hosted, or that local stack.
|
||||
|
||||
## Version Compatibility Table
|
||||
|
||||
|
|
|
|||
|
|
@ -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** Honcho locally without developing the server, `uv tool install honcho-cli`
|
||||
then `honcho start` is enough — see the [CLI reference](/v3/documentation/reference/cli).
|
||||
For development of this repo, [Self-hosting](/v3/contributing/self-hosting) covers
|
||||
the Docker Compose path and a manual Postgres setup. Then:
|
||||
|
||||
```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?** Skip the clone — [`honcho start`](/v3/documentation/reference/cli#local-stack) 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,23 @@ 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.
|
||||
|
||||
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
|
||||
LLM_OPENAI_API_KEY=sk-... honcho start
|
||||
# or: honcho start --setup basic
|
||||
```
|
||||
|
||||
`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 +333,7 @@ const client = new Honcho({
|
|||
### Next Steps
|
||||
|
||||
- **Configure Honcho**: Visit the [Configuration Guide](./configuration) for model tiers, provider options, and tuning
|
||||
- **Use the CLI**: [`honcho start`](/v3/documentation/reference/cli#local-stack) for a no-clone 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 +347,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 run a local stack with `honcho start`
|
||||
</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, `uv tool install honcho-cli && honcho start`, then pass `base_url="http://localhost:8000"` (Python) / `baseUrl: "http://localhost:8000"` (TypeScript). 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 init # API key or browser login, plus server URL
|
||||
honcho doctor # verify connectivity
|
||||
honcho start # optional: local API + deriver + Postgres + Redis (Docker)
|
||||
```
|
||||
|
||||
`honcho start` 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. Pass `--setup basic` for an interactive LLM wizard.
|
||||
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -29,7 +29,9 @@ honcho # show banner + command list
|
|||
|
||||
## 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` is the fastest way to run Honcho on your machine. It does **not** require cloning the Honcho repo. The CLI pulls the published image (`ghcr.io/plastic-labs/honcho:latest`), **pins that digest** in `~/.honcho/profiles/<name>/profile.json`, and starts API + deriver + Postgres + Redis via Docker. 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.
|
||||
|
||||
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 +39,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
|
||||
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 +65,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 (RFC 8628); 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
|
||||
|
|
|
|||
|
|
@ -28,13 +28,13 @@ honcho doctor # verify your 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` 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. On managed servers that advertise the device grant, you can log in via the browser instead of pasting a key. Host-specific entries under `hosts` are left untouched.
|
||||
|
||||
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` runs a personal Honcho server on your machine (API, deriver, Postgres, Redis) via Docker. You do **not** need to clone this repo. 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.
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -63,7 +63,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`. Browser login on managed servers. |
|
||||
| `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