Configuration options

Windows support is experimental.

PowerContext reads configuration from environment variables when each process starts. server run loads .env from the current working directory when that file exists. Pass --env-file <path> to select a different file without also merging .env, or pass --no-env-file to disable file loading. For server run, CLI options override process environment variables, process variables override values from the selected file, and defaults apply last. Agent hosts can load their own environment files according to their host-specific rules.

For the configuration-file workflow, including generation, redacted inspection, validation, and launch, see Configure a Server environment. Treat every environment file as a secret-bearing deployment artifact.

service install additionally requires the file to be a regular, non-symlink file owned by the current user with no group or other permissions. The service records its identity and refuses to launch if the file is replaced or its ownership, permissions, or contents change; run service install again after an intentional update.

User data

POWERCONTEXT_HOME overrides the directory used by the installed Server:

export POWERCONTEXT_HOME=/srv/powercontext

Without an override, the default is:

• Linux: $XDG_DATA_HOME/powercontext, or ~/.local/share/powercontext;
• macOS: ~/Library/Application Support/powercontext;
• Windows: %LOCALAPPDATA%\\powercontext.

The default SQLite database is powercontext.db in this directory. The four built-in background processors persist intents and scheduling checkpoints in the same database. Existing installations require offline migration.

Server

Server settings use the POWERCONTEXT_SERVER_ prefix.

Topic Workers enforce a durable allowance per unadvanced Scope Cursor: 3 attempts, 512 reserved provider requests, and 64,000,000 estimated token-capacity units across all retries. A Window admits at most 4,194,304 canonical evidence characters including metadata; nested input is also bounded. Exhaustion preserves Sources, Cursor, Pending, and the same-Scope tail, and stops further provider calls. Flush and restart do not reset it; inspect pc_topic_memory_work_budgets and structured errors for operator remediation.

Topic generation accepts max_tokens, temperature, top_p, top_k, seed, presence_penalty, frequency_penalty, timeout, openai_reasoning_effort, openai_text_verbosity, service_tier, openai_service_tier, anthropic_service_tier, and anthropic_effort as bounded scalar settings. Topic Embedding accepts only dimensions and truncate. Background/hidden-history/native-tool settings and extra_body disable Topic processing while ordinary inference continues; explicitly configured automatic Topic scheduling fails startup instead. Supported provider prefixes are openai, openai-chat, openai-responses, anthropic, azure, azure-responses, deepseek, and openrouter, plus the local test model; Embedding must also be supported by its SDK adapter. Topic SDK transport retries and automatic continuations are disabled. Non-Topic inference keeps its existing settings behavior.

When the cursor signing secret is unset, a file-backed SQLite Server creates a private key beside its database; other persistent backends create one in the PowerContext user data directory. In-memory SQLite uses a process-local key. Configure the same POWERCONTEXT_SERVER_CURSOR_SIGNING_SECRET on every replica so a cursor remains valid after restart or when the next request reaches another replica. Never expose or rotate this value while issued cursors must remain valid.

Access Control is disabled by default. In enforced mode, API and MCP requests must establish a Principal through the selected Authentication Provider; the liveness and readiness endpoints remain public. The built-in static-bearer Provider accepts Authorization: Bearer <token>. Plain HTTP is trusted only on a loopback address (localhost, ::1, or any address in 127.0.0.0/8). The Server refuses to start when it binds to a non-loopback address while authentication is disabled; either enable authentication, keep the bind on loopback, or, when TLS is terminated upstream or the network is otherwise controlled, set POWERCONTEXT_SERVER_ALLOW_UNAUTHENTICATED_NON_LOOPBACK=true to opt in explicitly. Use TLS before exposing an authenticated Server over a network.

