praxist-runtime-install

name

praxist-runtime-install

description

Install Praxist runtime dependencies and configure user-level Praxist provider credentials for a source checkout or pip-installed environment. Use when the user asks an agent to install or repair Praxist requirements, prepare a Praxist host, create the Praxist Python environment, install the `praxist` CLI, install Claude SDK or official Codex SDK runtime extras, install source-checkout test/dev dependencies, persist API keys or provider settings, verify imports, or diagnose missing dependencies. For source checkouts include the repository test/dev dependency group; for pip package installs keep the install runtime-only. Do not use for docs, task-specific training, dataset, benchmark, or experiment dependencies.

Praxist Runtime Install

Use this skill to install dependencies needed to run Praxist itself. For local source checkouts, also install the repository's test/dev dependency group so the agent can validate Praxist code changes. Keep task-specific dependencies separate: each task project owns its own training/evaluation environment, datasets, CUDA/PyTorch stack, and benchmark packages.

This is separate from scripts/install_codex_skills.sh: that compatibility script installs or updates Codex or Claude Code skill symlinks. The bundled scripts/install_runtime_deps.sh in this skill installs Praxist runtime Python dependencies and, when explicitly supplied with provider/key options, writes user-level Praxist environment config.

Scope

Install dependencies for the Praxist control plane:

• base package: praxist
• default runtime extras: agents,codex
• tested claude-agent-sdk==0.2.136 plus MCP support for agent_runtime:claude_sdk when a package or repaired install did not already provide them
• tested openai-codex==0.147.0, codex-relay==0.5.5, and MCP support for agent_runtime:codex_sdk; this peer runtime uses the Python SDK and its local app-server. The SDK-bundled Codex binary can own saved ChatGPT authentication for native OpenAI, but Praxist does not reuse an interactive CLI process
• source-checkout validation dependencies: repository dependency-groups.dev
• user-level provider config: API keys, PRAXIST_LLM_PROVIDER, PRAXIST_AGENT_SYSTEM, and PRAXIST_MODEL only when the user supplies them
• optional remote-storage extra: storage, only when the user asks for S3/object-storage support
• built-in pseudonymous product-usage client and consent CLI; no separate SDK package or service dependency is required for ordinary Praxist operation
• bundled Praxist User Agreement, scrollable review command, and local version-bound acceptance record
• optional operator CLIs: report whether the human-facing codex command is present. The SDK-bundled binary is sufficient for Codex-native login, so do not install a global CLI unless the user explicitly asks

Use this install split:

• source checkout: install runtime extras plus Praxist repository test/dev dependencies
• pip package: install runtime extras only; do not install test/dev dependencies
• no task-local packages unless the user separately asks to set up a task project
• documentation dependencies come only from the source checkout's docs optional dependency group; do not invent a parallel requirements file

Default Workflow

1. Identify the install surface.

   • Source checkout: a directory with pyproject.toml declaring name = "praxist" and an praxist/ package.
   • Pip package: no source checkout is available, or the user explicitly wants a package install.
   • Existing venv: respect an explicitly active or user-specified venv when practical.

2. Verify Python.

   • Require Python >=3.11.
   • Prefer python3.11, then python3, then python.
   • Do not change system Python.

3. Install the published package and runtime extras directly with pip:

   python3 -m pip install --index-url https://pypi.org/simple "praxist[agents,codex]"
   

   For a source checkout under active development, use its bundled helper so repository test dependencies are included:

   bash skills/praxist-runtime-install/scripts/install_runtime_deps.sh --repo /path/to/Praxist
   

   Add remote-storage support only when requested:

   bash skills/praxist-runtime-install/scripts/install_runtime_deps.sh --repo /path/to/Praxist --with-storage
   

4. Verify the runtime install.

   • Run <venv>/bin/praxist --help or uv run praxist --help.
   • Run <venv>/bin/python -c "import praxist; print(praxist.__file__)".
   • For agent_runtime:codex_sdk, import openai_codex and mcp, and confirm the venv contains codex-relay and the SDK-bundled Codex binary.
   • Only when the user explicitly selects Codex-native mode, run praxist setup --profile codex-native --install-skills codex in a local terminal. It reuses or repairs the SDK-bundled Codex ChatGPT login and verifies the result. Do not make this subscription check a requirement for another provider/runtime profile. Never print, manually inspect, or place token files in a task or run directory. The runtime may internally stage file-based auth in a private OS-temporary home that it deletes on close.
   • Optionally run codex --version only to verify the separate human operator interface used to invoke Praxist skills directly.
   • Report API key presence only; never print secret values.

Source Checkout Policy

For a source checkout, install from the checkout itself. The default script behavior is:

uv sync --group dev --extra agents
uv pip install --python .venv/bin/python \
  --index-url https://pypi.org/simple codex-relay==0.5.5
uv pip install --python .venv/bin/python \
  --index-url https://pypi.org/simple openai-codex==0.147.0

when uv is available, otherwise:

