# Quickstart This page takes you from nothing to the first fix Praxen opens as a pull request. At the end, your cloud, code and telemetry are connected, and the first issue is being worked in a thread you can read from top to bottom. ::steps{level="3"} ### Install the CLI or sign in at the console One command on macOS or Linux installs the CLI, signs you in, and starts connecting your stack: ```bash [Terminal] curl -fsSL https://getpraxen.app/setup | bash ``` Sign in with Google, GitHub or email; signing in creates your account and workspace when you do not have one yet. If you would rather skip the terminal, sign in at [console.getpraxen.app](https://console.getpraxen.app), create a workspace, and connect from **Settings**. Package managers and Windows are covered on the [CLI](https://docs.getpraxen.app/tools/cli) page. ### Connect a repository, a cloud and an observability tool The installer offers each connection in the order below, and the console has a page for each under **Settings**. | What to connect | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Repository | Install the GitHub App so agents can read code, assess pull requests against production, and open fixes. See [Repositories](https://docs.getpraxen.app/connect/repositories). | | Cloud account | Every resource appears on the topology, kept in sync and checked on a schedule. See [Clouds](https://docs.getpraxen.app/connect/clouds). | | Slack | Mention Praxen in a channel and the answer arrives in a Slack thread. See [Integrations](https://docs.getpraxen.app/connect/integrations). | | Observability tool | Logs, metrics and alerts from your provider feed detection and give agents evidence to cite. See [Integrations](https://docs.getpraxen.app/connect/integrations). | Clouds whose logs and metrics Praxen can query (AWS, Cloudflare, Vercel, Fly, Render, Railway and Kubernetes) already count as a telemetry source, so you can start without a separate observability tool. ### Ask a first question Open **Threads**, choose **New thread**, and ask about what Praxen already sees, for example: "Which services run in our production cloud account, and which had deploys in the last 24 hours?" The answer draws on the connected resources and cites the tool calls behind it. ### Watch the first fix run Detection starts as soon as resources sync, and alerts from your connected tools join the same lifecycle. Each real problem becomes an [issue](https://docs.getpraxen.app/detect/issues) worked by one [fix run](https://docs.getpraxen.app/investigate/fix-runs): the agent reaches a verdict, traces the cause, and opens a pull request when a code change fixes it. Read the run under **Threads** with the **Type** filter set to **Fix run**; the pull request appears in your repository for your review. ### Connect your coding agent Ask the same questions from your editor or terminal. [Praxen for coding agents](https://getpraxen.app/for-agents) has the prompt to paste and the CLI path. `praxen setup` registers the [platform MCP server](https://docs.getpraxen.app/tools/platform-mcp) with your coding agents through the [CLI](https://docs.getpraxen.app/tools/cli). :: ## Related - [How Praxen works](https://docs.getpraxen.app/getting-started/how-it-works): the loop and every primitive you will meet in the console, on one page. - [Connect](https://docs.getpraxen.app/connect): everything you can connect and what Praxen builds from it. - [Work from your tools](https://docs.getpraxen.app/tools): the MCP server, the CLI and the plugins that bring Praxen into your editor. - [API reference](https://api.getpraxen.app/v1/reference): the full HTTP surface for scripts and CI. # How Praxen works Praxen connects to your clouds, repositories and observability tools, watches them for problems, and works each one to a verdict and a fix. You read the whole story in threads, from the console, Slack, your coding agent or the terminal. ## The loop 1. **Connect**: you connect a cloud, a repository and an observability tool, and Praxen builds a live map of your system that every agent reads. See [Connect](https://docs.getpraxen.app/connect). 2. **Detect**: checks built from your telemetry raise issues, impact assessments check each pull request against production, and risky configuration is flagged. See [Detect](https://docs.getpraxen.app/detect). 3. **Investigate and fix**: one agent works each issue with your real tools, shows its evidence, and opens the fix as a pull request you review. See [Investigate and fix](https://docs.getpraxen.app/investigate). 4. **Work from your tools**: the same agent answers from your editor, terminal, CI or Slack. See [Work from your tools](https://docs.getpraxen.app/tools). ## The primitives | Primitive | What it is | Where you see it | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Context graph | The live model of your stack that clouds, repositories, and integrations feed, and every agent reads from. | Rendered as the [topology](https://docs.getpraxen.app/connect/topology). | | Cloud account | A connected cloud provider whose resources Praxen syncs, tiers and records every change to. | **Clouds** in **Settings**; see [Clouds](https://docs.getpraxen.app/connect/clouds). | | Repository | A connected code host that agents search, read and open pull requests against, linked to the resources it deploys to. | **Repositories** in **Settings**; see [Repositories](https://docs.getpraxen.app/connect/repositories). | | Integration | A connected observability tool, chat, code host, issue tracker or coding agent that contributes tools agents call and events detection listens to. | **Integrations** in **Settings**; see [Integrations](https://docs.getpraxen.app/connect/integrations). | | Topology | The graph view of your infrastructure: resources as nodes, relationships as edges, each with its properties and change history. | **Topology**; see [Topology](https://docs.getpraxen.app/connect/topology). | | Memory | Markdown files in a git repository per workspace that hold confirmed findings, so the next investigation starts from what you already know. | See [Memories](https://docs.getpraxen.app/connect/memories). | | Check | A scheduled evaluation of a resource, built from your providers and saved queries, that raises an issue when it breaches. | A fix run's **Lineage** panel. | | Issue | The single detection record: something may be wrong with a resource. A fix run gives it a verdict, confirmed or dismissed. | Its fix run thread; see [Issues](https://docs.getpraxen.app/detect/issues). | | Impact assessment | A check of each pull request against the production resources it deploys to, posted as a comment before you merge. | The comment on the pull request; see [Impact assessments](https://docs.getpraxen.app/detect/pull-request-reviews). | | Advisory | A per-resource recommendation about misconfiguration, resilience risk or an observability gap, with a fix you can hand to an agent. | The resource's panel on the topology; see [Advisories](https://docs.getpraxen.app/detect/advisories). | | Thread | A conversation with an agent that has your full context graph, which you can watch, interrupt, share and continue. | **Threads**; see [Threads](https://docs.getpraxen.app/investigate/threads). | | Fix run | One agent working one issue from verdict to root cause to pull request, in a single thread. | **Threads** with the **Type** filter set to **Fix run**; see [Fix runs](https://docs.getpraxen.app/investigate/fix-runs). | | Escalation | One record per thing an agent needs from you, cleared when you handle it. | The **Needs you** preset under **Threads**; see [Escalations](https://docs.getpraxen.app/investigate/escalations). | | Autofix | An agent-written code fix that arrives as a pull request in your repository, run by Praxen's coding agent or a connected one such as Devin, Cursor, Factory, Conductor, Capy or Amp. | The pull request, and the thread's **Lineage** panel; see [Autofix](https://docs.getpraxen.app/investigate/autofix). | ## What agents may do Agents read by default: a run nobody has written to uses read-only access to your providers, and a cloud account marked **Read-only** refuses every write call. When you are in a thread, a write call to a provider passes a safety review and then waits for your confirmation before it runs. Code changes land as pull requests in your repository, and the merge is yours. ## Related - [Quickstart](https://docs.getpraxen.app/getting-started): connect your stack and watch the first fix run in five steps. - [Threads](https://docs.getpraxen.app/investigate/threads): every thread type and how to start one from each surface. - [Fix runs](https://docs.getpraxen.app/investigate/fix-runs): how one issue is worked from verdict to pull request. - [Work from your tools](https://docs.getpraxen.app/tools): the write gate as it applies to your coding agent and the CLI. # Connect Connecting is where Praxen starts. You connect cloud accounts, repositories and the tools your team already uses. Praxen builds a topology, stores memory about your system, and checks the resources it finds. Connect one cloud and one observability provider first. Add your code host when you want impact assessments and autofixes. ::card-group :::card --- icon: i-lucide-plug title: Integrations to: https://docs.getpraxen.app/connect/integrations --- Every service you can connect, how connecting works, and exactly what disconnecting removes. ::: :::card --- icon: i-lucide-cloud title: Clouds to: https://docs.getpraxen.app/connect/clouds --- Connect a cloud account and its resources appear on the topology, kept in sync and checked on a schedule. ::: :::card --- icon: i-lucide-orbit title: Topology to: https://docs.getpraxen.app/connect/topology --- The live map of every resource across your clouds and repositories: views, fact sheets, tiers, and the blast radius of any change. ::: :::card --- icon: i-lucide-git-branch title: Repositories to: https://docs.getpraxen.app/connect/repositories --- Connect GitHub so agents can search your code, run it, assess pull requests against production, and follow code to its deployed resources. ::: :::card --- icon: i-lucide-brain title: Memories to: https://docs.getpraxen.app/connect/memories --- A git repository of markdown files per workspace, so the next investigation starts from what you already know. ::: :: ## Related - [How Praxen works](https://docs.getpraxen.app/getting-started/how-it-works) for the loop that runs on top of what you connect. - [Detect](https://docs.getpraxen.app/detect) for the checks and reviews that start once resources are on the topology. # Integrations Integrations connect Praxen to the services around your system. Each one gives agents something concrete to work with, and this page explains connecting and disconnecting once so the provider pages do not have to. ## What it does Connecting a tool registers query tools agents can call: search logs, fetch a pull request diff, run a metrics query, or describe a resource. Connecting a cloud provider also syncs its resources into the [topology](https://docs.getpraxen.app/connect/topology), where scheduled checks and impact assessments use them. ## How connecting works Every provider has a guided connect flow in the console under **Settings > Integrations**, with cloud providers under **Settings > Clouds**. The method depends on the provider, and credentials are stored encrypted. | Method | Description | Examples | | ---------------- | ---------------------------------------------------------------------------- | --------------------------- | | API key or token | You paste a key created in the provider's console. | Datadog, Cloudflare, Linear | | OAuth | You sign in to the provider in the browser and grant access. | Sentry, Slack, Vercel | | App install | You install the Praxen app on your organization and pick what it can read. | GitHub | | CloudFormation | You deploy a stack that creates a read-only role in your account. | AWS | | Helm | You install an agent in the cluster. | Kubernetes | Each provider has its own page with setup steps, permissions and troubleshooting at `/integrations/`, for example [/integrations/cloudflare](https://docs.getpraxen.app/integrations/cloudflare). Providers that connect without a browser also carry a **Pipeline** tab there, with the exact API calls for a CI job. From the terminal, `praxen cloud connect` and `praxen integration connect` run the same flows. ## How disconnecting works Disconnect from **Settings > Integrations**, from the cloud account page, or with `praxen integration disconnect` and `praxen cloud disconnect`. Disconnecting stops every sync and check, deletes the credentials Praxen held, and removes what Praxen set up on the provider side wherever the provider's API allows it. Each integration page states exactly what is removed and what stays, and what stays is always something only you can remove. | Provider side | Removed on disconnect | Stays | | ------------- | ------------------------------- | ----------------------------------------------------------------------------------------- | | AWS | The CloudFormation stack | The IAM role, its policies and the CloudTrail S3 bucket, which the stack keeps on purpose | | Slack | The bot token, which is revoked | The Slack app installation and the channels Praxen created | | GitHub | The credentials Praxen held | Autofix branches and pull requests, the onboarding branch, and check runs on past commits | | Datadog | The webhook Praxen registered | The `@webhook-praxen` mention and the `praxen:managed` tag on your monitors | | Vercel | The credentials Praxen held | The Vercel integration configuration and the `praxen-*` drains | Deleting a workspace disconnects everything in it the same way, with one exception: the AWS CloudFormation stack is only deleted when you disconnect the account itself. Disconnect AWS accounts before deleting a workspace, or delete the stack in the AWS console afterwards. ## Catalog Open any integration for its tools, connect guide, and what disconnecting removes. :integrations-catalog ## Related - [Clouds](https://docs.getpraxen.app/connect/clouds) for what a connected cloud account gives you and how to read its page. - [Repositories](https://docs.getpraxen.app/connect/repositories) for what connecting GitHub unlocks. - [Work from your tools](https://docs.getpraxen.app/tools) to connect and manage integrations from your coding agent. # Clouds A cloud account gives agents the infrastructure behind your system. Praxen syncs its resources into the [topology](https://docs.getpraxen.app/connect/topology), records every change, and checks each resource on a schedule. ## What it does Connecting an account discovers the resources your credentials can see and adds them to the topology as nodes, with edges for how they relate. Accounts re-sync on their own; the account header shows a **Last synced** time and a **Sync with Cloud** action for when you cannot wait. Once the first sync completes, anomaly checks run against every resource at the pace its [tier](https://docs.getpraxen.app/connect/topology) sets, and [advisories](https://docs.getpraxen.app/detect/advisories) are computed from the topology as it fills in. These providers connect as cloud accounts: :integrations-catalog{category="cloud"} ## Connect an account ::steps{level="3"} ### Pick a provider Open **Settings > Clouds** in the [console](https://console.getpraxen.app) and choose **Connect a cloud account**. AWS deploys a CloudFormation stack that creates a role in your account and the page waits until the stack reports back; most other providers take an API token or sign you in through OAuth. Each provider page at `/integrations/` lists the exact credentials it needs, and from the terminal `praxen cloud connect` runs the same flow. If nothing in your environment clicks console links, cloud accounts also connect entirely over the API: every provider page that supports it has a **Pipeline** tab with the exact calls, starting with [/integrations/aws](https://docs.getpraxen.app/integrations/aws). ### Let the first sync finish The account header shows sync progress. Resources appear on the topology as they are discovered, and Praxen starts watching the account as soon as the first sync completes. ### Review what Praxen watches Open the account's **Settings** tab to confirm the check frequency and decide whether agents may write to the account. The tabs below show what the account page gives you from then on. :: ## Read-only by default Accounts start read-only: agents can call the provider's read endpoints, and any write call is refused with the reason. A workspace admin can turn **Read-only** off in the account's **Settings** tab, except for Kubernetes clusters connected through the agent, which stay read-only. Even with writes enabled, a direct provider write is held until you confirm it in the thread where you asked for it, and background runs nobody has written to stay read-only. ## Google Cloud API reads After connecting a Google Cloud project, ask the agent to inspect infrastructure, query Cloud Logging, read Cloud Monitoring time series or retrieve Cloud Trace records. The `gcpApi` tool uses the connection's short-lived reader identity. `gcpListApiOperations` lists supported operations and their input fields. The [Google Discovery format](https://developers.google.com/discovery/v1/using) supplies the operation bindings. Each call targets one connected project. The reader must have the operation's IAM permissions and the Google API must be enabled. These tools read configuration and telemetry; automatic checks and resource-page dashboards retain their existing coverage. Storage reads expose metadata, including object metadata, without object contents. Use `gcpGkeKubectl` for Kubernetes workloads, live pod logs and resource usage. ## The account page | Tab | What it shows | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Cloud Graph** | The account's slice of the topology, filterable by type. Select a node to open its resource page. | | **Problems** | The fix runs on [issues](https://docs.getpraxen.app/detect/issues) scoped to this account, one row per run with its severity and outcome, plus the account's recent check evaluations. | | **Alerts** | Automatic triage for the account's alerts: alerts that fire become issues and get a [fix run](https://docs.getpraxen.app/investigate/fix-runs) when confirmed. Shown for AWS, Cloudflare, Google Cloud, Vercel, Render, Supabase, Convex and Trigger.dev. AWS and Cloudflare also list each alert rule with its own switch. For Google Cloud, Cloud Monitoring sends alerts while **Investigate alerts** is on in **Settings**. | | **Signals** | The [signals](https://docs.getpraxen.app/detect/signals) that read this account's telemetry: each one with its operation and its role. Shown for AWS, Cloudflare, Vercel, Fly.io, Render, Supabase, Railway and Trigger.dev. | | **Repositories** | The source code behind the account's resources, matched from your connected [repositories](https://docs.getpraxen.app/connect/repositories) or added by you. Discovery needs a connected [GitHub](https://docs.getpraxen.app/integrations/github). | | **Settings** | Credentials, with **Verify** and **Rotate**; the **Read-only** switch; the anomaly check **Frequency**; **Re-classify tiers**; and provider-specific options such as AWS regions, Vercel telemetry, and monitoring for preview deployments. | | **Properties** | The raw account record. | ## Related - [Topology](https://docs.getpraxen.app/connect/topology) for how to read the graph the account fills in. - [Integrations](https://docs.getpraxen.app/connect/integrations) for connect methods and what disconnecting removes. - [Issues](https://docs.getpraxen.app/detect/issues) for what the scheduled checks raise. # Topology Topology is the live map of your infrastructure: every resource Praxen syncs is a node and every relationship is an edge. Agents read the same graph you navigate, so what you see is what they reason over. ## What it does Praxen builds the graph from every connected cloud account and repository and refreshes it on each sync. Resources link across providers by matching hostnames, DNS records and IP addresses, so a record in one provider that points at a service in another shows the real request path. Connected repositories are nodes in the same graph, joined to the resources they deploy by `deploys_to` edges. Every resource belongs to one of 13 categories, from Compute and Databases to Repositories and External Services. Each view colors by category and can filter by it. ## Views | View | What you see | | ---------- | -------------------------------------------------------------------------------------------------------- | | **Galaxy** | The default: every resource as a dot on a sphere, colored by category. Click a dot to open the resource. | | **Flow** | Resources and their relationships as a node-and-edge diagram. | | **Table** | A sortable list with the columns you pick. | Search matches names and ids exactly and fuzzily, so `paymnt` still finds `payment-api`. Filters narrow by provider, type, tier, category and environment, and the active view, search and filters are stored in the page URL, so a filtered view can be shared as a link. ## Resource detail Select any resource to open its panel. Advisories sit at the top, followed by these tabs: | Tab | What it shows | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Cloud Graph** | The resource within its architecture: what depends on it, what it depends on, or everything connected, from one hop up to 10. This is how you read the blast radius of a change. | | **Problems** | The fix runs on [issues](https://docs.getpraxen.app/detect/issues) detected on this resource, plus its recent check evaluations. | | **Settings** | Anomaly monitoring on or off, the tier with the reasoning behind it, and alternate names that help the agent match the resource when observability providers call it something else. | | **Properties** | The raw properties synced from the provider. | Every resource also has a fact sheet rendered from the graph: what it is and the resources it connects to within two hops, grouped by relationship. Agents read the same fact sheet when you attach a resource to a thread. ## Resource tiers Praxen ranks every resource by how much of your architecture depends on it. The tier sets how often anomaly checks run and how the resource's changes are handled. | Tier | Label | Description | Check frequency | Changes | | ---- | -------- | ------------------------------- | ---------------- | -------------------------- | | 1 | Critical | The architecture depends on it. | Every 30 minutes | Investigated | | 2 | Standard | An important resource. | Every 90 minutes | Investigated | | 3 | Low | Little depends on it. | Every 18 hours | Investigated | | 4 | Minimal | Almost nothing depends on it. | Every 3 days | Recorded, not investigated | The classification is automatic, and the **Settings** tab shows the model's reasoning and the data behind it: connected resources within 2 hops, direct dependents, a peer comparison, and metrics over the last 7 days. Pick a tier there when you know better, and set it back to **Automatic** at any time. ## Advisories on resources When Praxen finds a configuration or observability gap on a resource, an [advisory](https://docs.getpraxen.app/detect/advisories) appears at the top of its panel with the problem and the remediation. Each one offers a button that starts a thread: **Ask Praxen to fix it** when the agent can fix it in place, **Ask Praxen how to fix it** otherwise. ## Related - [Clouds](https://docs.getpraxen.app/connect/clouds) for connecting the accounts that fill the graph. - [Repositories](https://docs.getpraxen.app/connect/repositories) for how code joins the graph and what `deploys_to` means. - [Advisories](https://docs.getpraxen.app/detect/advisories) for the gaps Praxen flags on resources. - [Issues](https://docs.getpraxen.app/detect/issues) for what the tiered checks raise. # Repositories Connecting a repository gives agents your source code. Agents search and run it in a sandbox. Praxen assesses each pull request against production and places the repository on the [topology](https://docs.getpraxen.app/connect/topology) next to its deployed resources. ## What it does Agents clone the repository into a sandbox and search it with `rg`. A function name, an error message or a route points to its exact lines. Agents read files and commits through GitHub. They also run repository code in the sandbox when an investigation calls for it. Every pull request gets an impact assessment against the production topology and a pass or fail comment. On the topology, the repository is a node joined by `deploys_to` edges to the resources it deploys and by `defines` edges to the resources its configuration provisions. When an agent investigates an issue on a service, it follows these edges straight to the code that ships there. ## Connect a repository Open **Settings > Repositories** in the [console](https://console.getpraxen.app) and choose **Add repository**. If GitHub is not connected yet, this installs the Praxen GitHub app on your organization and lets you pick which repositories Praxen can read. If it is already connected, it opens the app's settings on GitHub, where you add more repositories. Connected repositories stay in sync as code changes. See [GitHub](https://docs.getpraxen.app/integrations/github) for app permissions. ## The repository page | Tab | What it does | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Settings** | Autofix, impact assessment and sandbox network settings for this repository, described below. | | **Observability** | Praxen reviews the repository after each sync and reports how well its code is instrumented: how many route handlers emit telemetry and which produce none. Each finding can be handed to an agent with **Ask Praxen to fix it**. | | **Changes** | The history of [impact assessments](https://docs.getpraxen.app/detect/pull-request-reviews) for this repository. Each assessment checks the production topology and returns a pass or fail verdict. | | **Resources** | The cloud resources this repository manages. Praxen links them from deploy manifests and provider metadata. Add any resource it cannot detect with **Link resource**. Assessments focus on these resources and use the whole cloud account until you link them. | | **Properties** | The raw repository record. | ## Repository settings | Setting | What it controls | | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Open autofix pull requests** | Whether Praxen turns confirmed findings into pull requests on this repository. Turning it off stops new ones; existing pull requests stay open. | | **Assess pull requests for production impact** | Whether every pull request gets an assessment against the production topology and a verdict comment. | | **Impact assessment instructions** | Repository guidance, such as deploy-critical paths and concerns that other checks cover. The agent reads it from `preferences/repositories//.md` in workspace memory. | | **Block merging on production concerns** | Posts the **Praxen production impact** check for each assessed pull request. The check fails when an assessment finds a concern. Require it in branch protection to block merging. It is on by default. | ## Related - [Impact assessments](https://docs.getpraxen.app/detect/pull-request-reviews) for what Praxen checks and how the verdict reads. - [Topology](https://docs.getpraxen.app/connect/topology) for the graph the repository joins. - [Autofix](https://docs.getpraxen.app/investigate/autofix) for the pull requests Praxen opens against connected repositories. - [GitHub](https://docs.getpraxen.app/integrations/github) for app permissions and what disconnecting removes. # Memories Praxen keeps workspace memory as markdown files in a git repository, one repository per workspace. Agents read it and write to it, and so can you. ## What it does Memory records confirmed findings about your system: a failure mode, a recurring pattern, or an operational fact backed by evidence. When an investigation confirms a root cause, the agent writes it to a file, so the next agent starts from it and does not find it again. Agents do not store preferences, unverified claims, or configuration already visible in the [topology](https://docs.getpraxen.app/connect/topology). ## How the repository is laid out | Path | Written by | What it holds | | -------------------- | -------------------- | --------------------------------------------------------------------------- | | `MEMORY.md` | Praxen, each night | The index of what is known about the workspace. | | `daily/` | Praxen, each night | One note for each day, with the patterns and signals of that day's threads. | | `preferences/` | You | Files you edit to tell agents how your team works. | | Other markdown files | Agents | One finding in each file, with the resource and the date in each entry. | Each file starts with one line that says what it covers. ## How memory reaches a thread `MEMORY.md` and the three most recent daily notes appear in the briefing of every new thread. They show the state as of the nightly update. Agents clone the repository into the thread sandbox the first time the sandbox is used, and read it with `grep` or `rg` for anything the briefing does not show. Files saved after the nightly update are in the repository when the agent looks. When a turn ends, Praxen commits and pushes what the agent changed. If two changes conflict, the agent opens the files that Praxen names, keeps every fact that is still true, and removes the conflict markers. ## Edit memory yourself Edit files under `preferences/` to give agents standing guidance. Praxen rewrites `MEMORY.md` and writes the `daily/` notes each night, so do not edit those. To record a finding from a thread, ask in plain words: "Save a note: checkout-api integration tests fail intermittently because the payment vendor's sandbox times out under parallel load, confirmed from pipeline logs showing 504 responses." ## Related - [Threads](https://docs.getpraxen.app/investigate/threads) for where agents read and write memory. - [Fix runs](https://docs.getpraxen.app/investigate/fix-runs) for the investigations that produce confirmed findings. - [Topology](https://docs.getpraxen.app/connect/topology) for what agents read from the graph instead of memory. # Detect Once your stack is [connected](https://docs.getpraxen.app/connect), Praxen watches it and tells you what needs attention. You don't write alert rules or tune thresholds: agents read the telemetry and decide. Checks are built for every connected cloud account and observability integration, from the provider's signals and the dashboards and saved reports you keep there. Each check knows which direction is worse for its metric, so an improvement never raises an issue, and a statistical pass and an agent decide together whether a signal is a real problem. Every evaluation is recorded against the resource, and on the Free plan checks pause after 10 days without anyone using the workspace and resume when someone opens it ([Inactive workspaces](https://docs.getpraxen.app/administration/billing-and-usage#inactive-workspaces)). ::card-group :::card --- icon: i-lucide-siren title: Issues to: https://docs.getpraxen.app/detect/issues --- Every problem Praxen detects or receives from your alerting becomes one issue, worked by one fix run. ::: :::card --- icon: i-lucide-git-pull-request title: Impact assessments to: https://docs.getpraxen.app/detect/pull-request-reviews --- Every pull request in a connected repository gets an impact assessment against its production resources, with one pass or fail comment. ::: :::card --- icon: i-lucide-lightbulb title: Advisories to: https://docs.getpraxen.app/detect/advisories --- Per-resource recommendations for misconfiguration, resilience risks and observability gaps, each with a fix an agent can apply. ::: :::card --- icon: i-lucide-activity title: Signals to: https://docs.getpraxen.app/detect/signals --- Queries that watch what each of your services does, written every day from your code and telemetry, with an issue when one changes for the worse. ::: :: ## Related - [Connect](https://docs.getpraxen.app/connect) for the cloud accounts, integrations and repositories detection runs on. - [Investigate and fix](https://docs.getpraxen.app/investigate) for the fix run that works each issue to a verdict and a pull request. - [Billing and usage](https://docs.getpraxen.app/administration/billing-and-usage) for what the Free plan includes and when a workspace pauses. # Issues An issue is the single record of a problem: something Praxen's own checks found, or an alert a connected tool sent. The record keeps score (fingerprint, occurrences, verdict, severity); the fix run [thread](https://docs.getpraxen.app/investigate/threads) that works it is where you read what happened. ## What it does Every detection runs through one lifecycle, whatever its source: Praxen records an Issue, a fix run reaches a verdict, a confirmed Issue gets a fix, and the Issue resolves when the problem ends. There is no raw alert queue to triage by hand. Duplicates fold into the Issue that already exists, so one problem has one record with its fix-run history. ## Where issues come from | Source | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Praxen checks | Checks on connected resources and cloud accounts evaluate metrics, logs and traces, and record an issue when one finds a real problem. | | Signals | A [signal](https://docs.getpraxen.app/detect/signals) that watches one operation of your application changes for the worse. The issue belongs to the cloud account or integration that answers the signal. | | Provider alerts | Alerts from connected observability tools and cloud accounts become issues, so everything that might need attention runs through one lifecycle. See [Integrations](https://docs.getpraxen.app/connect/integrations). | | Opened from a thread | Hand a problem off in a chat thread and the agent opens the issue for you, which starts its fix run. | ## How it works 1. A finding is recorded with a fingerprint built from its source: the resource and check for Praxen detections, the integration and alert id for provider alerts. A firing that matches an open issue increments its occurrence count instead of creating a duplicate. 2. A [fix run](https://docs.getpraxen.app/investigate/fix-runs) reads the raw payload, the query behind the alert, recent metrics and your code, then records one of two verdicts: `confirmed` (a real problem) or `dismissed` (noise or expected behavior). A finding that belongs to an issue already open, or one resolved recently, joins that issue instead. 3. A confirmed issue is worked to a fix in the same thread, unless the workspace's severity floor or plan limit holds it for a person to start. Severity is one of `critical`, `high`, `medium`, `low` or `info`, and the run can regrade it once it has read the evidence. 4. The issue resolves when the problem is over: a recovery from the provider, a later check that comes back clean, or an alert that stays quiet. You can also mark one **Resolved** yourself. If the same problem returns within 24 hours (longer for issues that name a code defect), the existing issue reopens and its fix run takes a fresh look. ## Statuses | Status | Description | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `new` | Recorded, no fix run yet. | | `triaging` | The fix run is reading the evidence and has not reached a verdict. | | `confirmed` | A real problem. The Issue remains the same record; the run works it to a fix unless it is held for a person. | | `dismissed` | Not a problem. Kept so the same signal folds quietly next time. | | `skipped` | No fix run started, for example because the signature is suppressed in workspace settings. | | `failed` | The run never reached a verdict. Shown as **Not triaged** when no run started because the plan's daily automatic fix runs were used or the workspace was out of credits; **Investigate** starts it. | An issue also carries `resolvedAt` once the problem is over, whichever status it holds. ## Where to find it Open **Issues** in the [console](https://console.getpraxen.app) to browse detections, filter by severity or status, and find active or held issues. Each issue has a page with its evidence, investigation, timeline and properties. Use **Investigate** to start a run, or **Open thread** to continue the conversation. The API's `_html_url` field links directly to this page, including for issues without a run. Under **Threads**, the **Fix runs** preset lists the agent conversations. The run's last message is its outcome: a pull request, no fix needed, or something that needs you. The thread's sidebar opens the evidence and any [escalation](https://docs.getpraxen.app/investigate/escalations), with **Open full page** to view the record. Every cloud account, integration and topology resource has a **Problems** tab listing the fix runs on that scope. An issue that never got a run appears in the Issues list; open it and use **Investigate** to start one. From scripts, the issue is a first-class object in the [API reference](https://api.getpraxen.app/v1/reference), read with the `issues:read` scope and edited with `issues:write`. ## Related - [Fix runs](https://docs.getpraxen.app/investigate/fix-runs) for how a run reaches its verdict and works a confirmed issue. - [Threads](https://docs.getpraxen.app/investigate/threads) for reading a transcript and its evidence. - [Escalations](https://docs.getpraxen.app/investigate/escalations) for what happens when the agent needs you. - [Clouds](https://docs.getpraxen.app/connect/clouds) for the accounts and resources issues are scoped to. # Pull request impact assessments Most issues start with a change. Praxen runs an impact assessment for each pull request in a connected repository. It checks the production resources that repository deploys to and posts a pass or fail comment. See [repositories](https://docs.getpraxen.app/connect/repositories) to connect a code host. ## What it does An agent checks the diff against live metrics, logs, and open issues for the affected resources. You get one comment on the pull request, an optional **Praxen production impact** check, and a thread in the console with the analysis. ## How it works 1. A pull request against the default branch gets an assessment when a member opens it or pushes to it. A draft gets an assessment when a member marks it ready. 2. A later push replaces the assessment in progress, so only the latest commit gets a verdict. 3. A change with no production effect can pass without a resource investigation. 4. Praxen follows the repository's deploy edges to its production resources. If none exist, it checks the change against all cloud accounts in the workspace. 5. The agent investigates in a [thread](https://docs.getpraxen.app/investigate/threads) and records a `pass` or `fail` verdict. 6. Praxen edits one comment after each assessment. A fail says **Hold this merge** and shows the impact level and finding. A pass says **This change is unlikely to harm production**. It can also say if a fix for a detected issue can resolve it. A later push that addresses a concern changes the comment to a pass. The agent can also suggest observability improvements in one batch. Those suggestions do not affect the verdict. ## Act on an assessment Mention `@praxen` in a pull request comment. Praxen answers in the same conversation. Non-members get an access note. | You ask for | What happens | | ------------------ | --------------------------------------------------------------------------------------------- | | A question | The agent answers from the assessment thread with its evidence. | | Another assessment | The agent assesses the latest push again and reconsiders the verdict. | | A fix | Praxen starts a fix run and opens a stacked pull request against the pull request's branch. | The repository's **Changes** tab lists each assessment. A fail offers **Fix with Praxen**, which starts the same fix run, and **Dismiss** when the concern does not apply. A dismissed assessment gets no new comments until a member selects **Restore**. | Status | Description | | ------------- | ------------------------------------------------------------------------- | | Assessing | Praxen checks the latest push. | | Concern found | The assessment found a production concern. | | Passed | The assessment found no production concern. | | Resolved | A later push addressed the concern. | | Dismissed | A member dismissed the assessment. The pull request gets no new comments. | ## Configure Impact assessments run for every connected repository. Use **Settings > Impact assessments** to turn them off across the workspace. This page also controls whether pull request viewers can open assessment threads. Find repository fields under **Settings > Repositories > Settings**. | Field | Description | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Assess pull requests for production impact** | Turns assessments off for this repository only. | | **Impact assessment instructions** | A markdown file in workspace memory at `preferences/repositories//.md`. The agent reads it for repository-specific guidance, such as deploy-critical paths and concerns that other checks cover. | | **Block merging on production concerns** | Posts the **Praxen production impact** check for each assessed pull request. It fails when the assessment finds a concern. Require it in branch protection to block merging. On by default. | The check also completes on merge queue commits. Praxen assessed the pull request before it entered the queue. A fail verdict can send the **Production Concern Found** email. This email is off by default under [Notifications](https://docs.getpraxen.app/administration/notifications). ## Plan notes Each plan includes a monthly number of impact assessments. The Free plan's monthly limit appears on [Billing and usage](https://docs.getpraxen.app/administration/billing-and-usage). Members get an email as the included impact assessments run low. After they run out, the console records **Production impact not verified**. Praxen posts no result to GitHub. ## Related - [Repositories](https://docs.getpraxen.app/connect/repositories) to connect a repository and link its resources. - [Fix runs](https://docs.getpraxen.app/investigate/fix-runs) for how an investigation reaches its verdict. - [Autofix](https://docs.getpraxen.app/investigate/autofix) for the pull requests a fix run opens. - [Notifications](https://docs.getpraxen.app/administration/notifications) for the email an assessment can send. # Advisories Advisories are recommendations attached to individual resources in your [topology](https://docs.getpraxen.app/connect/topology). Each one names the problem, explains why it matters, and states the fix. ## What it does Praxen derives advisories from each resource's configuration, its recent activity, and the quality of the telemetry it emits. Every advisory carries three attributes. | Attribute | Values | Description | | ---------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | Category | observability, resilience, security, data protection, lifecycle | What kind of risk the advisory describes. | | Severity | warning, info | Warnings lead wherever advisories are listed. | | Fixability | in place, guidance | In place: an agent can change the setting through a provider API call. Guidance: the fix needs a recreate or manual steps. | Some examples: | Resource | Advisory | Category | Fixability | | ------------------- | ------------------------------------ | --------------- | ---------- | | Cloudflare Worker | Logs are disabled | observability | in place | | Amazon RDS database | Automated backups are disabled | resilience | in place | | Amazon S3 bucket | Public access is not fully blocked | security | in place | | Amazon RDS database | Storage is not encrypted | data protection | guidance | | AWS target group | Health checks are disabled | resilience | in place | | Any resource | Serving traffic but emitting no logs | observability | guidance | Telemetry-quality advisories such as "Serving traffic but emitting no logs" fire only after the condition persists across three consecutive checks. They stay silent while a configuration advisory already names the root cause: if logging is disabled on a Worker, you see that advisory, not the symptom on top of it. Lifecycle advisories come from the same activity metrics that assign [resource tiers](https://docs.getpraxen.app/connect/topology). ## Where to find it Open a resource in the topology and its active advisories appear in the node panel, one at a time, warnings first, with a counter to step through the rest. The **Advisories** page in the [console](https://console.getpraxen.app) shows the workspace-wide rollup: advisories grouped by rule with the count of affected resources, plus how many resources can be monitored, how many sit at the Minimal tier, and how many have an open observability advisory. Repositories carry advisories too and appear in the same rollup. ## Fix or ignore one Every advisory has a button that starts a [thread](https://docs.getpraxen.app/investigate/threads) about it, opened with the resource linked and the advisory's message and remediation as the first prompt. **Ask Praxen to fix it** appears on advisories fixable in place and asks the agent to apply the fix or walk you through it; **Ask Praxen how to fix it** appears on guidance advisories and asks for remediation steps. Click **Ignore** to dismiss an advisory on one resource. The dismissal records who ignored it and when, and the advisory leaves the node panel and the rollup for an Ignored list on the node, where **Restore** brings it back. Dismissals prune themselves once the underlying condition clears, so if the same problem returns the advisory fires again instead of staying silently ignored. ## Related - [Topology](https://docs.getpraxen.app/connect/topology) for the resources advisories attach to and how tiers are assigned. - [Threads](https://docs.getpraxen.app/investigate/threads) for the conversation a fix button starts. - [Detect](https://docs.getpraxen.app/detect) for the other ways Praxen surfaces what needs attention. # Signals A signal is one query on one of your cloud accounts or integrations that watches one operation of your application: a request route, a job, a queue consumer, a model call, a named step. It counts the failures, the successes, the volume or the latency of that operation, in the telemetry that the connection really carries. Signals show you whether each part of your application does its work. ## What it does Praxen reviews the cloud accounts and integrations of your workspace every day. Each team instruments its code in its own way, so Praxen learns the conventions of each connection before it writes a query: 1. It reads the code in your repositories: the entry points, and how the code logs, traces and counts. 2. It reads samples of real events and spans from the connection. 3. It records a profile of the telemetry: how the code is instrumented, the keys that name an event, the keys that tell success from failure, and the keys that narrow events to one operation. When your team calls its event field `action`, the profile says `action`. 4. It writes the signals of the connection with those keys, in the query language of the provider. | Role | What the signal measures | | ------- | ---------------------------------------------- | | Failure | The failures of one operation. | | Success | The success rate of one operation. | | Volume | The requests or runs of one operation. | | Latency | A percentile of the duration of one operation. | Praxen runs every query before it keeps it, so a signal is only kept when it returns real data. A signal must name a key or an event from the profile, so each signal watches one operation and not all the telemetry of the connection. A connection has at most 120 signals. Each signal runs on the check frequency of its connection, with the same baselines and checks as the rest of [detection](https://docs.getpraxen.app/detect). When a signal changes for the worse, Praxen opens an [issue](https://docs.getpraxen.app/detect/issues) on that cloud account or integration, and its fix run gets the operation and the query. When the telemetry of a connection cannot see the operations of your application, Praxen writes no signal for it. The discovery thread says what is missing, for example "the logs contain only request lines with no route or status". ## Signals from earlier Issues Praxen also reads confirmed Issues from the last 30 days. When a connection query can identify an Issue's cause, Praxen writes a signal for it. A signal links to its source Issue. Praxen can detect the same problem early if it returns. ## When it runs Discovery runs once a day. Your first run starts when you connect the first cloud account or integration that can answer signals. Each run reviews up to 12 connections, starting with the connections that have the fewest signals. The next daily run continues with the others. To start a run immediately, for example after you connect something new, select **Discover now** on the Signals page. A run takes some time, and the page shows when the run started. You can start a new run 30 minutes after the last one. Praxen keeps a signal while its query is the same, so its baseline continues from one run to the next. ## Where to find it - **Signals** in the console sidebar lists the signals of the workspace with their connection, operation, role and origin. Select a signal to see its query and why it matters. - The **Signals** tab on a [cloud account](https://docs.getpraxen.app/connect/clouds) or integration page lists the signals that read the telemetry of that connection. - Each discovery run opens one [thread](https://docs.getpraxen.app/investigate/threads) for each cloud account or integration it reviews, named `Signals: `, so you can read what Praxen checked for that connection. - Agents read the same signals in any thread, so you can ask which signals watch a failing operation. Signals come from AWS, Cloudflare, Vercel, Fly.io, Render, Supabase, Railway and Trigger.dev accounts, and from Datadog, Sentry, Honeycomb, Axiom, Mixpanel, PostHog, Grafana, Logfire, LangSmith, Braintrust and New Relic integrations. Discovery uses only the connections that every member of the workspace can see. A connection with anomaly checks turned off is not used. ## Related - [Issues](https://docs.getpraxen.app/detect/issues) for what happens when a signal changes for the worse. - [Billing and usage](https://docs.getpraxen.app/administration/billing-and-usage) for when background work, signal discovery included, pauses on a Free workspace. # Investigate and fix [Connect](https://docs.getpraxen.app/connect) is what Praxen sees and [Detect](https://docs.getpraxen.app/detect) is what it spots. Investigating is where an agent works the problem with your observability tools, your code and the topology, and writes up what it found. Every tool call and result is stored in the thread, and answers cite their sources, so you can check any number the agent puts in front of you. Threads are the surface. A fix run works one issue from verdict to pull request, an escalation records what only a person can do, and an autofix is the pull request that lands in your repository. ::card-group :::card --- icon: i-lucide-messages-square title: Threads to: https://docs.getpraxen.app/investigate/threads --- Every agent run, from the console, Slack, the CLI or the API. Watch it, stop it, share it and continue it. ::: :::card --- icon: i-lucide-radio-tower title: Fix runs to: https://docs.getpraxen.app/investigate/fix-runs --- One agent per issue reaches the verdict, traces the cause and opens the pull request, in a single thread. ::: :::card --- icon: i-lucide-hand title: Escalations to: https://docs.getpraxen.app/investigate/escalations --- The one list of what agents need from you: one record per ask, cleared when you handle it. ::: :::card --- icon: i-lucide-git-pull-request title: Autofix to: https://docs.getpraxen.app/investigate/autofix --- Agent-written fixes arrive as pull requests in your repository. You review and merge. ::: :: ## Related - [Detect](https://docs.getpraxen.app/detect) for the checks and alerts that start a fix run. - [Work from your tools](https://docs.getpraxen.app/tools) for reaching the same agent from your coding agent, the CLI and Slack. # Threads A thread is a conversation with an agent, and every agent run happens inside one. Whether you asked a question or a check fired, you get the same page: the streamed answer, every tool call and result, and the artifacts the agent produced. ## What it does Responses stream live and every tool call lands in the transcript as it happens, so you follow the work instead of waiting for a summary. Answers carry numbered reference badges; hover one to see the source and what it says, and the tool result behind it holds the raw data. Agents also produce artifacts alongside the conversation, such as reports, diagrams and pull requests, listed in the thread's artifacts panel. Agents can hand part of the work to sub-agents, whose threads nest under the parent. Every thread records where it started: the console, Slack, the CLI, the API, MCP, the browser extension, GitHub or email. ## Thread types | Type | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chat` | A conversation you start to ask a question or explore a problem. | | `fix_run` | The agent working one [issue](https://docs.getpraxen.app/detect/issues) from verdict to pull request. See [Fix runs](https://docs.getpraxen.app/investigate/fix-runs). | | `exploration` | An unattended sweep of a cloud account or integration that records findings and may open an issue. | | `pr_review` | An agent assessing a pull request's impact against your infrastructure. | | `signal_discovery` | The daily run that reviews your cloud accounts and integrations and writes the [signals](https://docs.getpraxen.app/detect/signals) that watch the operations of your application. | ## Start a thread In the [console](https://console.getpraxen.app), open **Threads**, click **New thread** and type what you want to know, for example "Which services call our production database, and which of them deployed in the last 24 hours?". From a terminal, `praxen thread ask` starts a thread and waits for the reply: ```bash [Terminal] praxen thread ask "why did p99 latency on api-gateway rise since 14:20 UTC?" ``` Scripts and integrations create threads with `POST /v1/threads`, documented in the [API reference](https://api.getpraxen.app/v1/reference). ## From Slack Mention Praxen in a channel it is in and the answer arrives in a Slack thread under your message. Replies in that Slack thread continue the same Praxen thread, which also appears under **Threads** in the console for your workspace. A direct message to Praxen works the same way. After a mention, Praxen reads the rest of that Slack thread and answers only the messages meant for it, and telling it to leave the conversation mutes it there until someone mentions it again. ## Where to find it **Threads** lists every thread with the presets **All**, **Mine**, **Running** and **Needs you**, the last one for threads whose run is waiting on a person. While a run is streaming, a stop button replaces the send button; click it to cancel the turn. When an agent wants to make a write call against a cloud account that requires confirmation, the run pauses and shows you the exact call. Approve it, or reject it with an optional note the agent reads before continuing. ## Sharing Threads are private by default. **Share thread** changes the **Visibility** to your workspace, a team or public, and **Copy** puts the link on your clipboard. From a terminal, `praxen thread export` writes the transcript to a file. ## Related - [Fix runs](https://docs.getpraxen.app/investigate/fix-runs) for the thread type that works an issue to a pull request. - [Escalations](https://docs.getpraxen.app/investigate/escalations) for what a thread waiting on you is asking. - [Memories](https://docs.getpraxen.app/connect/memories) for what agents carry from one thread to the next. - [CLI](https://docs.getpraxen.app/tools/cli) for driving threads from scripts and coding agents. # Fix runs A fix run is the agent working one [issue](https://docs.getpraxen.app/detect/issues). Each issue gets at most one: a [thread](https://docs.getpraxen.app/investigate/threads) of type `fix_run` that reaches the verdict and, on a confirmed problem, keeps working it to a fix in the same conversation. ## What it does The thread is where you read the whole story: the work as it happens, the evidence one click away in its lineage, and the outcome at the end. The run reads the alert or finding, the query behind it, recent metrics and logs around the firing, recent changes and your code. Before it acts, it writes the causal chain in the thread: the signal, the mechanism, the component and code path that produce it, the trigger and the blast radius, each link backed by named evidence or marked as unknown. ## How it works 1. A run starts when a check or a connected alert produces a finding, when an agent in a chat thread opens an issue from the problem you are discussing, or when you choose **Investigate** on an issue. 2. The agent reads the evidence and reaches one of two verdicts, `confirmed` or `dismissed`. A finding that matches an existing issue joins it instead of starting a second run. 3. On a confirmed problem, the same agent traces the cause and writes the causal chain. 4. When a code change fixes the cause in a connected repository, the run opens the pull request through [autofix](https://docs.getpraxen.app/investigate/autofix). When no pull request can fix it, the run raises an [escalation](https://docs.getpraxen.app/investigate/escalations) that names what a person has to do. 5. Every step lands on the issue's activity timeline, next to detections, re-detections and your own notes. ## Outcomes After each agent turn, Praxen classifies the run. | Outcome | Description | | ---------------- | ----------------------------------------------------------- | | `resolved` | Root cause found and the problem is fixed or has recovered. | | `diagnosed` | Root cause found, but the fix has not landed. | | `inconclusive` | The agent could not settle on a cause. | | `false_positive` | The finding did not point at a real problem. | | `failed` | The run ended on an error. | A run can also park, which stops monitoring from nudging it to re-investigate until the issue resolves. | Parked state | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------- | | `needs_human_action` | The fix requires something only you can do. | | `needs_decision` | The agent needs a call from you before continuing. | | `awaiting_change` | The agent is waiting for a fix to ship, for example a pull request awaiting review. This state parks quietly. | | `failed` | The run hit an error it could not work around. | The three states that need a person are recorded as escalations, shown on the outcome card in the thread and listed under the **Needs you** preset, so the same ask never notifies you twice. ## Where to find it Fix runs appear under **Threads** alongside chat threads, and the **Needs you** preset lists the ones waiting on a person. The **Lineage** in the thread's sidebar holds the record behind the run: **Issue** opens the evidence and the issue's timeline, **Escalation** opens what the agent asked of you with **Mark as handled**, and **Check** opens the evaluation that detected the problem. The issue's menu carries **Investigate**, **Investigate again**, **View investigation** and **View triggering check**. ## Configure Under **Settings > Workspace**, the **Investigations** card sets **Investigate automatically from**: the lowest severity that starts a fix run on its own. Issues below it keep their verdict and are held, and their thread offers **Start investigation** so someone on your team can pick them up. Verdicts are never held: every confirmed issue is visibly confirmed, and the floor only defers the work that follows. ## Related - [Issues](https://docs.getpraxen.app/detect/issues) for the record every fix run works. - [Threads](https://docs.getpraxen.app/investigate/threads) for reading, stopping and sharing the run. - [Escalations](https://docs.getpraxen.app/investigate/escalations) for the asks a parked run raises. - [Autofix](https://docs.getpraxen.app/investigate/autofix) for the pull request a run opens. # Escalations An escalation is a record of something that needs a person. When a [fix run](https://docs.getpraxen.app/investigate/fix-runs) parks needing you, Praxen records the ask once and tells you once, however many runs hit the same wall. ## What it does Each escalation carries a kind, a headline that says what is wrong and what you need to do, and a few sentences of detail. A second fix run blocked on the same remediation folds into the open escalation instead of notifying again: the count goes up and the latest thread joins its references. An escalation raised against an issue also lands on that issue's activity timeline. ## Where escalations come from | Kind | Label | Description | | -------------------- | ---------------------- | -------------------------------------------------- | | `needs_human_action` | Needs your action | The fix requires something only you can do. | | `needs_decision` | Awaiting your decision | The agent needs a call from you before continuing. | | `failed` | Agent stuck | The run hit an error it could not work around. | ## How it works 1. A fix run parks on one of the kinds above and raises the ask. 2. Praxen matches it against the open escalations, exactly when the source supplies a key and otherwise by text similarity, and folds it into a match. 3. A first record notifies you once; a folded one stays quiet. 4. **Mark as handled** clears the record, and so does the issue resolving. A request to confirm that an issue needs no fix closes on its own a week after its latest occurrence, so the list keeps only current asks. A cleared escalation stops absorbing repeats, so a recurrence notifies again; **Reopen** on the same card, or over the API, puts it back if the ask was not actually done. 5. Matching lapses 24 hours after the last occurrence, so a problem that persists speaks up again. You can also create escalations over the API to put your own asks on the same list. Listing needs an API key with the `analytics:read` scope and writing needs `issues:write`; see the [API reference](https://api.getpraxen.app/v1/reference). ## Where to find it Open **Escalations** in the console to see outstanding requests. Search the list or switch to **Handled** or **All** to find earlier requests. Each escalation has a page with its full description, originating issues and threads, lineage and occurrence history. Use **Mark as handled** when the request is complete, or **Reopen** if it still needs attention. The API's `_html_url` field links directly to this page, including for escalations without a thread. When Praxen raises an escalation, it grades how urgent it is: critical, high, medium or low. Under **Settings > Workspace > Escalations**, choose the severities that alert right away (critical only by default). Each one posts a message in your Slack notifications channel and emails workspace owners and admins. With incident.io connected, the integration's **Send escalations at or above** setting compares against the same severity. Once a day, members also get an email that lists the open escalations raised or seen again in the last 24 hours, the most critical first, each with a link to its page. A day with no open escalations sends nothing. Turn it off with **Daily Escalations** in **Settings > Notifications**. An escalation also appears on the thread that raised it. The run's outcome card opens the ask, with **Open full page** for the complete record. Under **Threads**, the **Needs you** preset lists every thread whose run is waiting on a person. ## Related - [Fix runs](https://docs.getpraxen.app/investigate/fix-runs) for the parked outcomes that raise escalations. - [Threads](https://docs.getpraxen.app/investigate/threads) for the Needs you preset and the run page. - [Issues](https://docs.getpraxen.app/detect/issues) for the records escalations point back to. - [Notifications](https://docs.getpraxen.app/administration/notifications) for the email settings behind what Praxen sends you. # Autofix An autofix is a pull request Praxen opens to resolve something it found. The agent investigates first, then writes the change on a branch and opens the pull request on GitHub; the merge is yours. ## What it does Autofixes start from three places. You ask for one in a [thread](https://docs.getpraxen.app/investigate/threads), for example "open a pull request that fixes this". A [fix run](https://docs.getpraxen.app/investigate/fix-runs) lands on a confirmed cause in a connected repository and opens the fix in the same thread. Or Praxen proposes one on its own, such as the observability improvements it drafts when a repository is first connected. ## How it works 1. **Investigate**: the agent gathers context from the topology, telemetry and the affected [repository](https://docs.getpraxen.app/connect/repositories). 2. **Branch**: it creates a branch against the repository's base branch. 3. **Fix**: the executor writes the change and pushes commits. 4. **Pull request**: it opens the pull request describing what was wrong and what changed, linked to the thread or issue behind it. 5. **Your checks**: your team and continuous integration decide whether to merge. Closing the pull request is valid, and Praxen records it. ## Statuses | Status | Description | | ------------------- | ------------------------------------------------------------------------------------------------------ | | `started` | The run is under way. | | `branch_pushed` | Commits are on the branch and the pull request is about to open. | | `pr_opened` | The pull request is open and waiting on your review. | | `merged` | You merged the pull request. | | `closed` | The pull request was closed without merging, by you or by Praxen. | | `failed` | The executor could not produce a fix. | | `no_fix_needed` | The agent concluded there was nothing to change. | | `already_in_flight` | Another run or an open pull request already covers the same fix. | | `quota_exhausted` | The workspace cannot start another run right now. | | `disabled` | Autofix is turned off for the workspace. | | `plan_rejected` | The request was rejected before a run started. | | `unreachable` | Praxen can no longer read the repository, for example after the GitHub App was removed or suspended. | | `expired` | The run stalled past its time window and was closed out. | A skipped run can be started from its overview with **Run anyway**, and an expired or failed one with **Run again**. Under **Settings > Workspace**, the **Autofix** card holds the **Open autofix pull requests** switch for the whole workspace. ## Pull requests left open A pull request Praxen opens does not wait forever. After a week without activity, the weekly sweep sends one reminder by email and in Slack and leaves the same note as a comment on the pull request; when nobody has been asked to review it, the owners of the code it touches are asked. A pull request that sees nothing for another week after the reminder is closed by Praxen with a comment explaining why, and the branch stays, so reopening brings the change back as it stands. Pull requests opened while a repository is being connected are left out of reminders and closures. ## Executors The executor is the coding agent that writes the diff. Praxen's own executor needs no setup; you can route autofixes through a coding agent you already use instead: :autofix-executors Connect Devin, Cursor, Factory, Conductor, Capy or Amp under **Settings > Integrations** with your own API key or access token, then turn on **Use Devin for all autofixes** (or the equivalent switch on the Cursor, Factory, Conductor, Capy or Amp page) to make it the executor for every autofix in the workspace. If that integration is removed or disabled, autofixes fall back to the Praxen executor. ## Where to find it Read an autofix on the thread that produced it. The **Lineage** in the thread's sidebar shows the **Autofix** and its **Pull request**, and the autofix node opens **Overview**, **Diff**, **Session**, **Timeline** and **Properties** tabs. **Run anyway**, **Run again** and the close reason live on its overview. ## Related - [Fix runs](https://docs.getpraxen.app/investigate/fix-runs) for the runs that hand a confirmed cause to autofix. - [Impact assessments](https://docs.getpraxen.app/detect/pull-request-reviews) for the production check on each pull request. - [Repositories](https://docs.getpraxen.app/connect/repositories) for connecting the code autofixes write to. - [GitHub](https://docs.getpraxen.app/integrations/github) for the code host connection autofixes write through. # Work from your tools Your coding agent can see what Praxen sees: telemetry across every connected provider, the topology, code and issues. Once connected, it answers questions like "what errored in production for the service this branch deploys, in the last hour?" without you leaving the editor. ::card-group :::card --- icon: i-lucide-puzzle title: Plugins to: https://docs.getpraxen.app/tools/plugins --- One install for Claude Code, Cursor or Codex: both MCP servers, the skills and the slash commands your agent needs. ::: :::card --- icon: i-lucide-plug title: Platform MCP server to: https://docs.getpraxen.app/tools/platform-mcp --- One Model Context Protocol endpoint for any MCP client. Sign in through the browser, or use an API key where there is none. ::: :::card --- icon: i-lucide-terminal title: CLI to: https://docs.getpraxen.app/tools/cli --- The `praxen` command for terminals, scripts and CI. Text in a terminal, JSON when piped, and the full API behind `praxen api`. ::: :: ## Reads by default, writes behind a gate Agent tools are read-only by default on the MCP server and the CLI: telemetry queries, topology traversal and GitHub reads work with no extra setup. On the MCP server, writes to provider resources unlock when the session sends the `x-praxen-allow-writes: true` header with a credential that carries the `agent_tools:write` scope; on the CLI, pass `--write` to `praxen tools run` or `praxen tools code`. A safety model screens every write, and clients that support confirmation prompts ask you to approve each one before it runs. ## Related - [Quickstart](https://docs.getpraxen.app/getting-started): the first connection, by hand or from inside your coding agent. - [API keys and OAuth](https://docs.getpraxen.app/administration/api-keys-and-oauth): scopes, key management and OAuth clients for headless setups. - [Docs MCP server](https://docs.getpraxen.app/reference/mcp): let your agent search and read these docs. # Platform MCP server Praxen runs a Model Context Protocol server at `https://mcp.getpraxen.app/mcp` over streamable HTTP. Connect any MCP client and your agent can query telemetry, the topology, code and issues without leaving your editor. ## What it does The server exposes the Praxen REST API and the same agent tools Praxen's own agents use across every connected provider in the [catalog](https://docs.getpraxen.app/connect/integrations). The server card at `https://mcp.getpraxen.app/.well-known/mcp` lists every tool. Once connected, ask your agent something like "Use Praxen to show me the error rate for the service this branch deploys, over the last hour." ## Tools | Tool | Description | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `search` | Queries the Praxen OpenAPI specification from a small async function that runs in a sandbox against a resolved copy of the spec. Read-only. | | `execute` | Calls the REST API through `codemode.request({ method, path, query, body })`; the API enforces your credential's scopes on every call. | | `searchTools` | Lists the agent tools your workspace and credential can use, with their input schemas. Call it first. | | `runTool` | Runs one agent tool by its exact `toolName`, with its arguments as a nested `params` object. | | `runCode` | Chains several agent tools in one call from TypeScript written against a `tools.(args)` namespace. | | `reportFeedback` | Reports friction with the server to the Praxen team, with the client, session id and workspace attached so the team can reproduce it. | ## Authentication OAuth is the default: the server is an OAuth 2.0 provider with dynamic client registration, so a client that connects with no headers opens your browser to approve it and sign in to Praxen. An OAuth session can span several workspaces, so pass `workspaceId` (id or slug) on agent-tool calls. Where a browser sign-in is not possible, such as continuous integration or a remote machine, open **Settings > Coding Agents** and click **Create API key**: the key carries every read scope the MCP tools check, is shown once and starts with `sk_`. Send it as `x-api-key: ` or as `Authorization: Bearer `; a key is bound to one workspace, so `workspaceId` is optional. ## Install in your editor Claude Code, Cursor and Codex can install this server together with the Praxen skills as a [plugin](https://docs.getpraxen.app/tools/plugins). To register the server on its own, add it to your client: ::tabs :::tabs-item{icon="i-simple-icons-anthropic" label="Claude Code"} ```bash [Terminal] claude mcp add --transport http praxen https://mcp.getpraxen.app/mcp ``` ::: :::tabs-item{icon="i-simple-icons-opencode" label="OpenCode"} ```json [opencode.json] { "mcp": { "praxen": { "type": "remote", "url": "https://mcp.getpraxen.app/mcp" } } } ``` ::: :::tabs-item{icon="i-simple-icons-openai" label="Codex"} ```toml [~/.codex/config.toml] [mcp_servers.praxen] url = "https://mcp.getpraxen.app/mcp" ``` If your build lacks streamable HTTP, bridge with `npx mcp-remote https://mcp.getpraxen.app/mcp`. ::: :::tabs-item{icon="i-simple-icons-cursor" label="Cursor"} ```json [.cursor/mcp.json] { "mcpServers": { "praxen": { "type": "http", "url": "https://mcp.getpraxen.app/mcp" } } } ``` ::: :::tabs-item{icon="i-simple-icons-visualstudiocode" label="VS Code"} ```json [.vscode/mcp.json] { "servers": { "praxen": { "type": "http", "url": "https://mcp.getpraxen.app/mcp" } } } ``` ::: :: Each client opens a browser to sign in on first use. To use an API key instead, add an `x-api-key` header to the same entry through your client's header setting, such as `--header "x-api-key: YOUR_API_KEY"` for Claude Code or `http_headers` for Codex. ## Writes Agent tools stay read-only until the session sends `x-praxen-allow-writes: true` with a credential that carries the `agent_tools:write` scope. A safety model screens every write and clients that support elicitation ask you to approve each one; see [Reads by default, writes behind a gate](https://docs.getpraxen.app/tools#reads-by-default-writes-behind-a-gate). ## Limits Each credential can make 600 requests per 60 seconds. Requests past that budget receive a rate-limit response until the window resets. ## Related - [Work from your tools](https://docs.getpraxen.app/tools): how the MCP server, the CLI and the plugins fit together. - [Plugins](https://docs.getpraxen.app/tools/plugins): install this server, the docs server and the skills in one step. - [Docs MCP server](https://docs.getpraxen.app/reference/mcp): the separate server that lets your agent search and read these docs. - [API keys and OAuth](https://docs.getpraxen.app/administration/api-keys-and-oauth): scopes, key management and OAuth clients. - [MCP integration](https://docs.getpraxen.app/integrations/mcp): let Praxen's agents call tools from a server you run. # CLI The `praxen` command lets you use every part of Praxen from a terminal, a script or a coding agent. Output is a text table in a terminal and JSON when piped, every prompt can be turned off, and the full API is available for anything that is not a command yet. ## What it does Each command group wraps one part of the platform: issues, services and their logs, repositories, threads, agent tools and more. Every command accepts the same non-interactive flags, so a script or an agent can run it without prompts; see [Scripting](https://docs.getpraxen.app/tools/cli/scripting). ## Install All four channels install the same command. ::tabs :::tabs-item{icon="i-simple-icons-npm" label="npm"} ```bash [Terminal] npm install -g @Praxen Inc./praxen ``` ::: :::tabs-item{icon="i-simple-icons-homebrew" label="Homebrew"} ```bash [Terminal] brew install coreplanelabs/tap/praxen ``` ::: :::tabs-item{icon="i-lucide-terminal" label="macOS / Linux"} ```bash [Terminal] curl -fsSL https://getpraxen.app/setup.sh | bash ``` ::: :::tabs-item{icon="i-simple-icons-powershell" label="Windows"} ```powershell [PowerShell] irm https://getpraxen.app/setup.ps1 | iex ``` ::: :: ## Sign in ```bash [Terminal] praxen auth login praxen auth login --no-browser praxen auth login --api-key sk_xxxxx ``` The first form opens your browser, `--no-browser` prints a device code for SSH and headless machines, and `--api-key` stores an API key for scripts and agents. [Authentication](https://docs.getpraxen.app/tools/cli/authentication) covers each method and where credentials are stored. ## Command groups | Group | Description | | ------------- | -------------------------------------------------------------------------------------------- | | `issue` | Detected issues, their timelines, notes and milestones | | `service` | Cloud infrastructure: nodes, logs, metrics, dependency graph | | `repo` | Repositories | | `tools` | Run Praxen agent tools directly (`tools search`, `tools run`, `tools code`) | | `thread` | Conversation threads (`thread ask`, `thread continue`, streaming supported) | | `artifact` | Per-thread artifacts: reports, diagrams, pull requests | | `autofix` | Automated code fixes (read-only) | | `integration` | Integrations: code hosts, chat, observability, issue tracking, coding agents, MCP servers | | `cloud` | Cloud accounts for every provider in the [catalog](https://docs.getpraxen.app/connect/clouds) | | `workspace` | Create and switch workspaces | | `auth` | Login, status, logout | | `setup` | Wire the CLI into your coding agents: agent skill and MCP server | | `config` | CLI configuration | | `telemetry` | Anonymous usage telemetry: status, enable, disable | | `api` | Raw API access | | `update` | Check for CLI updates | ## Discover commands `--help` is the authoritative reference and always matches the version you have installed: run it on `praxen`, on a resource, or on a single command for its flags and examples. Anything not yet a first-class command is available under `praxen api`, whose `list`, `describe` and `call` subcommands reach every operation in the [API reference](https://api.getpraxen.app/v1/reference). ## Uninstall ```bash [Terminal] curl -fsSL https://getpraxen.app/uninstall | sh ``` The uninstaller backs up `~/.praxen` to a tarball in your home directory, then removes the CLI, the MCP servers and skills it registered in your coding agents, and the PATH entries it added; preview every step with `sh -s -- --dry-run`. Your account, workspace and integrations stay as they are, and if you installed with npm, run `npm uninstall -g @Praxen Inc./praxen` as well. ## Related - [Authentication](https://docs.getpraxen.app/tools/cli/authentication): every sign-in method and where credentials are stored. - [Scripting](https://docs.getpraxen.app/tools/cli/scripting): JSON output, exit codes and the flags for CI and agents. - [Configuration](https://docs.getpraxen.app/tools/cli/configuration): environment variables, the config file and telemetry. - [Plugins](https://docs.getpraxen.app/tools/plugins): install the CLI skill and the MCP servers into your coding agent in one step. # Authentication The CLI signs in through your browser, a device code or an API key, and in scripts and CI it reads the credential from a flag or an environment variable. Run `praxen auth login` to pick a method interactively, or pass a flag to skip the picker. ## Sign-in methods | Method | Command | Description | | ----------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Browser | `praxen auth login` | For interactive use. The CLI opens your browser, receives the tokens on a localhost callback and refreshes them as they expire. | | Device code | `praxen auth login --no-browser` | For SSH and headless machines. The CLI prints a URL and a code; open the URL on any device, enter the code, and the CLI polls until you approve. | | API key | `praxen auth login --api-key sk_xxxxx` | For scripts, CI and agents. The CLI validates the key and stores it with a default workspace. | After sign-in the CLI shows who you are and, if you belong to more than one workspace, asks you to pick a default, saved as `workspace_id` in `~/.praxen/config.json`. Force a token refresh with `praxen auth refresh`. ## API keys Create a key under **Settings > API Keys** with **Create an API key**: name it, choose its scopes and copy it, because it is shown once. Keys start with `sk_`. In CI, set `PRAXEN_API_KEY` in the environment instead of running the login step, or pass the global `--api-key ` flag on a single call. ## Credential precedence When several credentials are present, the CLI resolves them in this order: 1. The `--api-key` flag on the current command 2. The `PRAXEN_API_KEY` environment variable 3. OAuth credentials in `~/.praxen/credentials.json` 4. `api_key` in `~/.praxen/config.json` An exported `PRAXEN_API_KEY` always beats a stale `~/.praxen/credentials.json`, so a CI runner with the variable set does not pick up leftover OAuth tokens. `praxen auth status` shows which source is in use. ## Check and switch ```bash [Terminal] praxen auth status praxen auth whoami praxen auth logout ``` `auth status` shows the method in use, a masked token, the user and the workspace; `auth whoami` shows the current user. `auth logout` revokes OAuth tokens and clears stored credentials after a confirmation, which `--yes` skips; to switch accounts, log out and log in with the other credential. ## Environment variables | Variable | Description | | ----------------------- | -------------------------------- | | `PRAXEN_API_KEY` | API key for non-interactive auth | | `PRAXEN_WORKSPACE_ID` | Default workspace (`ws_` id) | | `PRAXEN_API_DOMAIN` | API hostname override | Use these in CI jobs and containers where you do not want to write to `~/.praxen/`. [Configuration](https://docs.getpraxen.app/tools/cli/configuration) lists the full set. ## Related - [Configuration](https://docs.getpraxen.app/tools/cli/configuration): the full precedence order, every environment variable and the files on disk. - [Scripting](https://docs.getpraxen.app/tools/cli/scripting): JSON output, exit codes and the flags for CI and agents. - [API keys and OAuth](https://docs.getpraxen.app/administration/api-keys-and-oauth): scopes, key management and OAuth clients. # Scripting The CLI is built to be driven by shell scripts, CI jobs and coding agents. Data goes to stdout, everything else goes to stderr, exit codes are stable and every prompt can be turned off. ## Output Output is text when stdout is a terminal and JSON when it is piped or redirected; force a format with `--output json` or `--output text`, the `PRAXEN_OUTPUT` variable or the config file, in that order of precedence. stdout carries only data, whether JSON, table rows or streamed tokens, so it is safe to pipe. stderr carries spinners, progress, hints and errors, and in JSON mode an error arrives as an object with `code`, `message` and `hint`, where `code` matches the exit code. ## Flags for scripts | Flag | Description | | ------------------- | --------------------------------------------------------------------------- | | `--output json` | Force JSON regardless of terminal state | | `--quiet` | Suppress spinners and progress; stdout stays pure data | | `--non-interactive` | Fail fast on missing input instead of prompting | | `--yes` | Skip confirmation on destructive commands | | `--dry-run` | Show what would happen without making changes | | `--full` | Return full objects on list commands instead of the narrow field projection | | `--api-key ` | Override the stored API key for one call | | `--workspace ` | Override the default workspace for one call | With `--non-interactive`, `praxen cloud disconnect` refuses to run unless you also pass `--yes`, while other confirmations are skipped, so pass `--yes` explicitly to make intent clear. `PRAXEN_API_KEY` and `PRAXEN_WORKSPACE_ID` set the credential and workspace from the environment, which suits CI; see [Authentication](https://docs.getpraxen.app/tools/cli/authentication). ## Exit codes | Code | Description | | ---- | --------------------------------------- | | 0 | Success | | 1 | General error | | 2 | Usage error: bad flag, missing argument | | 3 | Authentication error | | 4 | Rate limit or plan upgrade required | | 5 | Timeout | | 6 | Network error | | 130 | Interrupted with Ctrl-C | Branch on the exit code first to decide whether to retry, re-authenticate or surface the failure, then parse the error object on stderr for detail. ## Example ```bash [Terminal] praxen issue list --active --severity critical --output json --quiet \ | jq -r '.items[] | "\(.id)\t\(.title)"' ``` `praxen issue list` returns an object with `items` and `count`, and each item is projected to `id`, `severity`, `status`, `title`, `resourceKind`, `resourceId`, `detectedAt` and `investigationThreadId`; `--full` returns the complete objects. [Issues](https://docs.getpraxen.app/detect/issues) explains the lifecycle behind each status. ## Related - [Authentication](https://docs.getpraxen.app/tools/cli/authentication): API keys and environment variables for CI. - [Configuration](https://docs.getpraxen.app/tools/cli/configuration): output and timeout settings and the config file. - [Issues](https://docs.getpraxen.app/detect/issues): the statuses and severities the `issue` commands return. - [Threads](https://docs.getpraxen.app/investigate/threads): what `thread ask` starts and how a thread progresses. # Configuration The CLI reads each setting from flags, environment variables, its config file and built-in defaults, and stores everything under `~/.praxen`. This page lists the order, the variables and how to control telemetry. ## Precedence The CLI resolves each setting in this order, highest wins: 1. CLI flags, for example `--workspace`, `--api-key`, `--output` and `--timeout`. 2. Environment variables: the `PRAXEN_*` set plus the standard `NO_COLOR` and `DO_NOT_TRACK`. 3. For the credential only, OAuth tokens in `~/.praxen/credentials.json`. 4. The config file at `~/.praxen/config.json`. 5. Built-in defaults: domain `api.getpraxen.app`, timeout 300 seconds, output `text` in a terminal and `json` when piped. An exported `PRAXEN_API_KEY` always beats a stale `~/.praxen/credentials.json`, so a CI runner with the variable set does not pick up leftover OAuth tokens. [Authentication](https://docs.getpraxen.app/tools/cli/authentication) lists the same order for credentials. ## Config file `~/.praxen/config.json` accepts six keys: `domain`, `workspace_id`, `api_key`, `output`, `timeout` and `telemetry`. Manage it through the CLI: `config show` prints the resolved configuration, the auth method in use and the file path, with API keys masked. ```bash [Terminal] praxen config show praxen config set --key output --value json ``` To set the default workspace by slug instead of id, run `praxen workspace use `. OAuth credentials live separately in `~/.praxen/credentials.json` and refresh on their own when the access token nears expiry. ## Environment variables | Variable | Description | | ----------------------- | --------------------------------------------------------------------------------------------------- | | `PRAXEN_API_KEY` | Authenticate without storing a key on disk | | `PRAXEN_WORKSPACE_ID` | Set the workspace for the current shell | | `PRAXEN_API_DOMAIN` | Point at a different API hostname; hostname only, no protocol | | `PRAXEN_OUTPUT` | Force `text` or `json` output | | `PRAXEN_TIMEOUT` | Request timeout in seconds | | `PRAXEN_VERBOSE` | Enable verbose logging | | `PRAXEN_TELEMETRY=0` | Disable telemetry for this environment | | `DO_NOT_TRACK=1` | The universal telemetry opt-out; overrides every other telemetry setting, including the config file | | `NO_COLOR` | Disable ANSI colors | ## Telemetry Anonymous usage telemetry is on by default. It records the command name, flag names, the count of positional arguments, the exit code and error category, durations, CLI and Node versions, operating system details, an anonymous per-install identifier and the workspace id. Flag values, arguments, file paths, command output and full error messages stay out of it, and `praxen telemetry status` shows exactly what is sent and where. Turn it off for good with `praxen telemetry disable`, which writes to the config file, or per environment with `PRAXEN_TELEMETRY=0` or `DO_NOT_TRACK=1`. The decision follows `DO_NOT_TRACK`, then `PRAXEN_TELEMETRY`, then the config file, then the default of on; there is no per-invocation flag. ## Files on disk Everything the CLI stores lives under `~/.praxen`: | File | Description | | ------------------- | ---------------------------------------------------------------------- | | `config.json` | Saved settings: domain, workspace, API key, output, timeout, telemetry | | `credentials.json` | OAuth tokens | | `telemetry.json` | Anonymous install id and run counters | | `update-state.json` | Update check state | Delete the directory to reset the CLI completely; a fresh install id is generated on the next run. ## Related - [Authentication](https://docs.getpraxen.app/tools/cli/authentication): the sign-in methods and how credentials are chosen. - [Scripting](https://docs.getpraxen.app/tools/cli/scripting): the output contract, script flags and exit codes. # Plugins The Praxen plugin installs this whole section in one step for Claude Code, Cursor or Codex: the [platform MCP server](https://docs.getpraxen.app/tools/platform-mcp), the [docs MCP server](https://docs.getpraxen.app/reference/mcp), skills that teach your agent the platform and the [CLI](https://docs.getpraxen.app/tools/cli), and slash commands for the most common workflows. One repository, [coreplanelabs/skills](https://github.com/coreplanelabs/skills), is published to each agent's plugin directory. ## What it adds | Component | Description | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `praxen` MCP server | `https://mcp.getpraxen.app/mcp`: the REST API and agent tools for connected providers. See [Platform MCP server](https://docs.getpraxen.app/tools/platform-mcp). | | `praxen-docs` MCP server | `https://docs.getpraxen.app/mcp`: search and read these docs, so the agent retrieves current commands and schemas instead of guessing. See [Docs MCP server](https://docs.getpraxen.app/reference/mcp). | | `praxen` skill | The platform: connecting a stack, investigating issues, checking the production impact of a change before shipping it, and how to use the MCP server well. | | `praxen-cli` skill | The `praxen` command: authentication, workspaces, querying services and logs, running agent tools, threads and scripting patterns. | | `/praxen:onboard` | Install the CLI, sign in, and connect integrations and cloud accounts. | | `/praxen:investigate` | Find the cause of an issue across logs, metrics, the dependency graph, code and recent changes. | Skills load themselves when a request matches their description, and commands run when you invoke them. Claude Code and Cursor ship the commands; Codex surfaces the same workflows as starter prompts on the plugin, and Cursor also gets a rule that reminds the agent to retrieve Praxen documentation before acting. Once installed, ask your agent something like "Use Praxen to show me the error rate for the service this branch deploys, over the last hour, and what changed in production for it today." ## Install ::tabs :::tabs-item{icon="i-simple-icons-anthropic" label="Claude Code"} ```bash [Claude Code] /plugin marketplace add coreplanelabs/skills /plugin install praxen@praxen ``` The same commands work from a terminal as `claude plugin marketplace add coreplanelabs/skills` and `claude plugin install praxen@praxen`. Update later with `claude plugin update praxen@praxen`. ::: :::tabs-item{icon="i-simple-icons-cursor" label="Cursor"} Open **Settings > Plugins**, search for **Praxen** in the Cursor Marketplace and install it; plugins need Cursor 3.13 or later. Without the marketplace, register the MCP server with the [Add to Cursor](https://cursor.com/install-mcp?name=praxen&config=eyJ1cmwiOiJodHRwczovL21jcC5wb2x5bGFuZS5jb20vbWNwIn0=) link and add the skills under **Settings > Rules > Add Rule > Remote Rule (GitHub)** with `coreplanelabs/skills`. ::: :::tabs-item{icon="i-simple-icons-openai" label="Codex"} ```bash [Terminal] codex plugin marketplace add coreplanelabs/skills --ref main codex plugin add praxen@praxen ``` You can also install **Praxen** from the plugin directory with `/plugins` in the Codex app or CLI. Start a new thread so the skills and MCP servers load, and update later with `codex plugin marketplace upgrade praxen` followed by `codex plugin add praxen@praxen`. ::: :: Any agent that follows the Agent Skills standard can use the skills without the plugin wrapper: run `npx skills add coreplanelabs/skills`. ## Sign in The first connection to the `praxen` server opens your browser: approve the client and sign in to Praxen, and the agent stores the tokens (in Claude Code, run `/mcp` to start it). On a machine without a browser, register the server yourself with an API key as [Platform MCP server](https://docs.getpraxen.app/tools/platform-mcp#authentication) describes; agent tools stay read-only until you opt in, on the plugin as everywhere else. ## Check the install | Agent | Description | | ----------- | ------------------------------------------------------------------------------------------------------------- | | Claude Code | `claude plugin list` shows `praxen@praxen`, and `/mcp` lists `praxen` and `praxen-docs` as connected. | | Cursor | **Settings > MCP** lists `praxen`, and the Praxen skills show under **Customize**. | | Codex | `codex plugin list` shows `praxen@praxen` as installed and enabled, and `/mcp` lists both servers. | ## Related - [Platform MCP server](https://docs.getpraxen.app/tools/platform-mcp): the tools behind the `praxen` server and how to register it by hand. - [CLI](https://docs.getpraxen.app/tools/cli): the command the `praxen-cli` skill teaches your agent to use. - [Docs MCP server](https://docs.getpraxen.app/reference/mcp): what the `praxen-docs` server gives your agent. - [Reads by default, writes behind a gate](https://docs.getpraxen.app/tools#reads-by-default-writes-behind-a-gate): how to unlock write tools when you need them. # Workspace Everything on this page lives under **Settings** in the [console](https://console.getpraxen.app). It covers the workspace-level controls that have no page of their own: who is in the workspace, what each settings page does, and how to take your data out. ## Members and roles Every member holds one role, and owners and admins can invite teammates from **Settings > Members** with **Invite a teammate**. An invite grants the member, admin or read-only role, and pending invites count toward the member limit alongside accepted members. The Free plan includes two team members; paid plans do not cap members. | Role | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------ | | `owner` | Full control of the workspace, including deleting it. | | `admin` | Invites members and manages roles, deletes any API key or telemetry token, reviews published pages and requests exports. | | `member` | The default role for a teammate who works in the workspace. | | `read-only` | The lowest role, for people who need to see the workspace without running it. | Each member also carries a set of granular permission scopes, managed from the **Manage permissions** card on the same page. ## Join by email domain On the Team plan and above, **Joining by email domain** under **Settings > Members** lets anyone with a verified email on your company domain join as a member without an invite. Owners and admins get an email each time someone joins this way. ## Teams **Manage teams**, also under **Settings > Members**, groups members into teams for shared ownership and visibility of resources. Create one with **New team**. ## Settings map | Settings entry | What it controls | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Workspace** | Name, slug, workspace ID, avatar and description, plus the sections in the next table. Changing the slug changes every URL in the workspace. | | **Billing & Usage** | Your plan, usage against its limits, invoices and overage. See [Billing and usage](https://docs.getpraxen.app/administration/billing-and-usage). | | **Members** | Roles and permissions, invites, joining by email domain, and teams. | | **Coding Agents** | Connect your editor's agent over MCP and create the API key it uses. See [Platform MCP server](https://docs.getpraxen.app/tools/platform-mcp). | | **Integrations** | Connect and disconnect clouds, code hosts and observability tools. See [Integrations](https://docs.getpraxen.app/connect/integrations). | | **Clouds** | The cloud accounts agents use to inspect your infrastructure. See [Clouds](https://docs.getpraxen.app/connect/clouds). | | **Repositories** | The code repositories agents can read and act on. See [Repositories](https://docs.getpraxen.app/connect/repositories). | | **API Keys** | Scoped keys for scripts and CI. See [API keys and OAuth clients](https://docs.getpraxen.app/administration/api-keys-and-oauth). | | **OAuth Clients** | Applications that access Praxen on a user's behalf. See [API keys and OAuth clients](https://docs.getpraxen.app/administration/api-keys-and-oauth). | | **Telemetry Tokens** | Credentials that authenticate alerts forwarded from your observability tools. A token's creator or a workspace admin can delete it. | | **Labels** | Labels that organize and categorize resources across the workspace. | | **Pages** | Every public page the workspace has published, which admins and owners can review and delete. | | **Notifications** | Your personal email preferences and the workspace weekly digest. See [Notifications](https://docs.getpraxen.app/administration/notifications). | | **Analytics** | Charts of usage, investigations, issues and autofixes over the last 7 to 90 days, hourly or daily, for all users or one person. | | **Support** | Documentation, a call with the Praxen team, a Slack Connect channel and a feedback form. | The **Workspace** page itself is split into sections. | Section | What you set there | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **AI Models** | The model family behind your agents and your own provider key. See [AI models](https://docs.getpraxen.app/administration/ai-models). | | **Investigations** | The severity at which Praxen investigates and fixes confirmed issues on its own, and the alert signatures you have suppressed. | | **Autofix** | Whether autofix pull requests open at all and whether commits are attributed to the person who asked or to Praxen. | | **Escalations** | The escalation severities Praxen announces right away in your Slack notifications channel and by email to admins. | | **Impact assessments** | Whether each pull request gets an assessment against the production topology. See [Impact assessments](https://docs.getpraxen.app/detect/pull-request-reviews). | | **Privacy & data** | Whether Praxen Inc. may use workspace data to improve its models, and the workspace export. | | **Screensaver** | Plays your live topology fullscreen. | | **Danger Zone** | Deletes the workspace. Only the owner can, and it is not reversible. | ## Idle Free workspaces A Free workspace nobody has interacted with for seven days gets a warning email, and background monitoring pauses three days later if nobody comes back. Opening the workspace or replying to the email resumes it; [Billing and usage](https://docs.getpraxen.app/administration/billing-and-usage) lists what pauses and what keeps running. ## Export your data Admins and owners can request an export from **Privacy & data** with **Request export**. Reports, impact assessments, settings and threads arrive in one JSON archive. You get an email with a download link when it is ready. Exports work for 60 days after workspace deletion. ## Related - [Notifications](https://docs.getpraxen.app/administration/notifications) to choose which events reach your inbox and what the workspace gets in Slack. - [AI models](https://docs.getpraxen.app/administration/ai-models) to run agents on your own provider key or endpoint. - [API keys and OAuth clients](https://docs.getpraxen.app/administration/api-keys-and-oauth) to create credentials for scripts and applications. - [Billing and usage](https://docs.getpraxen.app/administration/billing-and-usage) for plan limits, invoices and idle workspaces. # Notifications Praxen emails you about what happens in your workspace, and you choose which events qualify. Preferences are per person: your choices do not affect your teammates. ## What it does Open **Settings > Notifications** in the [console](https://console.getpraxen.app). The **Email** switch at the top mutes every event and disables each per-event checkbox; below it, every event has its own checkbox, grouped by category. Most events are on by default, and three stay off until you turn them on: **Account Connected**, **Autofix PR Merged** and **Production Concern Found**. Two switches under **Account updates** are separate from events. **Product updates** sends a monthly email about what shipped, and **Important updates** covers security fixes and maintenance. ## Events | Category | Event | Email by default | Description | | ------------------ | -------------------------------- | ---------------- | -------------------------------------------------------------------------------------------- | | Cloud Accounts | Account Connected | Off | A cloud account was connected to the workspace. | | Cloud Accounts | Account Removed | On | A cloud account was removed from the workspace. | | Integrations | Integration Removed | On | An integration was disconnected. | | Team | Invite Accepted | On | Someone accepted an invite to the workspace. | | Team | Access Requested | On | Someone asked to join the workspace. | | Team | Member Joined | On | A member joined the workspace. | | Security | Cloud Account Needs Reconnecting | On | A cloud account's credentials need to be reconnected. | | Security | Integration Needs Reconnecting | On | An integration's credentials need to be reconnected. | | Usage | Usage Limit Reached | On | The workspace reached a plan limit. | | Usage | Usage Threshold Warning | On | Usage crossed a warning threshold on the way to a limit. | | Escalations | New Escalation | On | Workspace owners and admins: an escalation at a severity the workspace alerts on was raised. | | Escalations | Daily Escalations | On | Once a day, a list of the open escalations raised or seen again in the last 24 hours. | | Autofixes | Autofix PR Submitted | On | An autofix opened a pull request. | | Autofixes | Autofix PR Merged | Off | An autofix pull request was merged. | | Autofixes | Autofix Failed | On | An autofix run failed. | | Autofixes | Autofix PR Waiting on Review | On | An open autofix pull request is waiting on your review. | | Impact Assessments | Production Concern Found | Off | An impact assessment found a production concern. | | Digest | Weekly Digest | On | The weekly summary of issues, investigations, autofixes, changes and idle resources. | | Digest | Waiting Autofixes | On | A digest of autofix pull requests waiting on action. | | Onboarding | Connect Reminders | On | Reminders to finish connecting your stack. | | Workspace | Monitoring Pause Notice | On | An idle Free workspace is about to pause monitoring. | | Workspace | Monitoring Paused | On | Monitoring paused on an idle Free workspace. | | Billing | Payment Received | On | A payment succeeded. | | Billing | Payment Failed | On | A payment failed. | | Billing | Workspace Past Due | On | A payment lapsed and the workspace is past due. | | Billing | Subscription Canceled | On | The subscription was canceled. | | Billing | Plan Changed | On | The workspace moved to another plan. | | Billing | Billing Cycle Changed | On | The billing cycle switched between monthly and annual. | | Billing | Overage Started | On | Agents started drawing on pay-as-you-go overage. | | Billing | Overage Cap Reached | On | Overage reached the monthly cap you set. | Checkout, scheduled cancellation and renewal reminder emails always send and do not appear in the list. ## Weekly digest Once a week, every member receives a summary of the workspace's issues, investigations, autofixes, changes and idle resources. The **Weekly Digest** checkbox in the Digest category stops the email for you alone. The **Weekly digest** switch in the **Workspace** section of the same page stops it for every member, and changing it requires workspace write permission. ## Daily escalations Once a day, every member receives a list of the open escalations that Praxen raised or saw again in the last 24 hours, the most critical first. Each row links to the escalation page. A day with no open escalations sends nothing. The **Daily Escalations** checkbox in the Escalations category stops the email for you alone. ## Slack With the [Slack integration](https://docs.getpraxen.app/integrations/slack) connected, Praxen also posts to a shared channel: connecting creates `#praxen-notifications` in your Slack workspace and invites the person who connected it. Delivery there is workspace-wide and independent of your email preferences: new escalations at the severities chosen under **Settings > Workspace > Escalations**, autofix pull requests, credential failures, usage warnings, the weekly digest, monitoring pauses, invites and members joining all arrive as cards. The Slack App Home tab lists the open problems with **Open the investigation** and **All fix runs** buttons. ## Related - [Escalations](https://docs.getpraxen.app/investigate/escalations) for the one list of what agents need from you. - [Autofix](https://docs.getpraxen.app/investigate/autofix) for the pull request lifecycle behind the Autofixes events. - [Billing and usage](https://docs.getpraxen.app/administration/billing-and-usage) for what triggers the Usage and Billing events. - [Slack integration](https://docs.getpraxen.app/integrations/slack) to connect Slack and add Praxen to channels. # AI models Every workspace has one AI model configuration, and it applies to every agent in the workspace: threads, fix runs, autofixes and background work. Set it in the **AI Models** section of **Settings > Workspace** in the [console](https://console.getpraxen.app). ## Providers | Provider | Description | Plan | | ------------------------------ | ---------------------------------------------------------------------------------- | ---------- | | **Praxen Pure** | The default. Praxen manages inference for you, with no key and no configuration. | Every plan | | **OpenAI** | OpenAI's model family, with the option to bring your own key. | Enterprise | | **Anthropic** | Anthropic's model family, with the option to bring your own key. | Enterprise | | **Custom (OpenAI-compatible)** | Your own endpoint and your own models, one per tier. | Enterprise | ## Bring your own key On Enterprise, select OpenAI or Anthropic, turn on **Bring Your Own Key** and paste an API key from your provider account. Model calls then run against that account under your own agreement with the provider, and the key is encrypted at rest. Access to the latest models typically requires a paid plan on the provider side, so a free-tier key may fail or be limited to older models. Use **Test connection** before saving: it runs a test generation through the path real requests take, including your gateway when one is set. Switching back to Praxen Pure and saving removes the stored key and gateway. On the Enterprise plan, **Custom Gateway** routes every inference request through your own OpenAI-compatible gateway instead of the provider's default endpoint. The field unlocks once you have provided an API key. ## Custom endpoint On the Enterprise plan, the **Custom (OpenAI-compatible)** provider runs agents on models Praxen does not offer, such as a self-hosted or private deployment. Usage on your endpoint is billed by your provider and is not metered against your Praxen plan. | Field | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------- | | **Base URL** | The root of your OpenAI-compatible inference API. | | **Models URL** | Optional. A separate endpoint that lists available models. Leave it blank to use the models path under the base URL. | | **Auth header name** | The header your endpoint authenticates with. Defaults to `Authorization`; use `x-api-key` if your endpoint requires it. | | **Auth header value** | Sent verbatim as the value of that header, so include any prefix your endpoint expects. Encrypted at rest. | ## Model tiers Praxen routes each internal task to a tier. Click **Load models** to pull the model list from your endpoint, then assign a model per tier. | Tier | Description | | -------------- | ----------------------------------------------------------- | | **Premium** | Deep reasoning: investigations, autofix, action plans. | | **Standard** | Most agent work: triage, reviews. | | **Cheap** | High-volume light tasks: titles, summaries, classification. | | **Code** | Repository and infrastructure exploration. | | **Embeddings** | Vector search indexing. | | **Reranker** | Search reranking. | Premium, Standard and Cheap fall back to each other, and Code falls back to them, so setting only Standard runs all agent work on one model. No tier falls back to Code, so Code alone is not enough to save. Embeddings falls back to Praxen's managed embeddings when unset, and reranking is skipped when no reranker is set. Finish with **Test connection**, which runs a test generation against your cheapest configured tier. ## Related - [Billing and usage](https://docs.getpraxen.app/administration/billing-and-usage) for which plan unlocks which provider. - [Workspace](https://docs.getpraxen.app/administration) for the rest of the Workspace settings page. # API keys and OAuth clients Praxen has two credential types for programmatic access. API keys suit scripts, CI and headless tools: one key, one workspace, a fixed set of scopes. OAuth clients suit applications that sign users in and call Praxen on their behalf, and both authenticate against the same [API](https://api.getpraxen.app/v1/reference). ## API keys Open **Settings > API Keys** in the [console](https://console.getpraxen.app) and click **Create an API key**. Name the key (at least 4 characters) and pick its scopes: the form preselects the scopes your own membership holds, and a request for a scope you do not hold fails with a 403. The key is shown once, starts with `sk_` and cannot be viewed again, so copy it into your secret manager. Send the key in the `x-api-key` header: ```bash [Terminal] curl https://api.getpraxen.app/v1/scopes \ -H "x-api-key: sk_xxxxx" ``` Requests are authorized against the key's scopes, not your full permissions. Revoke a key from the same settings page or with a `DELETE` to `/v1/api_keys/{workspaceId}/{id}`; the key's creator or a workspace admin can delete it. ## Scopes Scopes pair a resource with an action, and `GET /v1/scopes` lists every one with its description. These are the scopes you will meet most often across these docs. | Scope | Description | | --------------------- | ------------------------------------------------------------------------------ | | `threads:read` | View threads. | | `issues:write` | Acknowledge, resolve or rerun issue checks. | | `cloud_infra:read` | View cloud infrastructure nodes and edges. | | `autofixes:write` | Record and update autofix lifecycle state. | | `agent_tools:read` | Discover and run read-only agent tools from external clients such as MCP. | | `agent_tools:write` | Run write-capable agent tools from external clients, subject to safety review. | | `oauth_clients:write` | Create and manage OAuth clients. | | `analytics:read` | View workspace activity, popular content and usage statistics. | ## OAuth clients An OAuth client is an application you register so it can sign users in and call Praxen with the scopes each user approves; managing clients requires `oauth_clients:write`. Open **Settings > OAuth Clients** and click **New OAuth client**: the name and contact email appear on the consent screen, you add the redirect URIs and the scopes the client may request, and description, website and logo are optional. Creation returns a client ID starting with `oauth_client_` and a client secret shown once; if you lose the secret, **Rotate** it from the client's page and the previous secret stops working immediately. ## The authorization flow Praxen implements the OAuth 2.0 authorization code flow with PKCE (`S256`). ::steps{level="3"} ### Send the user to the consent page ```text https://console.getpraxen.app/oauth/ ?client_id= &redirect_uri=https://example.com/callback &scope=threads:read%20issues:read &code_challenge= &code_challenge_method=S256 &state= ``` The redirect URI must exactly match one you registered, and every requested scope must be one the client was granted. ### Exchange the code for tokens After the user approves, Praxen redirects to your callback with a `code`. Exchange it on your backend: ```bash [Terminal] curl -X POST https://api.getpraxen.app/v1/oauth/token \ -H "Content-Type: application/json" \ -d '{"grant_type": "authorization_code", "code": "", "redirect_uri": "https://example.com/callback", "client_id": "", "client_secret": "", "code_verifier": ""}' ``` The response carries an `access_token` that expires after one hour and a `refresh_token`. ### Call the API as the user ```bash [Terminal] curl https://api.getpraxen.app/v1/scopes \ -H "Authorization: Bearer " ``` ### Refresh when the access token expires Post `grant_type` `refresh_token` to the same token endpoint. Refresh tokens are single use: each refresh returns a replacement. :: Server metadata, including every endpoint URL, is published at `https://api.getpraxen.app/v1/.well-known/oauth-authorization-server`, and the provider also exposes `/v1/oauth/userinfo` and `/v1/oauth/introspect`. Revoke a token your application holds with a `POST` to `/v1/oauth/revoke` carrying the token and your client credentials, with `token_type_hint` set to `access_token` or `refresh_token`, or omitted to try both. Deleting a client from its page stops it from starting further authorizations. ## Coding agents You do not need an OAuth client to connect a coding agent. The hosted MCP server at `https://mcp.getpraxen.app/mcp` runs its own OAuth flow with dynamic client registration and also accepts an API key; see [Platform MCP server](https://docs.getpraxen.app/tools/platform-mcp). ## Related - [Platform MCP server](https://docs.getpraxen.app/tools/platform-mcp) to connect an editor agent without registering a client. - [CLI authentication](https://docs.getpraxen.app/tools/cli/authentication) to sign the CLI in with a browser, a device code or an API key. - [API reference](https://docs.getpraxen.app/reference/api) for every endpoint and the scopes it requires. # Billing and usage Praxen has eight plans: Free, Starter, Team, Business, Scale, Premium, Ultimate, and Enterprise. Manage your plan under **Settings → Billing** and watch consumption under **Settings → Usage**. Both pages link to the plans page where you compare and change plans. ## Monthly credits Your monthly credits cover all agent activity, including chat, investigations, and monitoring. More demanding tasks use more credits. Billing shows the percentage used and the reset date; analytics shows usage over time and each type of work's share. When the credits are used up and paid extra usage is off, agent activity pauses until the next monthly reset or you upgrade. Free workspaces reset on their creation day each month; paid workspaces reset on the day their subscription began, including annual subscriptions. A date past the end of a shorter month resets on that month's last day. Billing shows a warning once you use 70% of the credits. Workspace owners and admins receive a credit usage email once you use 80% of the credits. When Praxen gives your workspace a usage reset, workspace owners and admins can use it from **Settings → Billing** with **Reset usage**. The monthly credits and the month's PR reviews start again from zero, and the next monthly reset stays on the same day. Extra usage already paid for that month still counts toward your monthly cap. Each reset is available for 14 days after Praxen gives it, and Billing shows the date it expires. When a workspace has more than one, **Reset usage** uses the one that expires soonest. The button stays inactive while the workspace has no reset available. If a subscription payment is past due or unpaid, agent activity also pauses until payment is resolved. ## Plan limits | What you get | Free | Starter | Team | Business | Scale | Premium | Ultimate | Enterprise | | ----------------------------------- | --------- | --------- | --------- | --------- | --------- | --------- | ----------- | ---------- | | Monthly credits | Included | 10x Free | 40x Free | 100x Free | 160x Free | 400x Free | 1,000x Free | Unlimited | | Cloud accounts | 2 | 5 | Unlimited | Unlimited | Unlimited | Unlimited | Unlimited | Unlimited | | Team members | 2 | Unlimited | Unlimited | Unlimited | Unlimited | Unlimited | Unlimited | Unlimited | | Impact assessments per month | 10 | 500 | 2,000 | 5,000 | 8,000 | 20,000 | 50,000 | Unlimited | | Automatic fix runs per day | 16 | Unlimited | Unlimited | Unlimited | Unlimited | Unlimited | Unlimited | Unlimited | | Autofix pull requests per month | Unlimited | Unlimited | Unlimited | Unlimited | Unlimited | Unlimited | Unlimited | Unlimited | | Pay-as-you-go overage | - | - | - | - | ✓ | ✓ | ✓ | ✓ | | Bring your own LLM provider API key | - | - | - | - | - | - | - | ✓ | | Join by email domain | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Bring your own AI gateway | - | - | - | - | - | - | - | ✓ | The team member count includes pending invites. Each paid plan's monthly credits are listed as a multiple of the Free plan's credits. Repositories and integrations are not limited on any plan. When an action would exceed a limit, the API returns status code 402 with the affected limit and a next action. Monthly credit errors omit internal usage counters. Enterprise workspaces can bring their own model provider API key. See [AI models](https://docs.getpraxen.app/administration/ai-models). Joining by email domain, which lets anyone with a verified email on the workspace's domain join without an invite, is available on the Team, Business, Scale, Premium, Ultimate, and Enterprise plans. ## Automatic fix runs on Free A fix run reads the evidence for a detection, decides whether it is a real problem, and works it to a fix. One run can use a large part of the Free plan's credits, so a Free workspace starts up to 16 fix runs on its own in any 24 hours. This covers runs from detections, findings from Praxen's own exploration, and repository tasks such as adding observability. A new connection often turns up several detections at once; the limit bounds automatic activity against the shared monthly credits. - Detections past the first 16 in the rolling 24-hour window are recorded as issues with the status **Not triaged**, so nothing is lost. Praxen does not queue them for the next day: the oldest detection is usually the least useful one to run first, and a queue would spend the next day's runs on it. - A confirmed Issue that Praxen would restart on its own, for example after it recurs or after another Issue is linked to it, is held with **Held because today's automatic fix runs on this plan are used**. The next recurrence starts it again. - A repository task past the limit is recorded on the autofix page as not started, and **Re-run** starts it. - **Investigate** on the issue starts a fix run at any time. Runs a person starts do not count toward the daily limit. On Free, impact assessments use a faster model, so each assessment uses fewer credits. When the monthly credits are used up, detections are also recorded as **Not triaged**, and a fix run that was already working stops with the reason that the workspace ran out of credits. Add credits or upgrade, then use **Investigate** to start it again. ## Inactive workspaces A Free workspace nobody has used for a while stops running background work, and picks it back up the moment someone returns. Nothing is deleted: connections, issues, threads, history, and settings stay exactly as they are. Paid plans are never paused. 1. After 7 days without anyone using the workspace, owners and admins receive an email: monitoring pauses in 3 days unless someone wants it to continue. Opening the workspace or replying to the email keeps it on. 2. If nobody acts within those 3 days, Praxen pauses background monitoring. Scheduled checks, signal discovery, daily automations, and the weekly digest stop. Impact assessments, alert triage, and chat keep working. A second email confirms the pause. 3. Any of these resumes everything right away: signing in, opening the console, sending the agent a message, merging an autofix pull request, or replying to either email. There is nothing to switch back on. Using the workspace means a person acting in it; agents, monitors, and webhooks that run on their own never count. The two emails are the **Monitoring Pause Notice** and **Monitoring Paused** events under [Notifications](https://docs.getpraxen.app/administration/notifications), and a workspace with Slack connected sees the same notice in its notifications channel. ## Paid extra usage The Scale, Premium, Ultimate, and Enterprise plans can enable paid extra usage under **Settings → Billing → Spending limit**. Agents then keep running after the monthly credits are used up. Extra usage is billed at the end of the period, up to the monthly spending cap you set in the same panel. Agents pause when that cap is reached. With paid extra usage off, agents pause when the monthly credits are used up and resume at the next monthly reset. ## Changing plans Open the plans page from **Adjust plan** on the billing page or **Upgrade** on the usage page. It lists every plan above Free: Starter, Team, Business, Scale, Premium, Ultimate, and Enterprise. A **Monthly** / **Yearly** toggle switches the billing cycle for the six self-serve plans; Enterprise shows custom pricing and a **Contact us** button. - Upgrading from Free starts a Stripe checkout. - Changing between paid plans applies directly to your existing subscription. - Downgrades show a confirmation with your current usage measured against the target plan's limits before anything changes. - Enterprise is handled by contacting us directly from the plan card. To cancel, use **Cancel plan** on the billing page. The subscription stays active until the end of the current period, then the workspace returns to the Free plan. ## Invoices and payment The billing page lists past invoices with their date, amount, and status, each linking to the hosted invoice. Payment methods are managed in the Stripe customer portal, opened from **Settings → Billing → Payment method**. # Docs MCP server The docs site runs its own Model Context Protocol server at `https://docs.getpraxen.app/mcp`, so any MCP client can search and read these pages while you work. It only reads documentation; to give an agent access to your workspace (topology, issues, threads), use the [platform MCP server](https://docs.getpraxen.app/tools/platform-mcp). ## Tools | Tool | Description | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list-pages` | Lists every page with its title, path, description and full URL. It takes no parameters, and agents call it first to find what exists. | | `get-page` | Returns one page in full: title, description and markdown. It takes one parameter, `path`, a page path from `list-pages` such as `/investigate/autofix`. | ## Resources Clients that support MCP resources can read the documentation without calling a tool. | Resource | URI | Description | | ------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `docs-index` | `https://docs.getpraxen.app/llms.txt` | The [llms.txt](https://docs.getpraxen.app/reference/llms) index: every page with its title, description and raw markdown URL, organized by section. | | `docs-full` | `https://docs.getpraxen.app/llms-full.txt` | The complete content of every page in one markdown document. | Both URIs are plain HTTPS URLs too, so anything that cannot speak MCP can fetch them directly. ## Install in your editor ::tabs :::tabs-item{icon="i-simple-icons-anthropic" label="Claude Code"} ```bash [Terminal] claude mcp add --transport http praxen-docs https://docs.getpraxen.app/mcp ``` ::: :::tabs-item{icon="i-simple-icons-opencode" label="OpenCode"} ```json [opencode.json] { "mcp": { "praxen-docs": { "type": "remote", "url": "https://docs.getpraxen.app/mcp" } } } ``` ::: :::tabs-item{icon="i-simple-icons-cursor" label="Cursor"} ```json [.cursor/mcp.json] { "mcpServers": { "praxen-docs": { "type": "http", "url": "https://docs.getpraxen.app/mcp" } } } ``` ::: :::tabs-item{icon="i-simple-icons-visualstudiocode" label="VS Code"} ```json [.vscode/mcp.json] { "servers": { "praxen-docs": { "type": "http", "url": "https://docs.getpraxen.app/mcp" } } } ``` ::: :::tabs-item{icon="i-simple-icons-windows" label="Windsurf"} ```json [.codeium/windsurf/mcp_config.json] { "mcpServers": { "praxen-docs": { "type": "http", "url": "https://docs.getpraxen.app/mcp" } } } ``` ::: :::tabs-item{icon="i-simple-icons-zedindustries" label="Zed"} ```json [.config/zed/settings.json] { "context_servers": { "praxen-docs": { "source": "custom", "command": "npx", "args": ["mcp-remote", "https://docs.getpraxen.app/mcp"], "env": {} } } } ``` ::: :: Once connected, your editor's agent searches the docs mid-conversation, cites exact pages and stays current as the documentation changes. ## Related - [Platform MCP server](https://docs.getpraxen.app/tools/platform-mcp) to query your own workspace from the same editor. - [llms.txt](https://docs.getpraxen.app/reference/llms) for the same pages as plain text, without MCP. - [Plugins](https://docs.getpraxen.app/tools/plugins) to install both MCP servers in one step. # llms.txt Every Praxen docs page is also published as plain text through the [llms.txt convention](https://llmstxt.org), so a language model or coding agent can read the documentation without a browser. ## Endpoints | URL | Description | | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | [/llms.txt](https://docs.getpraxen.app/llms.txt) | The title, the description and an index of every page grouped by section, each with its raw markdown URL. | | [/llms-full.txt](https://docs.getpraxen.app/llms-full.txt) | The full markdown of every page in one file. | | `/raw/.md` | One page as raw markdown, served as `text/markdown`. Prefix the docs path with `/raw/` and add `.md`. | For example, this page is served at [/raw/reference/llms.md](https://docs.getpraxen.app/raw/reference/llms.md) and the autofix page at [/raw/investigate/autofix.md](https://docs.getpraxen.app/raw/investigate/autofix.md). When a page body does not start with a level one heading, the route prepends the title as a heading and the description as a blockquote, so the file stands alone. ## When to use which - **Agent with web access**: point it at `/llms.txt` so it can fetch individual pages through the [docs MCP server](https://docs.getpraxen.app/reference/mcp), the `/raw/` routes or a plain HTTP fetch. - **Offline prompts or fine-tuning**: use `/llms-full.txt` to bundle the docs into a single context window or dataset. ## Related - [Docs MCP server](https://docs.getpraxen.app/reference/mcp) for the same pages as MCP tools and resources. - [API reference](https://docs.getpraxen.app/reference/api) for the hosted OpenAPI reference of the platform itself. # API reference The complete Praxen API reference is generated from the OpenAPI specification the platform serves, so it always matches what is deployed. ::card --- icon: i-lucide-external-link target: _blank title: Open the API reference to: https://api.getpraxen.app/v1/reference --- Every operation, request and response shape, and copyable request snippets. :: ## Authentication Send a workspace API key in the `x-api-key` header, or an OAuth access token in `Authorization: Bearer`. Create either in the console; see [API keys and OAuth clients](https://docs.getpraxen.app/administration/api-keys-and-oauth). ```bash [Terminal] curl https://api.getpraxen.app/v1/workspaces \ -H "x-api-key: $PRAXEN_API_KEY" ``` ## Response format Every JSON response uses the same envelope. | Field | Description | | --------- | -------------------------------------------------------------------------------------------------------- | | `success` | `true` when the request succeeded, `false` when it failed. | | `message` | On success, an object whose `message` describes the status. `null` on failure. | | `error` | `null` on success. On failure, an object with a `message`, an optional `detail` and optional `metadata`. | | `result` | The payload on success. Absent on failure. | ```json { "success": true, "message": { "message": "Successful request" }, "error": null, "result": { "items": [], "count": 0 } } ``` ## Rate limits | Surface | Limit | | ------------------- | -------------------------------------------- | | REST API | 5,000 requests per 60 seconds per credential | | Platform MCP server | 600 requests per 60 seconds per credential | Responses advertise the policy in the `RateLimit-Limit` and `RateLimit-Policy` headers. Over the limit, the API answers `429` with a `Retry-After` header carrying the window in seconds; back off until it elapses, then retry. Every operation is also callable from the [CLI](https://docs.getpraxen.app/tools/cli), which is generated from the same specification. ## Related - [API keys and OAuth clients](https://docs.getpraxen.app/administration/api-keys-and-oauth) to create the credentials these requests use. - [CLI](https://docs.getpraxen.app/tools/cli) to call the API from a terminal or a script. - [Platform MCP server](https://docs.getpraxen.app/tools/platform-mcp) to reach the same data from an editor agent.