POWERCONTEXT_SERVER_ACCESS_MODE is the only supported switch. disabled bypasses authorization decisions inside the trusted local boundary. enforced enables one policy enforcement point plus Binding and audit behavior. Authorization defaults to the built-in implementation and can be replaced through create_server_app(access_control=...); Authentication is supplied through create_server_app(authentication_provider=...). Without an injected Authentication Provider, the Server accepts only the legacy AUTH_TOKEN fallback and bootstraps its fixed server-token Principal as a built-in administrator. Startup fails when neither is available. The old AUTH_ENABLED=true plus AUTH_TOKEN configuration maps automatically to ACCESS_MODE=enforced.

Authentication establishes a Principal; Access Control decides what that Principal may do. Principal IDs are deployment-wide unique, non-reused identifiers; description is display metadata and is not part of identity. The built-in static token always represents one service Principal, so it cannot distinguish user A from user B. The compatibility token materializes explicit Server and per-scope roles for that Principal. Inject the deployment Authentication Provider and corresponding AccessControlService when different users or groups need different access.

Background Memory, Topic Memory, Experience, and Profile processing use the service Principal selected by ACCESS_BACKGROUND_PRINCIPAL_ID, falling back to the fixed static Principal. That Principal must have scope.contribute for each processed scope and write permission on existing Artifacts it changes. New entries, Artifacts, and Candidates retain its ownership or owner attestation in the same transaction as processing completion. An enforced deployment with background capabilities fails startup if its identity or authorization provider cannot be reconstructed in a child process, even when automatic schedules are disabled: accepted work still needs recovery. The built-in provider supports this reconstruction. Injected providers and model objects remain usable by synchronous SDK/Server operations with background capabilities disabled (ARTIFACT_PROCESSING_FAMILIES=[]).

SDK workers without a Server identity do not require Server authorization dependencies. Built-in background workers use the built-in Source definitions. A custom Source registry requires custom processing bindings for every enabled family, or disabling built-in background families with ARTIFACT_PROCESSING_FAMILIES=[]; otherwise startup fails before accepting work. Turning off schedules alone is insufficient because explicit requests still start workers. Custom Source registries remain available to synchronous SDK contexts and API-only composition.

The authenticated /metrics endpoint exposes powercontext_server_artifact_processing_* observations with only a family label: Worker capacity, ready/retry queues, unacknowledged Scopes, discovery and invocation duration, completions, failures, and timeouts. Unacknowledged counts reflect the latest discovery; counters reset with the Supervisor instance.

Remote and multi-user deployments must use enforced. In that mode, HTTP, MCP, and metrics share one Server PEP. /v1/access/me reports the server/scope/artifact Resource Kinds, Provider batch/list/relationship capabilities and Artifact Family profiles. Managed Skill export and installation do not introduce separate Access actions: the recipient first needs artifact.read on the logical Skill identity, then chooses whether and how to install an exact Revision.

The built-in Access schema uses the configured SQLite, seekdb, or OceanBase backend, but remains Server-owned rather than becoming a Runtime domain. A custom deployment can inject an AccessControlService into create_server_app. CasbinAuthorizationProvider is the included writable external adapter: it evaluates the fixed action vocabulary in embedded Casbin while using the canonical Binding Store as its persistent adapter, so it supports point/batch checks, safe resource filters, create/revoke, expiry, and CAS without a second policy shadow. Pass that provider as both the decision provider and relationships, and retain the relational repository as the audit store.

AuthZenAuthorizationProvider is an included decision-only adapter for the OpenID AuthZEN Authorization API 1.0 evaluation and evaluations endpoints. Configure its capabilities with multi_requirement_check=true, relationship_management=false, and safe_resource_filtering=false; self-service Binding mutation and authorized resource listing then return 503 instead of claiming an unsafe capability. The adapter accepts HTTPS endpoints or loopback HTTP, rejects credentials embedded in URLs, and does not expose PDP response bodies or errors. An authentication middleware must still bind an opaque PrincipalRef; scope_id is only a resource partition and never establishes identity.

