Install and run

For an Agent connecting from another machine, see Connect to a remote Server for guided URL confirmation, unattended setup, and endpoint-bound HTTP consent.

Start with the Quick Start for your first session. This page covers version selection, platforms, installation roles, startup, diagnostics, and updates.

Platform support

Windows CLI, Server, and personal-service support is experimental. Each Agent Host still has its own platform requirements. Examples using Bash syntax require a Bash environment and cannot be pasted directly into PowerShell. Embedded seekDB is unavailable on Windows.

Choose a version

These instructions use PowerContext 1.4.0. Keep the package and Agent integration on the same version: package 1.4.0 and Git tag powercontext-v1.4.0.

uv tool install --force "powercontext[cli,server]==1.4.0"
powercontext setup codex --ref powercontext-v1.4.0

Check the capability matrix for host support and maintenance status. Capabilities marked experimental remain experimental in this release.

Install the application

You need Python 3.11 or newer, Git, and uv on macOS, Linux, or Windows. Then install PowerContext from PyPI:

uv tool install --force "powercontext[cli,server]==1.4.0"

For a source installation of the same version:

uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@powercontext-v1.4.0"

The Git command does not leave a repository checkout for you to manage. Git uses its normal credential configuration, including credential helpers and SSH settings. For an SSH-based install, replace the HTTPS URL with the Git URL approved for your environment. --force also refreshes an existing tool from the current commit behind the selected Git ref; without it, uv may report the same requirement as already installed without fetching a newer master.

To install another branch or tag, replace the ref after the final @. The master branch can include unreleased changes. Follow the guide for each integration for Agent installation, connection options, and verification, using the same ref as the Server.

Run the local Server

powercontext server run

Without environment variables or an environment file, the Server:

• binds to 127.0.0.1:8000;
• enables Streamable HTTP MCP at /mcp;
• creates a default Scope;
• creates a persistent SQLite database in the operating system's user data directory;
• supports explicit Memory operations without an inference provider.

Ctrl-C performs a clean shutdown. Restarting the command reopens the same database.

The Dashboard is an optional content viewer for personal use and demonstrations. It is disabled by default and needs no separate frontend installation or model configuration. To enable it locally without a token, save these settings in an environment file:

POWERCONTEXT_SERVER_HTTP_HOST=127.0.0.1
POWERCONTEXT_SERVER_DASHBOARD_ENABLED=true
POWERCONTEXT_SERVER_ACCESS_MODE=disabled

To require authentication, set POWERCONTEXT_SERVER_ACCESS_MODE=enforced and set POWERCONTEXT_SERVER_AUTH_TOKEN to your own long random credential. The configuration wizard also offers this choice when enabling Dashboard locally.

chmod 600 /path/to/powercontext.env
powercontext config validate --env-file /path/to/powercontext.env
powercontext server run --env-file /path/to/powercontext.env

Open http://127.0.0.1:8000/dashboard/home, using the actual port if you change it. With authentication disabled, the page opens directly. When enabled, sign in with the Server token and configure connected Agents to use it for API and MCP requests. The CLI does not automatically load a directory's .env file.

The first visit selects the Server default Scope. Pages are empty until content is saved. Save a Memory through an Agent or public API, then refresh Memories in the same Scope. Experiences, skills, handoffs, and usage also come from saved records. The Dashboard does not capture sessions, run generation, or approve candidates. The Dashboard and Agent must use the same Server and Scope.

Open Profile to read the saved profile, inspect Version history, or verify its sources. Selecting a historical revision does not change the current profile. In Handoff, use Export Markdown on a collection entry or its detail page to download that exact revision, including its full text, omissions, and citations. If sign-in expires, sign in again to return to the selected detail, then repeat the download.

When authentication is enabled, all token holders use one identity. Multi-user RBAC deployments should leave the Dashboard disabled and use the API, MCP, or host integrations. See Deploy the Server for network and credential configuration.

