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

# Your first Entity

> From a fresh checkout to a persistent agent, with hosted or local inference.

Start in a terminal. You can add messaging and a spatial body once your Entity can respond.

## Before you begin

You need **Python 3.11+**, [Git](https://git-scm.com/downloads), and [uv](https://docs.astral.sh/uv/getting-started/installation/). Choose one inference route:

| Route            | You need                                                                   | Where the Entity runs |
| ---------------- | -------------------------------------------------------------------------- | --------------------- |
| **Hosted API**   | A supported provider account and API key                                   | Your computer         |
| **Local Ollama** | [Ollama](https://ollama.com/download) and hardware that can run your model | Your computer         |

Hosted inference does not require a local GPU. Node.js and a headset are optional until you add [spatial presence](/spatial/quickstart).

<Steps>
  <Step title="Get the runtime">
    ```bash theme={null}
    git clone https://github.com/ngramspatial/ngram.git
    cd ngram
    uv sync --extra dev
    uv run ngram --help
    ```

    The help output confirms the command is installed. While the application repository is private, your GitHub account needs access to clone it.
  </Step>

  <Step title="Create and configure your Entity">
    <Tabs>
      <Tab title="Hosted API">
        ```bash theme={null}
        uv run ngram setup --profile hosted
        ```

        Name your Entity, choose your provider and chat model, and supply the API key at the prompt. The wizard configures the local `.env` and Entity YAML.

        Memory also needs embeddings. Use the wizard's provider defaults where available; if your chat provider does not serve embeddings, configure the separate embedding route it offers.
      </Tab>

      <Tab title="Local Ollama">
        ```bash theme={null}
        uv run ngram setup --profile local
        ```

        The repository defaults are `gemma4:26b` for chat and `nomic-embed-text` for embeddings. Choose a model your hardware can run. Pull the selected models if they are not installed:

        ```bash theme={null}
        ollama pull gemma4:26b
        ollama pull nomic-embed-text
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Start a conversation">
    Run the exact command the wizard prints. If you named your Entity `rook`:

    <CodeGroup>
      ```bash Hosted theme={null}
      uv run ngram talk rook
      ```

      ```bash Local theme={null}
      uv run ngram talk rook --ollama
      ```
    </CodeGroup>

    Ask a concrete question. A successful first run reaches the terminal conversation and returns a reply without provider or embedding errors.
  </Step>
</Steps>

## What you just created

The Entity's YAML defines its identity and behavior. Its runtime stores memory and state separately from the source code. The default local state lives under `~/.ngram/entities/`; an explicit execution workspace or portable container can change those paths.

Inspect the configured Entity:

```bash theme={null}
uv run ngram status rook
```

The command argument selects the YAML file stem. For `configs/entities/rook.yaml`, use `rook`, even if the display name inside the file differs.

## Keep it running

`talk` is a terminal conversation. `run` starts the daemon and configured surfaces:

```bash theme={null}
uv run ngram run rook
```

For local inference, add `--ollama`. Background work can call your inference provider while you are not chatting. Read [usage and stop controls](/guides/usage-and-controls) before leaving a hosted Entity running.

Stop a foreground run with **Ctrl+C**. Exit the terminal conversation when you finish. State persists; stopping the process does not wipe the Entity.

<CardGroup cols={2}>
  <Card title="Give it a body" icon="cube" href="/spatial/quickstart">Connect the same Entity to a browser or headset.</Card>
  <Card title="Make it yours" icon="fingerprint" href="/guides/creating-entities">Edit identity, voice, tools, and platforms.</Card>
</CardGroup>

If the first reply fails, start with [troubleshooting](/troubleshooting). Do not change your memory database to work around an inference error.