The Python Client and CLI apply the matching rule for general outbound requests: a configured unencrypted http:// Server URL is accepted only for loopback hosts. The explicit remote Skill Receiver PoC exception is documented below. Code whose http:// base URL is only a routing label for a transport that is secure in practice, such as an in-process ASGI app, Unix-domain socket, or TLS-terminating proxy, must supply its own http_client and pass trust_transport_security=True explicitly. See Deploy the Server for a safe Docker and remote-access setup.

By default, the Server treats its startup directory as the workspace and exposes two writable local project targets: <workspace>/.agents/skills for Codex and <workspace>/.claude/skills for Claude Code. Missing directories are harmless and are created only by an explicit publication operation. Set POWERCONTEXT_SERVER_WORKSPACE once for systemd, containers, or other launchers whose working directory is not the project.

Configure POWERCONTEXT_SERVER_PUBLIC_URL when remote Skill Receivers should connect through a stable externally reachable origin. Enrollment commands may otherwise use the remote CLI's configured Server URL.

For a first-phase PoC on a protected internal test network, direct HTTP requires explicit consent on both sides. Set POWERCONTEXT_SERVER_ALLOW_INSECURE_HTTP=true, advertise an http:// POWERCONTEXT_SERVER_PUBLIC_URL, and bind the listener to an address reachable by the target. The enrollment command must include remote-enroll --allow-insecure-http. Without the Server setting, the remote endpoints reject non-loopback HTTP. Without the Receiver option, the CLI rejects the URL before transmitting the one-time enrollment code. The permission is stored in the owner-only Receiver configuration so remote-watch and its systemd user service keep the same policy without embedding credentials or extra flags in the unit. This switch adds no TLS, network isolation, or protection against interception: do not use it on the public Internet or an untrusted network, and prefer HTTPS for persistent deployments.

export POWERCONTEXT_SERVER_HTTP_HOST=0.0.0.0
export POWERCONTEXT_SERVER_PUBLIC_URL=http://powercontext.internal.example:8765
export POWERCONTEXT_SERVER_ALLOW_INSECURE_HTTP=true
export POWERCONTEXT_SERVER_ALLOW_UNAUTHENTICATED_NON_LOOPBACK=true
powercontext server run

# On the target project:
powercontext --server-url http://powercontext.internal.example:8765 \
  skill remote-enroll --workspace "$PWD" --install-service --allow-insecure-http

The non-loopback opt-in in this example is independent of the Receiver transport exception: it acknowledges that all Server routes on this listener are reachable without the Server-wide bearer token. Prefer enabling authentication or terminating TLS in front of a loopback-bound Server whenever the deployment permits it.

Handoff Report API routes are independently enabled by default. See Use Handoff Report for selection, inspection, and export.

The Artifact Processing Supervisor is enabled by the default all role. OceanBase deployments may run api and background separately; powercontext server run --role background starts no HTTP, MCP, or Dashboard listener, and multiple background candidates use the database Lease to elect one active Leader. SQLite and embedded seekdb support only the single-process all role. Automatic Topic Memory waves remain disabled until a positive interval is set; explicit flush work remains recoverable regardless of that interval. Topic workers need file-backed SQLite: configuring a generation model with an in-memory SQLite database is rejected before processing is advertised. Use a persistent POWERCONTEXT_SERVER_DATABASE_URL, such as sqlite+aiosqlite:////srv/powercontext/runtime.db. Memory, Topic Memory, Experience, and Profile all use the Supervisor. OceanBase permits their schedules in split roles. SQLite and embedded seekdb retain one all host. Every Family has its own quota and timeout in both modes; spare quota is not shared. Disabling automatic admission preserves already accepted requests. The API and background instances must agree on mode, registered Families and trigger capabilities. Model resources are only required by workers. Changing modes requires coordinated offline migration; mixed modes cannot start. Conflicting explicit old/new configuration aliases fail startup; equal values are accepted.

