potpie Documentation

Context Graph for AI Native SDLC

RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy potpie on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run)
docker run -d --name potpie -p 3010:3010 --restart always potpie-ai/potpie:latest
Configured Services & Ports
โš™๏ธ api
image: build locally
๐Ÿ”Œ Ports: ${DAYTONA_DASHBOARD_PORT:-3010}:3000
โš™๏ธ dex
image: build locally
docker-compose.yml
yaml (docker-compose.yml)
# Layered on top of /Users/nandan/Desktop/Dev/daytona/docker/docker-compose.yaml
# by scripts/setup-daytona-local.sh.
#
# Two changes:
#   1. Move the Daytona dashboard host port from 3000 to ${DAYTONA_DASHBOARD_PORT}
#      (default 3010) so port 3000 is free for the potpie frontend dev server.
#      Inside the container the API still listens on 3000, so service-to-service
#      URLs (`http://api:3000/api`) are untouched.
#   2. Replace the dex config bind with our copy that whitelists the new
#      `http://localhost:${DAYTONA_DASHBOARD_PORT}` redirect URIs in the
#      daytona OIDC client. Without this, dashboard login fails with
#      `invalid_redirect_uri` after the port move.
#
# `!override` is required for both fields. Compose merges list fields by
# default (appending), which would leave the original `3000:3000` mapping live
# and the unwanted dex config still mounted.

services:
  api:
    ports: !override
      - "${DAYTONA_DASHBOARD_PORT:-3010}:3000"
    # The API container does string substitution into the dashboard's built JS
    # at startup using DASHBOARD_BASE_API_URL (replaces %DAYTONA_BASE_API_URL%
    # in main.ts) and emits dashboardUrl in /api/config from DASHBOARD_URL.
    # Both default to localhost:3000 in upstream โ€” point them at the host port
    # we exposed above, otherwise the dashboard at localhost:3010 will try to
    # call localhost:3000/api and fail with `TypeError: Failed to fetch`.
    environment:
      DASHBOARD_URL: http://localhost:${DAYTONA_DASHBOARD_PORT:-3010}/dashboard
      DASHBOARD_BASE_API_URL: http://localhost:${DAYTONA_DASHBOARD_PORT:-3010}
      # Local-dev permissiveness: the runner runs on the same Docker VM that
      # also hosts Postgres, Redis, MinIO, etc. Memory routinely sits in the
      # 80-90% range, which drags the runner's `availabilityScore` below the
      # upstream default threshold of 10 โ†’ sandbox creation fails with
      # `No available runners`. Lowering the threshold to 1 lets the runner
      # be picked even under memory pressure (the score is also used to rank
      # multiple runners โ€” single-runner local dev doesn't need the gate).
      # Bump RAM in Docker Desktop / Colima for the durable fix.
      RUNNER_AVAILABILITY_SCORE_THRESHOLD: "1"
      RUNNER_DECLARATIVE_BUILD_SCORE_THRESHOLD: "1"
      # Daytona's upstream compose hard-codes `proxy.localhost:4000` as the
      # toolbox/preview hostname, which is fine when consumers run inside the
      # daytona-network (where Docker DNS resolves it) but breaks our potpie
      # worker that runs on the macOS host. macOS's resolver doesn't map
      # `proxy.localhost` to 127.0.0.1, so SDK calls die with NameResolutionError.
      # Re-point the API at plain `localhost:4000` (the proxy is published on
      # the host at that port already) so URLs the API returns are reachable.
      # Sandbox preview URLs `-.localhost:4000` work too โ€”
      # macOS Sequoia resolves `*.localhost` via mDNS to 127.0.0.1.
      PROXY_DOMAIN: localhost:4000
      PROXY_TEMPLATE_URL: http://{{PORT}}-{{sandboxId}}.localhost:4000
    # Upstream's substitution only replaces the `%DAYTONA_BASE_API_URL%`
    # placeholder, but the dashboard is built with `VITE_API_URL=http://localhost:3000/api`
    # baked in via Vite โ€” that becomes a literal `BASE_PATH = "http://localhost:3000"`
    # in the OpenAPI client and is the actual URL the dashboard fetches from.
    # Re-write the literal in the bundled JS at startup before nest boots.
    # `$$` escapes the `$` so compose passes the variable through to the shell.
    entrypoint:
      - /bin/sh
      - -c
      - |
        target_url="$${DASHBOARD_BASE_API_URL:-http://localhost:3000}"
        if [ "$$target_url" != "http://localhost:3000" ]; then
          find /daytona/dist/apps/dashboard -type f -name '*.js' \
            -exec sed -i "s|http://localhost:3000|$$target_url|g" {} +
        fi
        exec node dist/apps/api/main.js

  dex:
    volumes: !override
      - ${POTPIE_SANDBOX_DIR:?set by setup-daytona-local.sh}/scripts/daytona-overrides/dex-config.yaml:/etc/dex/config.yaml
      - dex_db:/var/dex

