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

# Install and run the Server

> Start the minimum Server first. Do not add a model on the first run.

Start the minimum Server first. It has no generation or embedding model, but it can already store a Memory (Selected project knowledge you will reuse later.) you write, run full-text search, and expose the same data through HTTP, the Python Client, and MCP.

Do not add a model on the first run. If something gets stuck, you only need to check install, the data directory, Scope (Chooses which isolated data set this request reads and writes. A mismatch usually looks like a miss, not an error.), and the connection. Finish this loop, then add inference. Otherwise a provider failure can look like a broken database or a broken integration.

![The first loop: write a Memory, find it, then get a cited PreparedContext.](https://mintcdn.com/powercontext/1t_ajifOEOG5YQjP/assets/basic-first-loop-en.svg?fit=max\&auto=format\&n=1t_ajifOEOG5YQjP\&q=85\&s=c80f846d7f1f5069e9a3c6aa6de6fb35)

> [!NOTE]
>
> Install flags, API contracts, and deploy settings follow the latest published [official docs](https://oceanbase.github.io/powercontext/). This page only helps you start the local Server and see what it can do now.

> [!WARNING]
>
> The documented install path is macOS or Linux, Python 3.11 or later. This tutorial does not provide an unverified Windows workaround.

## Prerequisites

The documented environment is:

* macOS or Linux;
* Python 3.11 or later;
* Git;
* [`uv`](https://docs.astral.sh/uv/).

PowerContext supports Python `<4.0`.

## Install the CLI and Server

Install the current `master`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
uv tool install --force \
  "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
```

`uv tool` uses an isolated environment and leaves no repository checkout in the current directory. `--force` also matters for updates: when the same Git requirement is already installed, it fetches and replaces the selected ref instead of returning already installed.

For local learning, follow the ref on the page you are reading. This page and the common / coding-agent setup pages use `@master` so the tutorial can track current docs.

For a reproducible deploy, do not follow `master`. Pin one reviewed commit, then use that same ref for the CLI, Server, and host plugin. Write the full commit hash when you pin. Do not mix a short hash and a long hash in the same command set.

> [!NOTE]
>
> A `powercontext[client]` extra installed inside the `uv tool` environment is not importable from an unrelated Python project. Install the client extra in the project that runs Client code.

## Start the local Server

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
powercontext server run
```

The default configuration is:

| Item | Default behavior |
| - | - |
| Address | `http://127.0.0.1:8000` |
| Dashboard | `/` |
| Streamable HTTP MCP | `/mcp`; see [Connect with MCP](https://powercontext.mintlify.site/en/basic-usage/mcp.md) |
| Database | Persistent SQLite in the user data directory |
| Bearer auth | Disabled for the default loopback setup |
| Generation / embedding | Not configured |
| Search | `auto`, `fts` |

On macOS, the database is usually stored at:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
~/Library/Application Support/powercontext/powercontext.db
```

On Linux, it is usually:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
~/.local/share/powercontext/powercontext.db
```

When `POWERCONTEXT_HOME` is set, the default database moves under that directory. A new data directory or database URL opens another database. That looks like a lost Scope.

`Ctrl-C` shuts the Server down cleanly. Starting it again reopens the same database.

## Inspect runtime status

Open another terminal:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
powercontext doctor
powercontext ready
powercontext capabilities
```

These three commands answer different questions.

### `doctor`

Checks the installed package, Server liveness, and Server readiness. It exits with zero only when every check is `ok`.

When liveness fails, readiness is marked skipped. `degraded` also produces a non-zero doctor result because at least one configured inference check failed; it does not necessarily mean the database is unavailable.

### `ready`

Distinguishes:

* `ready`: every configured check passes;
* `degraded`: an optional inference check failed, with HTTP 200;
* `not_ready`: the Runtime or database is unavailable and the readiness endpoint returns HTTP 503. The current CLI prints that 503 as a Server error instead of rendering the full `not_ready` response; use `doctor` or inspect `/health/ready` directly for dependency details.

### `capabilities`

A minimum Server should report something like:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Source types: content
Artifact families: memory, experience, skill, handoff
Memory extraction: disabled
Experience generation: disabled
Managed Skill generation: disabled
External Skill Registry: disabled
Handoff generation: disabled
Search modes: auto, fts
Context versions: powercontext.prepared-context.v1
```

The presence of an Artifact family does not mean model-backed generation for that family is enabled. Check the corresponding capability boolean.

Open the Dashboard at:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
http://127.0.0.1:8000/
```

With no Dashboard Scope configured, the page is empty. A Dashboard initialization failure only logs a warning. HTTP and MCP still work. To check counts for the same Scope, follow [Verify Scope statistics in the Dashboard](https://powercontext.mintlify.site/en/basic-usage/dashboard.md) and use the same `scope_id`.

## Check what works without a model first

The minimum Server still supports:

* Source capture;
* explicit Memory remember, search, revise, and retire;
* FTS;
* typed Experience and Skill proposals with Candidate Review;
* Prepared Handoff finalize, commit, and continue;
* `PreparedContext` construction when the Scope has recallable content.

It does not support:

* model extraction from Source to Memory;
* model generation for Experience, Skill, or Handoff;
* vector or hybrid search;
* model-backed reranking.

So the first loop starts with a Memory you already accept: write it, find it with `search_memory`, and use `prepare_context` to get a cited `PreparedContext`. Confirm the data is still there, the Scope matches, and the Citation is present before you add a provider. Extracting Memory from a Source, and generating a Handoff with a model, wait for later pages.

## Install the Client in a Python project

In the project that runs the examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
uv add \
  "powercontext[client] @ git+https://github.com/oceanbase/powercontext.git@master"
```

Confirm that the project uses Python 3.11 or later:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
uv run python --version
```

The next page imports the public API through:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from powercontext.client import PowerContextClient
from powercontext.http import RememberMemoryRequest
```

Do not import internal generated modules from `powercontext.http._generated`.

## `.env` is not loaded automatically

The PowerContext CLI does not search the current directory for `.env`. Pass the file explicitly:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
powercontext server run --env-file .env
```

A full-capability configuration starts with:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
powercontext config init --output .env
powercontext config show --env-file .env
powercontext config validate --env-file .env
powercontext server run --env-file .env
```

Generation and scheduling are separate settings. A generation model turns extraction on. It does not start the periodic scheduler. You can still call `flush_memory` yourself.

Embedding needs the model, profile ID, and dimension as one set. If any piece is missing, validation should fail. Do not start a vague half-vector mode.

## Authentication and remote access

The default Server listens on loopback, so disabled authentication is reasonable for local development.

A non-loopback bind requires authentication or an explicit unsafe opt-in by default. The Python Client also rejects plaintext HTTP to a non-loopback host. Remote and production deployments should use TLS and a bearer token. Never put the token in the URL.

When authentication is enabled, the Client reads a bare token:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export POWERCONTEXT_CLIENT_API_TOKEN="replace-with-token"
```

It constructs:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
Authorization: Bearer replace-with-token
```

## Common startup stuck points

### `doctor` cannot reach the Server

Confirm that `powercontext server run` is still running and that port 8000 is free. For a custom address, put the option that belongs to `doctor` after the subcommand:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
powercontext doctor \
  --server-url http://127.0.0.1:9000
```

The root `--server-url` applies to Client content commands and does not replace the separate doctor address.

### You created `.env`, but capabilities did not change

Did the Server command include `--env-file .env`? The CLI does not load it on its own.

### `capabilities` lists only `auto, fts`

The Server is working in full-text-only mode. That is expected until vector or hybrid search is fully configured.

### `ready` is degraded

Inspect the failed dependency check. Database operations that do not need that inference capability may still work. Operations that need the failed provider will not.

### Data disappeared after restart

Check `POWERCONTEXT_HOME`, the database kind, and the database URL, then check `scope_id`. Each one changes which data you see. If it still does not match, start with [Troubleshooting](https://powercontext.mintlify.site/en/start/troubleshooting.md).

## How you know it worked

Before you continue, confirm:

* `powercontext doctor` passes on the minimum setup.
* `powercontext capabilities` lists `auto, fts`.
* The Dashboard opens, or you turned it off on purpose.
* The example Python project can import `PowerContextClient`.
* The stable Scope for this tutorial is `project:powercontext-101`.
* The next step is: write a Memory, find it with `search_memory`, then get a cited `PreparedContext` from `prepare_context`.

## Next step

> [card] [Common API tour](https://powercontext.mintlify.site/en/basic-usage/api-tour.md)
>
> Use the Python Client to write one Memory, find it, and get a cited PreparedContext.

> [card] [If you are stuck](https://powercontext.mintlify.site/en/start/troubleshooting.md)
>
> Can't find what you wrote, see an empty page, or a check passed and it still fails? Start there.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.