python -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install \
  --index-url https://pypi.org/simple codex-relay==0.5.5
.venv/bin/python -m pip install \
  --index-url https://pypi.org/simple openai-codex==0.147.0
.venv/bin/python -m pip install -e ".[agents,codex]"
.venv/bin/python -m pip install <dependency-groups.dev from pyproject.toml>

Use --method pip if the user wants to avoid uv creating or updating a lock file. The public index is scoped to the two Codex-specific packages so an incomplete default mirror cannot silently omit them. Praxist pins both agent SDKs to the versions exercised by its runtime and conformance tests; do not upgrade either SDK independently. Override PRAXIST_RUNTIME_CODEX_INDEX_URL only when the approved mirror carries the exact pinned packages.

Pip Package Policy

For package installs, create or reuse a venv and install:

python -m pip install --index-url https://pypi.org/simple "praxist[agents,codex]"

If --with-storage is requested, install:

python -m pip install --index-url https://pypi.org/simple "praxist[agents,codex,storage]"

The package ships docs, complete examples, task templates, and skills as package resources; do not assume a source checkout exists after pip installation. After pip installation, praxist setup materializes the writable bundled examples. For package-only automation, run praxist examples list, install the selected example with praxist examples install <name>, and report its absolute destination. Never run against a read-only package-resource copy.

The codex extra provides the official Python SDK, its app-server support, codex-relay, and MCP dependencies. OpenAI connects directly. DeepSeek and OpenRouter require the relay because they expose Chat Completions while the Codex app-server expects Responses. Praxist owns the private run-scoped relay; do not configure a task-local relay or start one manually per peer.

Credential Configuration

When the user provides a provider, model, agent system, or API key as part of this skill invocation, treat that as permission to write user-level Praxist config. Default file:

${XDG_CONFIG_HOME:-$HOME/.config}/praxist/env

The bundled script writes shell-compatible export ...=... lines and sets the file mode to 0600. Praxist still reads credentials through environment variables at startup; users can activate the file for the current shell with:

set -a; . "${XDG_CONFIG_HOME:-$HOME/.config}/praxist/env"; set +a

Provider names map to these env vars:

Provider	Env var
anthropic	ANTHROPIC_API_KEY
openrouter	OPENROUTER_API_KEY
deepseek	DEEPSEEK_API_KEY
openai	OPENAI_API_KEY
moonshot / kimi	MOONSHOT_API_KEY
qwen	DASHSCOPE_API_KEY
google	GOOGLE_API_KEY
mistral	MISTRAL_API_KEY
groq	GROQ_API_KEY
xai	XAI_API_KEY
brave	BRAVE_API_KEY

Never ask the user to provide a raw key in chat. Pause and have the operator run the local masked configuration prompt:

praxist setup --interactive

The prompt displays one * per character and keeps the secret out of argv, shell history, agent messages, logs, and task files. Continue only after the operator reports that local setup completed. If this is not an interactive terminal, leave configuration incomplete rather than transporting the key through the conversation.

If the key is already exported, avoid handling the raw secret:

bash skills/praxist-runtime-install/scripts/install_runtime_deps.sh \
  --skip-install \
  --provider deepseek \
  --api-key-env DEEPSEEK_API_KEY

Provider-only configuration is allowed:

bash skills/praxist-runtime-install/scripts/install_runtime_deps.sh \
  --skip-install \
  --provider openrouter

This writes PRAXIST_LLM_PROVIDER=openrouter and leaves API keys unchanged. Do not modify shell rc files unless the user explicitly asks for shell auto-loading; if that is needed, source this dedicated env file rather than writing raw secrets into .bashrc or .zshrc.

Safety Rules

• Do not print raw values for environment variables containing KEY, TOKEN, SECRET, PASSWORD, or CREDENTIAL.
• Do not install OS packages with apt, yum, dnf, pacman, brew, npm -g, cargo install, or similar global package managers without explicit user approval.
• Do not install CUDA, PyTorch, benchmark, dataset, or task-local packages as part of this skill.
• Do not write raw credentials into shell rc files, task configs, logs, docs, or git-tracked files. Use the dedicated user-level Praxist env file above.
• Do not recurse through large directories while locating a checkout. Check only explicit candidate paths and immediate parent-level candidates.

Result Report

Finish with a concise table:

Item	Status
Install mode	source checkout / pip package
Python	executable and version
Praxist CLI	path and praxist --help result
Runtime extras	installed extras and exact agent SDK versions
Test/dev deps	installed for source checkout / omitted for pip package
Provider config	config file path and redacted variable names written
Codex SDK runtime	openai_codex import and codex-relay path
Codex saved auth	ChatGPT login present / not requested / corrective action
Operator Codex CLI	present / missing / not requested
User Agreement	accepted current version / awaiting explicit operator choice
Product-usage consent	granted / denied / unset and awaiting explicit reply
Remaining blockers	exact next action

If installation fails, include the failing command and the shortest corrective action. Do not continue into task setup or run launch.