File: README.md

Potpie turns your codebase and software development lifecycle into a living context graph for AI agents.
It indexes code, structure, decisions, source history, team knowledge and engineering workflows, so agents can answer questions, plan changes, debug failures, and write code with project-specific context.

Install and setup Potpie

Step 1: install the CLI through [PyPI](https://pypi.org/project/potpie/) with `uv` or `pip`:

bash
uv tool install potpie

or:

bash
python3 -m pip install --user potpie

[!NOTE]
uv tool install potpie is recommended for CLI installs because global
mutation of Python packages is generally not recommended.

Step 2: Run the Potpie setup wizard

bash
potpie setup

The setup wizard provisions local config, storage, the daemon, a default pot, and
agent skills. It also lets you choose integrations and the coding harness Potpie
should configure.

Step 3: Open your configured harness

Potpie is already integrated into your selected harness.
You can start using Potpie with the repo of your choice.

Open your previously selected harness and ask it to use Potpie for the repo.

[!NOTE]
You don't need to run a separate manual ingest command. The CLI registers
sources and the configured agent can ingest or update project context when the
task requires it.

You can view your context graph in the web UI:

bash
potpie ui

This will open a graph explorer in your browser.

Basic CLI user checklist

The main CLI commands are:

Command Purpose
potpie setup Run first-time local setup for config, daemon, default pot, and agent skills.
potpie login Sign in to Potpie for account-backed and managed features.
potpie github login / potpie linear login Connect source integrations you want agents to use.
potpie status Show context readiness for the active pot, including daemon, graph, and skill checks.
potpie auth status Show configured integration auth status.
potpie auth status --verify Verify integration credentials with lightweight API checks.
potpie doctor Run local diagnostics for daemon, backend capabilities, and skill drift.
potpie source add repo . Register the current repo as a source for the resolved pot.
potpie pot list / potpie pot use List pots and choose the active workspace.
potpie resolve "<task>" Pull the context an agent should read before doing a task.
potpie search "<query>" Look up a specific file, workflow, bug, decision, or convention.
potpie record --type <type> --summary "" Write a durable project learning.
potpie graph ... Use lower-level graph reads, quality checks, proposals, and commits.
potpie ui Open the local graph explorer served by the daemon.
potpie skills install --agent <agent> Install or refresh Potpie guidance for an agent harness.

Examples:

bash
potpie setup --repo . --agent claude
potpie github login
potpie auth status
potpie status
potpie source add repo .
potpie resolve "what should I know before working in this repository?"
potpie search "authentication flow"
potpie record --type decision --summary "Prefer the Potpie CLI for graph work"

You can find an exhaustive list with more examples in our docs.

Integrations and Coding Harnesses

Potpie supports a variety of integrations and coding harnesses, with more coming.
If your team needs a new integration or harness, please
raise a ticket.

Integrations

Tool Description
GitHub Index repositories, pull requests, issues, reviews and source history.
Linear Index teams, issues, projects and documents.
Jira Index projects, issues, status and changelog context.
Confluence Index spaces, pages, runbooks and decisions.

Coding harnesses

Tool Description
Claude Code Install Potpie instructions and skills for Claude Code.
OpenAI Codex Install Potpie instructions and skills for OpenAI Codex.
Cursor Install Potpie instructions and skills for Cursor.
OpenCode Install Potpie skills for OpenCode.

Architecture

Potpie's current architecture is CLI-first. CLI is designed to be used by both humans and agents. Read the deeper architecture notes in docs/context-graph/architecture.md.

License

This project is licensed under the Apache 2.0 License. See LICENSE.

Community & Support

  • GitHub Issues: bugs and repository-scoped requests
  • Discord: community discussion and support
  • Docs: setup, product guides, and integration details

New contributions are always welcome. Read the Contributing Guide
to set up your environment, understand the workflow, and open a pull request.


File: docs/index.md


title: Potpie

Overview

Potpie turns your codebase and software development lifecycle into a living context graph for AI agents.
It indexes code, structure, decisions, source history, team knowledge and engineering workflows, so agents can answer questions, plan changes, debug failures, and write code with project-specific context.

Start here

Architecture

Potpie's current architecture is CLI-first. CLI is designed to be used by both humans and agents. Read the deeper architecture notes in Context graph architecture.

License

This project is licensed under the Apache 2.0 License. See LICENSE.

Community and support

  • GitHub Issues: bugs and repository-scoped requests
  • Discord: community discussion and support
  • Docs: setup, product guides, and integration details

New contributions are always welcome. Read the Contributing Guide
to set up your environment, understand the workflow, and open a pull request.