This minimal launch does not enable model-backed extraction or vector search. To generate and validate one explicit environment file for those capabilities, continue with the Enable extraction and vector search.

Use embedded seekDB

Embedded seekDB is available on Linux and macOS when a compatible pylibseekdb wheel is available. Windows does not support this embedded backend. Install or replace the tool with the optional seekDB extra:

uv tool install --force "powercontext[cli,server,seekdb]==1.4.0"

When switching from SQLite, remove POWERCONTEXT_SERVER_DATABASE_URL from the Server process environment. An explicit SQLAlchemy database URL is not valid for seekDB. Then select the backend and start the Server:

unset POWERCONTEXT_SERVER_DATABASE_URL
export POWERCONTEXT_SERVER_DATABASE_KIND=seekdb
powercontext server run

server run loads .env from the current directory when present. Export values in the shell to override that file, pass --env-file <path> to select another file, or pass --no-env-file to ignore environment files. Process managers and containers should normally provide an explicit environment instead of relying on their working directory.

PowerContext always uses seekDB's built-in test database. Leave POWERCONTEXT_SERVER_DATABASE_PATH unset to store the instance in the seekdb subdirectory of the PowerContext user data directory. If POWERCONTEXT_HOME is set, the default is $POWERCONTEXT_HOME/seekdb; set POWERCONTEXT_SERVER_DATABASE_PATH only when a different location is required.

In another terminal, verify that the Server and database are ready:

powercontext doctor
powercontext ready
powercontext capabilities

Verify the installation

powercontext doctor
powercontext ready
powercontext capabilities

doctor checks the installed package, Server liveness, and Server readiness without requiring an integration. Server readiness covers the database and each configured inference provider. Runtime or database failures return not_ready; an inference failure returns degraded without removing database-backed operations from traffic. ready and capabilities show the readiness and enabled capabilities of the running service. For Agent diagnostics, use the guide for each integration. For Server status definitions and recovery steps, see Troubleshoot.

For a long-running process, Docker, authentication, or remote access, continue with Deploy the Server.

Update or replace an installation

Before upgrading an existing deployment, back up its database and configuration. Version 1.1.0 upgrades legacy tag-table constraints during Server startup to support Topic Memory tags. Stop the old Server instances and start one upgraded instance first so the schema upgrade completes before other instances connect. Databases from before 1.0.0 also need the Artifact processing migration if it has not already been completed. Existing collection-based Memory databases also require the offline Atomic Memory migration for existing collection databases. Complete any required Artifact processing migration first, stop all writers, then apply and verify the Atomic Memory migration. Start the new service only after verification returns ready: true. Upgrade the Server, clients, and Agent integrations together. The Dashboard must be explicitly enabled; static Bearer authentication is optional for local use. See Deploy the Server. Remote plaintext HTTP connections require explicit client consent; see Connect to a remote Server.

Review the Dream coordinated upgrade requirements before upgrading an existing database. The unified Candidate routes replace /v1/artifact-candidates/* with /v1/candidates/* without aliases, and Dream Clients require contract 2. Existing Dream storage needs an explicit migration after unfinished runs have drained. The current unified migration bundle reports server_ready=false; it does not provide a complete production Server upgrade path. Atomic Memory verification alone does not establish that readiness. Do not bypass migration_required or migration_framework_not_ready.

To upgrade to 1.4.0:

uv tool install --force "powercontext[cli,server]==1.4.0"

To replace the installed tool with another Git ref:

uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@<ref>"

Update each installed host using its integration guide and the same ref. Restart the Server and open a new host session after updating. Existing SQLite data remains in the user data directory unless POWERCONTEXT_HOME or the database URL changes.

Install a Python role

An application that imports the async Client SDK should add it to that application's environment:

uv add "powercontext[client]==1.4.0"

Use builtin for in-process Python composition, server for the service, client for the Python SDK, or cli for the Server-backed command line. An extra that is only present in the isolated uv tool environment is not importable by an unrelated Python project.