Normal Runtime startup initializes and recovers the configured search indexes. Topic Workers reuse that database without rebuilding the unrelated Memory/Experience search projections for each Window; Topic index validation and publication guards still apply. If an empty database is reconfigured to another Topic retrieval shape or embedding profile, reopen existing Runtimes with the same configuration: stale Runtimes reject Topic search, exact get, and current-head browsing with a retrieval-shape error instead of reading another vector space.

Normal Runtime startup initializes and recovers the configured search indexes. Topic Workers reuse that database without rebuilding the unrelated Memory/Experience search projections for each Window; Topic index validation and publication guards still apply. If an empty database is reconfigured to another Topic retrieval shape or embedding profile, reopen existing Runtimes with the same configuration: stale Runtimes reject Topic search, exact get, and current-head browsing with a retrieval-shape error instead of reading another vector space.

Provider credentials, such as OPENAI_API_KEY, are read by the configured inference provider. Do not place secrets in command-line arguments, documentation, or Memory. Replace provider:model-name with a model identifier supported by Pydantic AI. Scheduled extraction requires both a generation model and POWERCONTEXT_SERVER_RUNTIME_SCHEDULE_SECONDS. An explicit Memory write does not require either.

The default coding extraction profile keeps cross-task work context such as preferences, decisions, constraints, expensive facts, and unfinished progress. Select conversation when the product must preserve independently answerable personal facts, relationships, events, exact dates, lists, and historical states from dialogue evidence:

export POWERCONTEXT_SERVER_RUNTIME_MEMORY_EXTRACTION_PROFILE=conversation

The profile affects future Source processing only. It does not reinterpret existing Memory revisions.

Enable answer-oriented Memory reranking when broad Hybrid recall is more important than the latency and token cost of one additional structured generation request:

export POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL=provider:model-name
export POWERCONTEXT_SERVER_RUNTIME_MEMORY_RERANK_ENABLED=true
export POWERCONTEXT_SERVER_RUNTIME_MEMORY_RERANK_CANDIDATE_LIMIT=30

Reranking is disabled by default. When enabled, the Runtime retrieves and fuses the configured candidate pool, then uses the generation model at temperature zero to select no more than the search request's final limit. It does not change stored Memory or indexes. Provider and structured-output failures remain visible as inference errors; disable reranking when search must remain independent of model availability. See RFC 0080 for the algorithm, concurrency, and API boundaries.

The built-in reranker is an LLM listwise reranker, not a dedicated cross-encoder protocol. By default it reuses the generation model and its provider settings. Set POWERCONTEXT_SERVER_INFERENCE_RERANK_MODEL to give that LLM operation an independent model, base URL, headers, settings, timeout, and request limit.

The same configured generation model gates explicit Experience generation, managed Skill generation, and semantic Skill fork/evolution. Exact external Skill import and complete package upload do not use a model: PowerContext validates and stores the canonical package bytes, then creates a pending Candidate with the same package digest. Without a generation model, semantic generation returns a capability error before persisting a Candidate; Review, package inspection and download, exact import, usage recording, and external Skill scan/list/resolve continue to work.

Experience incubation has its own Supervisor binding and persisted Source cursor. Each invocation inspects a finite window controlled by SOURCE_WINDOW_LIMIT and exposes only Content Sources whose metadata contains "kind": "task-outcome" to the model. It creates pending Experience Candidates in the Review Inbox; it does not approve them, place them in PreparedContext, create a managed Skill, export it to an Agent target, or execute anything. Memory and Experience keep independent scheduling intervals, Worker quotas, and business cursors. Unsetting an interval stops new automatic admission for that Family while preserving accepted work. See Create and review an Experience for setup and verification steps.

Agent Skill targets

The zero-configuration flow uses the Codex and Claude Code project folders under the workspace. Provide a JSON override only for custom paths, user-level targets, environment compatibility facts, or to explicitly disable local discovery. For a basic JSON shape and verification flow, see Configure Agent Skill targets. A compatibility-aware override looks like:

