> ## Documentation Index
> Fetch the complete documentation index at: https://honcho.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Start building with Honcho in under 5 minutes.

For production-level use, Honcho offers two powerful ways to leverage ambient personalization: our managed platform and our open source solution. Read further if you want to explore the quickstart demo.

<CardGroup cols={2}>
  <Card title="Honcho Platform" icon="cloud" href="https://app.honcho.dev">
    Fully managed, hassle-free solution with one-click deployment
  </Card>

  <Card title="Honcho Open Source" icon="github" href="https://github.com/plastic-labs/honcho">
    Self-hosted, fully customizable, and open source
  </Card>
</CardGroup>

# Getting Started

Have your project use Honcho's ambient personalization capabilities in just a few steps. No signup required!

<Info>
  By default, the SDK uses the demo server hosted at demo.honcho.dev. The demo server is meant for quick experimentation and the data is cleared on a regular basis. Do not use for production applications.

  For production use:

  1. Get your API key at [app.honcho.dev/api-keys](https://app.honcho.dev/api-keys)
  2. Set `environment="production"` and provide your `api_key`
</Info>

## 1. Install the SDK

<CodeGroup>
  ```bash Python (uv) theme={null}
  uv add honcho-ai
  ```

  ```bash Python (pip) theme={null}
  pip install honcho-ai
  ```

  ```bash TypeScript (npm) theme={null}
  npm install @honcho-ai/sdk
  ```

  ```bash TypeScript (yarn) theme={null}
  yarn add @honcho-ai/sdk
  ```

  ```bash TypeScript (pnpm) theme={null}
  pnpm add @honcho-ai/sdk
  ```
</CodeGroup>

## 2. Initialize the Client

The Honcho client is the main entry point for interacting with Honcho's API. By default, it uses the demo environment and a default workspace.

### Demo Environment (Default)

<CodeGroup>
  ```python Python theme={null}
  from honcho import Honcho

  # Initialize client (uses demo environment and default workspace)
  honcho = Honcho()

  ```

  ```typescript TypeScript theme={null}
  import { Honcho } from '@honcho-ai/sdk';

  // Initialize client (uses demo environment and default workspace)
  const honcho = new Honcho({});

  ```
</CodeGroup>

### Production Environment

<CodeGroup>
  ```python Python theme={null}
  import os
  from honcho import Honcho

  # Production environment with API key
  honcho = Honcho(
      api_key=os.environ["HONCHO_API_KEY"],
      environment="production",
      # Create a workspace, otherwise set to "default"
      # workspaceId="your-workspace-id"
  )
  ```

  ```typescript TypeScript theme={null}
  import { Honcho } from '@honcho-ai/sdk';

  // Production environment with API key
  const honcho = new Honcho({
      apiKey: process.env.HONCHO_API_KEY!,
      environment: "production",
      // Create a workspace, otherwise set to "default"
      // workspace: "your-workspace-id"
  });
  ```
</CodeGroup>

## 3. Create Peers

Peers represent individual users, AI agents, or any conversational entity in your system:

<CodeGroup>
  ```python Python theme={null}
  alice = honcho.peer("alice")
  bob = honcho.peer("bob")
  ```

  ```typescript TypeScript theme={null}
  const alice = await honcho.peer("alice")
  const bob = await honcho.peer("bob")
  ```
</CodeGroup>

## 4. Create a Session

Sessions are independent conversations that can include multiple peers:

<CodeGroup>
  ```python Python theme={null}
  session = honcho.session("session_1")
  session.add_peers([alice, bob])
  ```

  ```typescript TypeScript theme={null}
  const session = await honcho.session("session_1")
  await session.addPeers([alice, bob])
  ```
</CodeGroup>

## 5. Add Messages

Add some conversation messages. Honcho automatically learns from these interactions:

<CodeGroup>
  ```python Python theme={null}
  session.add_messages([
      alice.message("Hi Bob, how are you?"),
      bob.message("I'm good, thank you!"),
      alice.message("What are you doing today after work?"),
      bob.message("I'm going to the gym! I've been trying to get back in shape."),
      alice.message("That's great! I should probably start exercising too."),
      bob.message("You should! I find that evening workouts help me relax."),
  ])
  ```

  ```typescript TypeScript theme={null}
  await session.addMessages([
      alice.message("Hi Bob, how are you?"),
      bob.message("I'm good, thank you!"),
      alice.message("What are you doing today after work?"),
      bob.message("I'm going to the gym! I've been trying to get back in shape."),
      alice.message("That's great! I should probably start exercising too."),
      bob.message("You should! I find that evening workouts help me relax."),
  ])
  ```
</CodeGroup>

## 6. Query for Insights

Now ask Honcho what it's learned - this is where the magic happens:

<CodeGroup>
  ```python Python theme={null}
  # Ask what Bob is like
  response = bob.chat("Tell me about Bob's interests and habits")
  print(response)

  # Returns rich context like:
  # "Bob is health-conscious and has been working on getting back in shape.
  # He regularly goes to the gym, particularly in the evenings, and finds
  # exercise helps him relax. He's encouraging about fitness and willing
  # to share advice about workout routines."
  ```

  ```typescript TypeScript theme={null}
  bob.chat("Tell me about Bob's interests and habits").then((response) => {
    console.log(response);
    // Returns rich context like:
    // "Bob is health-conscious and has been working on getting back in shape.
    // He regularly goes to the gym, particularly in the evenings, and finds
    // exercise helps him relax. He's encouraging about fitness and willing
    // to share advice about workout routines."
  })
  ```
</CodeGroup>

## 7. Putting it all together

<CodeGroup>
  ```python Python theme={null}
  import os
  from honcho import Honcho

  # Create your client
  honcho = Honcho(
      api_key=os.environ["HONCHO_API_KEY"],
      environment="production",
      # Create a workspace, otherwise set to "default"
      # workspaceId="your-workspace-id"
  )

  # Get your Peers
  alice = honcho.peer("alice")
  bob = honcho.peer("bob")

  # Make a Session and add your Peers
  session = honcho.session("session_1")
  session.add_peers([alice, bob])

  # Add messages sent by your Peers
  session.add_messages([
      alice.message("Hi Bob, how are you?"),
      bob.message("I'm good, thank you!"),
      alice.message("What are you doing today after work?"),
      bob.message("I'm going to the gym! I've been trying to get back in shape."),
      alice.message("That's great! I should probably start exercising too."),
      bob.message("You should! I find that evening workouts help me relax."),
  ])

  # Get insights about your Peers
  response = bob.chat("Tell me about Bob's interests and habits")
  print(response)

  # Returns rich context like:
  # "Bob is health-conscious and has been working on getting back in shape.
  # He regularly goes to the gym, particularly in the evenings, and finds
  # exercise helps him relax. He's encouraging about fitness and willing
  # to share advice about workout routines."
  ```

  ```typescript TypeScript theme={null}
  import { Honcho } from '@honcho-ai/sdk';

  // Create your client
  const honcho = new Honcho({
      apiKey: process.env.HONCHO_API_KEY!,
      environment: "production",
      // Create a workspace, otherwise set to "default"
      // workspace: "your-workspace-id"
  });

  // Get your Peers
  const alice = await honcho.peer("alice")
  const bob = await honcho.peer("bob")

  // Make a Session and add your peers
  const session = await honcho.session("session_1")
  await session.addPeers([alice, bob])

  // Add messages sent by your Peers
  await session.addMessages([
      alice.message("Hi Bob, how are you?"),
      bob.message("I'm good, thank you!"),
      alice.message("What are you doing today after work?"),
      bob.message("I'm going to the gym! I've been trying to get back in shape."),
      alice.message("That's great! I should probably start exercising too."),
      bob.message("You should! I find that evening workouts help me relax."),
  ])

  // Get insights about your peers
  bob.chat("Tell me about Bob's interests and habits").then((response) => {
    console.log(response);
    // Returns rich context like:
    // "Bob is health-conscious and has been working on getting back in shape.
    // He regularly goes to the gym, particularly in the evenings, and finds
    // exercise helps him relax. He's encouraging about fitness and willing
    // to share advice about workout routines."
  })
  ```
</CodeGroup>

## What Just Happened?

You just got through building a simple conversation between two people, Alice
and Bob. We:

1. Set up our connection to Honcho.
2. Setup who the participants of our conversation are, these are called `Peers`.
3. Made a `Session` and added our `Peers` to it.
4. Sent messages from our `Peers`
5. Chat with Honcho to get insights about one of the `Peers` in the conversation

As soon as you save a message in Honcho, it will start to reason about it to
pull out insights and develop a profile of the user. This is the default
behavior and can be toggled off via [the configuration](/v2/documentation/core-concepts/configuration).

## Next Steps

<CardGroup cols={3}>
  <Card title="Architecture" icon="rocket" href="/v2/documentation/core-concepts/architecture">
    Learn about the data primitives in Honcho and how they work together
  </Card>

  <Card title="Start Building" icon="brain" href="https://app.honcho.dev">
    Sign up for Managed Honcho and get started building agents now.
  </Card>

  <Card title="Guides" icon="book" href="/v2/guides/overview">
    Check out spellbooks to see different examples apps built with Honcho
  </Card>
</CardGroup>