export POWERCONTEXT_SERVER_EXTERNAL_SKILLS='{
  "host_id": "workstation-1",
  "targets": [
    {
      "target_id": "codex-project",
      "agent_kind": "codex",
      "installation_scope": "project",
      "path": "/srv/project/.agents/skills",
      "allow_managed_publish": true,
      "environment": {
        "operating_system": "linux",
        "architecture": "x86_64",
        "commands": {"python": "3.13.2", "bash": "5.2"},
        "network_policy": "restricted",
        "writable_roots": ["workspace"],
        "dependency_install_policy": "denied",
        "environment_names": ["CI"]
      }
    },
    {
      "target_id": "claude-project",
      "agent_kind": "claude_code",
      "installation_scope": "project",
      "path": "/srv/project/.claude/skills",
      "allow_managed_publish": true
    }
  ]
}'

Setting POWERCONTEXT_SERVER_EXTERNAL_SKILLS replaces both automatically generated project targets in full; use {"host_id": null, "targets": []} to disable local discovery and publication. Target IDs must be unique. agent_kind supports codex and claude_code; installation scopes are user, project, and plugin. PowerContext scans only the immediate Skill package directories under default or explicit targets; it does not infer a user home directory, install packages, or grant execution authority. Custom targets default allow_managed_publish to false; when true, an explicit publication operation may safely create or update an approved managed Skill in that target. Publication materializes the exact reviewed package, including scripts and references, without executing it or injecting a sidecar into the package. Unpublication succeeds only for an intact package whose binding and tree digest still match; local drift and foreign content remain untouched. Publication cannot submit an arbitrary path or overwrite a foreign or modified package. The host_id, locator, and registration are local-environment state, not a cross-host contract. Existing codex_roots configuration remains accepted as a Codex-only compatibility form; new configuration should use targets.

The optional environment object contains only observed, secret-free compatibility facts. Command values are version labels, and environment_names records names only, never values. PowerContext does not probe or execute package scripts to construct this profile. When it is absent, packages containing scripts report unknown compatibility; when present, the Skills Library compares known script interpreters with the observed command names and returns a reasoned assessment. The assessment does not grant network, filesystem, dependency-install, or environment access.

The Server always creates non-recording OpenTelemetry request context so X-PowerContext-Request-ID can be derived from the inbound span. To enable recording and export for a CLI-managed Server, install powercontext[cli,server,tracing-otlp], enable tracing, and configure standard OpenTelemetry variables such as OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, and OTEL_SERVICE_NAME. Programmatic Server integrations that do not use the powercontext command may omit the cli extra.

Enabling tracing also produces spans for the generation and embedding calls that PowerContext constructs, without recording prompts, model responses, Memory content, or vectors. See Trace with Phoenix for a working configuration, and Trace with Langfuse for a backend that authenticates the exporter through OTEL_EXPORTER_OTLP_HEADERS.

To use OceanBase, provide its URL through your environment or secret manager:

export POWERCONTEXT_SERVER_DATABASE_KIND=oceanbase
export POWERCONTEXT_SERVER_DATABASE_URL="$OCEANBASE_URL"

The URL must use the mysql+aoceanbase driver, include an explicit port and database, and set charset=utf8mb4. The tenant must use MySQL compatibility mode.

Embeddings and SQLite vector search

Vector search requires all three embedding identity variables: model, stable profile ID, and positive dimension. Normalization defaults to unit; timeout and batch size are optional controls. SQLite vector and hybrid search use the bundled sqlite-vec extension. The Server probes it when opening the database, and startup fails if the installed library is incompatible with the platform or SQLite build. Full-text search remains available without an embedding profile. For configuration and capability verification, see Configure vector search.

CLI Server connection

Equivalent one-off flags are available for the Server URL and timeout on powercontext. The token is accepted only through the environment so it does not appear in command-line arguments.

Agent integrations

For installation, connection, authentication, and environment variables, use the guide for your integration.