GitHub Go Monthly Trending Repositories

alibaba/open-code-review

Fast, efficient, battle-tested at Alibaba's scale. Hybrid architecture code review tool: deterministic pipelines + LLM Agent, precise line-level comments, built-in multi-language ruleset (NPE, thread-safety, XSS, SQL injection), OpenAI & Anthropic compatible.

OpenCodeReview

English | 简体中文 | 日本語 | 한국어 | Русский

What is Open Code Review?

Open Code Review is an AI-powered code review CLI tool. It originated as Alibaba Group's internal official AI code review assistant — over the past two years, it has served tens of thousands of developers and identified millions of code defects. After thorough validation at massive scale, we incubated it into an open source project for the community. Simply configure a model endpoint to get started.

It reads Git diffs, sends changed files to a configurable LLM via an agent with tool-use capabilities, and generates structured review comments with line-level precision. The agent can read full file contents, search the codebase, inspect other changed files for context, and produce deep reviews — not just surface-level diff feedback. Beyond diff review, ocr scan reviews entire files for auditing unfamiliar codebases or directories that have no meaningful diff.

Visit the official website for more details.

Benchmark

Compared to general-purpose agents (Claude Code), Open Code Review achieves significantly higher Precision and F1 with the same underlying model, while consuming only ~1/9 of the tokens and completing reviews faster. Note that its Recall is lower than general-purpose agents — a deliberate trade-off favoring precision over noise.

A real-world code review benchmark built from 50 popular open-source repositories, 200 real Pull Requests, and 10 programming languages — cross-validated by 80+ senior engineers (1,505 annotated ground-truth issues).

Explore the AACR-Bench dataset on Hugging Face.

Metric	What it measures	Why it matters
F1	Harmonic mean of precision and recall	Best single number for overall review quality
Precision	Proportion of reported issues that are real defects	Higher = fewer false alarms to triage
Recall	Proportion of real defects that are found	Higher = fewer issues slip through review
Avg Time	Wall-clock time per review	Matters for CI pipeline latency
Avg Token	Total tokens consumed per review	Directly impacts API cost

Why Open Code Review?

The Problem with General-Purpose Agents

If you've used general-purpose agents like Claude Code with Skills for code review, you've likely encountered these pain points:

Incomplete coverage — On larger changesets, agents tend to "cut corners," selectively reviewing only some files and missing others.
Position drift — Reported issues frequently don't match the actual code location, with line numbers or file references drifting off target.
Unstable quality — Natural-language-driven Skills are hard to debug, and review quality fluctuates significantly with minor prompt variations.

The root cause: a purely language-driven architecture lacks hard constraints on the review process.

Core Design: Deterministic Engineering × Agent Hybrid

Open Code Review's core philosophy is to combine deterministic engineering with an agent, each handling what it does best.

Deterministic Engineering — Hard Constraints

For review steps that must not go wrong, engineering logic — not the language model — guarantees correctness:

Precise file selection — Determines exactly which files need review and which should be filtered, ensuring no important change is missed.
Smart file bundling — Groups related files into a single review unit (e.g., message_en.properties and message_zh.properties are bundled together). Each bundle runs as a sub-agent with isolated context — a divide-and-conquer strategy that stays stable on very large changesets and naturally supports concurrent review.
Fine-grained rule matching — Matches review rules to each file's characteristics, keeping the model's attention sharply focused and eliminating information noise at the source. Compared to purely language-driven rule guidance, template-engine-based rule matching is more stable and predictable.
External positioning and reflection modules — Independent comment-positioning and comment-reflection modules systematically improve both the location accuracy and content accuracy of AI feedback.

Agent — Dynamic Decision-Making

The agent's strengths are concentrated where they matter most — dynamic decisions and dynamic context retrieval:

Scenario-tuned prompts — Prompt templates deeply optimized for code review, improving effectiveness while reducing token consumption.
Scenario-tuned toolset — Distilled from deep analysis of tool-call traces in large-scale production data — including call frequency distributions, per-tool repetition rates, and the impact of new tools on the overall call chain — resulting in a purpose-built toolset that is more stable and predictable for code review than a generic agent toolkit.

How to Use

Prerequisites

Git >= 2.41 — Open Code Review relies on Git for diff generation, code search, and repository operations.

CLI

Install

npm install -g @alibaba-group/open-code-review

After installation, the ocr command is available globally.

For other installation methods (install script, GitHub Release binary, from source), see Installation.

Quick Start

1. Configure LLM

You must configure an LLM before reviewing code, unless you use Delegation Mode.

ocr config provider          # Select a built-in provider or add a custom one
ocr config model             # Pick a model for the active provider

The interactive UI guides you through provider selection, API key entry, and model configuration, then automatically tests connectivity.

For CLI setup, environment variables, custom providers, and other advanced configuration, see Configuration.

2. Review

cd your-project

# Workspace mode — review all staged, unstaged, and untracked changes
ocr review

# Branch range — reviews feature-branch's changes since it diverged from main (merge-base mode)
ocr review --from main --to feature-branch

# Single commit
ocr review --commit abc123

# Resume an interrupted range or commit review
ocr session list
ocr review --from main --to feature-branch --resume <session-id>

# Full-file scan — review whole files instead of a diff (no git history needed)
ocr scan                          # scan the entire repository
ocr scan --path internal/agent    # scan a directory or specific files
ocr scan --resume <session-id>   # resume an interrupted full-file scan

# Delegation mode — let your AI coding agent perform the review itself
# OCR handles file selection and rule resolution; no LLM configuration needed
ocr delegate preview
ocr delegate rule src/main.go src/handler.go

Documentation

Full documentation lives at open-codereview.ai/docs:

Quickstart — install and run your first review
Installation — all platforms and package managers
CLI Reference — every command and flag
Review Rules — customize review rules with path filtering and targeting
Configuration — config keys and environment variables
MCP Server — extend the review agent with external tools
Coding Agent Integrations — choose the platform you use
- Claude Code — install a plugin with review slash commands
- Codex — install a plugin with callable review skills
- Cursor — install a plugin with portable review skills
- OpenCode — install native review tools and slash commands
- QCA Forward — run delegation mode with the QCA host model and a ready-to-publish template
- Skill-compatible agents — install the portable agent skill
Review Execution Modes — after integration, choose which LLM performs the review
- Default (OCR-managed) — OCR runs the review using its configured LLM
- Delegation Mode — your coding agent runs the review using its own LLM; no OCR API key required
CI/CD Integration — GitHub Actions, GitLab CI, GitFlic CI, and Gerrit integration
Session Viewer — browse and replay review sessions in browser
Telemetry — OpenTelemetry integration for observability
FAQ — common questions and troubleshooting

Contributing

This project exists thanks to all the people who contribute. See CONTRIBUTING.md for development setup, coding guidelines, and how to submit pull requests.

License

ltaoo/wx_channels_download

微信视频号下载器

体积小、使用简单、支持 macOS 和 Windows 系统。

使用说明

下载构建包，以管理员身份运行，首次打开会自动安装证书，然后启动服务。

当终端提示「代理服务启动成功」就说明可以使用了。

已安装证书会跳过安装证书步骤。

打开微信 PC 端，点击需要下载的视频，在视频下方的操作按钮一栏，会多出一个下载按钮，如下所示

如果没有，在页面侧边或底部会有悬浮按钮，拥有相同的功能

首页推荐	视频详情页

等待视频开始播放，然后暂停视频，点击下载按扭即可下载视频。下载成功后，会在上方显示已下载的文件，下载文件名最后面会标志该视频质量。

下载按钮默认会下载视频号默认质量的视频（即当前播放的视频，一般都是体积最小的），可以在下拉菜单下载其他质量的视频

开发说明

先以管理员身份启动终端，然后 go run main.go 即可。

打包

参考 build/build.sh 脚本。

感谢

前端解密部分参考自
https://github.com/kanadeblisst00/WechatVideoSniffer2.0

后端解密代码来自
https://github.com/Hanson/WechatSphDecrypt

⚠️ 免责声明

本项目为开源项目
仅用于技术交流学习和研究的目的
请遵守法律法规,请勿用作任何非法用途
否则造成一切后果自负
若您下载并使用即视为您知晓并同意

cli/cli

GitHub’s official command line tool

GitHub CLI

gh is GitHub on the command line. It brings pull requests, issues, and other GitHub concepts to the terminal next to where you are already working with git and your code.

GitHub CLI is supported for users on GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server 2.20+ with support for macOS, Windows, and Linux.

Documentation

For installation options see below, for usage instructions see the manual.

Agent skills

An agent skill is available for driving gh from coding agents. Install or update it with the built-in gh skill command:

# Install the skill (user scope recommended)
gh skill install cli/cli gh --scope user

# Update the skill after a `gh` release
gh skill update gh

Contributing

If anything feels off or if you feel that some functionality is missing, please check out the contributing page. There you will find instructions for sharing your feedback, building the tool locally, and submitting pull requests to the project.

If you are a hubber and are interested in shipping new commands for the CLI, check out our doc on internal contributions

Installation

macOS

For additional macOS packages and installers, see community-supported docs

Linux & Unix

For additional Linux & Unix packages and installers, see community-supported docs

Windows

For additional Windows packages and installers, see community-supported docs

Build from source

See here on how to build GitHub CLI from source.

GitHub Codespaces

To add GitHub CLI to your codespace, add the following to your devcontainer file:

"features": {
  "ghcr.io/devcontainers/features/github-cli:1": {}
}

GitHub Actions

GitHub-hosted runners have the GitHub CLI pre-installed, which is updated weekly.

If a specific version is needed, your GitHub Actions workflow will need to install it based on the macOS, Linux & Unix, or Windows instructions above.

For information on all pre-installed tools, see actions/runner-images

Verification of binaries

Starting with v2.93.0, releases of gh are published as immutable releases. For more information, see Immutable releases.

Since version 2.50.0, gh has been producing Build Provenance Attestation, enabling a cryptographically verifiable paper-trail back to the origin GitHub repository, git revision, and build instructions used. The build provenance attestations are signed and rely on Public Good Sigstore for PKI.

There are two common ways to verify a downloaded release, depending on whether gh is already installed or not. If gh is installed, it's trivial to verify a new release:

Option 1: Using gh if already installed:

$ gh at verify -R cli/cli gh_2.62.0_macOS_arm64.zip
Loaded digest sha256:fdb77f31b8a6dd23c3fd858758d692a45f7fc76383e37d475bdcae038df92afc for file://gh_2.62.0_macOS_arm64.zip
Loaded 1 attestation from GitHub API
✓ Verification succeeded!

sha256:fdb77f31b8a6dd23c3fd858758d692a45f7fc76383e37d475bdcae038df92afc was attested by:
REPO     PREDICATE_TYPE                  WORKFLOW
cli/cli  https://slsa.dev/provenance/v1  .github/workflows/deployment.yml@refs/heads/trunk

Option 2: Using Sigstore cosign:

To perform this, download the attestation for the downloaded release and use cosign to verify the authenticity of the downloaded release:

$ cosign verify-blob-attestation --bundle cli-cli-attestation-3120304.sigstore.json \
      --new-bundle-format \
      --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
      --certificate-identity="https://github.com/cli/cli/.github/workflows/deployment.yml@refs/heads/trunk" \
      gh_2.62.0_macOS_arm64.zip
Verified OK

Comparison with hub

For many years, hub was the unofficial GitHub CLI tool. gh is a new project that helps us explore what an official GitHub CLI tool can look like with a fundamentally different design. While both tools bring GitHub to the terminal, hub behaves as a proxy to git, and gh is a standalone tool. Check out our more detailed explanation to learn more.

gastownhall/beads

Beads - A memory upgrade for your coding agent

bd - Beads

Distributed graph issue tracker for AI agents, powered by Dolt.

Platforms: macOS, Linux, Windows, FreeBSD

Docs: https://beads.gascity.com/

Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context.

flowchart LR
    create["bd create<br/>new bead"] --> depgraph["dependency<br/>graph"]
    depgraph --> ready["bd ready<br/>claimable work"]
    ready --> claim["bd update --claim<br/>agent takes it"]
    claim --> close["bd close<br/>work done"]
    close -->|blockers released| ready
    depgraph <-->|"bd dolt push / pull"| remote[("other machines<br/>and agents")]

⚡ Quick Start

# Install beads CLI (system-wide - don't clone this repo into your project)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

# Initialize in YOUR project
cd your-project
bd init

# Optional: refresh or install richer instructions for your agent
bd setup codex    # Codex CLI - installs skill, AGENTS.md guidance, and hooks
bd setup claude   # Claude Code - installs hooks/settings
bd setup factory  # Factory.ai Droid - creates/updates AGENTS.md

Note: Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project.

bd init creates or updates AGENTS.md by default so agents can discover the beads workflow, and also installs project Claude/Codex integrations unless you pass --skip-agents or --stealth. Use bd setup --list to see supported integrations, including bd setup codex, bd setup factory, bd setup claude, bd setup mux, bd setup cursor, and more. See Agent and IDE setup.

Manual copy-paste is only for unsupported agents, existing projects where you cannot rerun bd init/bd setup, or custom instruction files. In those cases, run bd onboard and paste the printed snippet into the file your agent reads.

If your agent is not covered by bd setup, add this minimal AGENTS.md section:

This project uses bd (beads) for issue tracking.

- Run `bd prime` for workflow context and command guidance.
- Use `bd ready`, `bd show <id>`, `bd update <id> --claim`, and `bd close <id>`.
- Use `bd remember "insight"` for persistent project memory; do not create MEMORY.md files.
- Do not use markdown TODO lists for task tracking.

🛠 Features

Dolt-Powered: Version-controlled SQL database with cell-level merge, native branching, and built-in sync via Dolt remotes.
Agent-Optimized: JSON output, dependency tracking, and auto-ready task detection.
Zero Conflict: Hash-based IDs (bd-a1b2) prevent merge collisions in multi-agent/multi-branch workflows.
Compaction: Semantic "memory decay" summarizes old closed tasks to save context window.
Messaging: Message issue type with threading (--thread), ephemeral lifecycle, and mail delegation.
Graph Links: relates-to, duplicates, supersedes, and replies-to for knowledge graphs.

📖 Essential Commands

Command	Action
`bd ready`	List tasks with no open blockers.
`bd create "Title" -p 0`	Create a P0 task.
`bd update <id> --claim`	Atomically claim a task (sets assignee + in_progress).
`bd dep add <child> <parent>`	Link tasks (blocks, related, parent-child).
`bd show <id>`	View task details and audit trail.
`bd prime`	Print agent workflow context and persistent memories.
`bd remember "insight"`	Store project memory that `bd prime` injects later.

🔗 Hierarchy & Workflow

Beads supports hierarchical IDs for epics:

bd-a3f8 (Epic)
bd-a3f8.1 (Task)
bd-a3f8.1.1 (Sub-task)

Stealth Mode: Run bd init --stealth to use Beads locally without committing files to the main repo. Perfect for personal use on shared projects. See Git-Free Usage below.

Contributor vs Maintainer: When working on open-source projects:

Contributors (forked repos): Run bd init --contributor to route planning issues to a separate repo (e.g., ~/.beads-planning). Keeps experimental work out of PRs.
Maintainers (write access): Beads auto-detects maintainer role via SSH URLs or HTTPS with credentials. Only need git config beads.role maintainer if using GitHub HTTPS without credentials but you have write access.

📦 Installation

brew install beads           # macOS / Linux (recommended)
npm install -g @beads/bd     # Node.js users

Other methods: install script | go install | from source | Windows | Arch AUR

Requirements: macOS, Linux, Windows, or FreeBSD. See docs/getting-started/installation.md for complete installation guide.

Upgrading? Replacing the binary is not always the whole story. Short version: sync remote-backed databases with your current bd, back up with bd export --all, upgrade the binary, then run bd info --whats-new, bd hooks install, and bd version. If the upgrade crosses a schema migration on a remote-backed database, exactly one designated clone runs bd migrate and bd dolt push; other clones install the new binary and run bd bootstrap. See the full upgrade guide or docs/getting-started/installation.md.

Security And Verification

Before trusting any downloaded binary, verify its checksum against the release checksums.txt.

The install scripts verify release checksums before install. For manual installs, do this verification yourself before first run.

On macOS, scripts/install.sh preserves the downloaded signature by default. Local ad-hoc re-signing is explicit opt-in via BEADS_INSTALL_RESIGN_MACOS=1.

See docs/reference/antivirus.md for Windows AV false-positive guidance and verification workflow.

💾 Storage Modes

Beads uses Dolt as its database. Two modes:

Embedded (default) — bd init. Dolt runs in-process, data lives in .beads/embeddeddolt/, single writer. Recommended for most users.
Server — bd init --server. Connects to an external dolt sql-server for multiple concurrent writers; data lives in .beads/dolt/.

Cross-machine sync uses bd dolt push / bd dolt pull against refs/dolt/data on your git remote; .beads/issues.jsonl is an export for viewers and interchange, not the source of truth or a backup. Back up and migrate between modes with bd backup; reclaim space with bd prune / bd purge.

Full detail — connection flags, sockets, maintenance, backup, and migration — in the Dolt backend guide.

Schema Version Guard

bd checks the database schema version at open time. If the database has been migrated by a newer binary and an older binary tries to open it, bd exits with an actionable error rather than issuing queries that fail with cryptic SQL errors:

schema version mismatch: database is at v45, binary knows up to v42 (3 migrations ahead)

  Your bd binary is stale. Queries for dropped or renamed columns will fail
  with cryptic SQL errors (e.g. "column X could not be found in any table in scope").

  Rebuild from main:
    CGO_ENABLED=0 go build -tags gms_pure_go ./cmd/bd

  Or install the latest release:
    CGO_ENABLED=0 go install -tags gms_pure_go github.com/steveyegge/beads/cmd/bd@latest

  To proceed despite the risk (some read commands may still work):
    BD_IGNORE_SCHEMA_SKEW=1 bd <command>
    bd --ignore-schema-skew <command>

When this fires: only when the database schema is ahead of the binary (a newer binary migrated the database; this binary doesn't know those migrations). Normal upgrades, where the binary migrates the database forward, are unaffected.

Escape hatch: BD_IGNORE_SCHEMA_SKEW=1 (or --ignore-schema-skew) bypasses the guard with a warning on stderr. Use this only if you know the forward migrations are additive and safe for your specific workload.

🌐 Community Tools

See docs/community-tools.md for a curated list of community-built UIs, extensions, and integrations—including terminal interfaces, web UIs, editor extensions, and native apps.

See docs/related-projects.md for adjacent or complementary projects that solve different problems in the same neighborhood.

🚀 Git-Free Usage

Beads works without git. The Dolt database is the storage backend — git integration (hooks, repo discovery, identity) is optional.

# Initialize without git
export BEADS_DIR=/path/to/your/project/.beads
bd init --quiet --stealth

# All core commands work with zero git calls
bd create "Fix auth bug" -p 1 -t bug
bd ready --json
bd update bd-a1b2 --claim
bd prime
bd close bd-a1b2 "Fixed"

BEADS_DIR tells bd where to put the .beads/ database directory, bypassing git repo discovery. --stealth sets no-git-ops: true in config, disabling all git hook installation and git operations.

This is useful for:

Non-git VCS (Sapling, Jujutsu, Piper) — no .git/ directory needed
Monorepos — point BEADS_DIR at a specific subdirectory
CI/CD — isolated task tracking without repo-level side effects
Evaluation/testing — ephemeral databases in /tmp

📝 Documentation

Documentation site | Installing | Sync Concepts | Agent Workflow | Copilot CLI Setup | Copilot VS Code MCP | Articles | Sync Branch Mode | Troubleshooting | FAQ

tailscale/tailscale

The easiest, most secure way to use WireGuard and 2FA.

Tailscale

https://tailscale.com

Private WireGuard® networks made easy

Overview

This repository contains the majority of Tailscale's open source code. Notably, it includes the tailscaled daemon and the tailscale CLI tool. The tailscaled daemon runs on Linux, Windows, macOS, and to varying degrees on FreeBSD and OpenBSD. The Tailscale iOS and Android apps use this repo's code, but this repo doesn't contain the mobile GUI code.

Other Tailscale repos of note:

the Android app is at https://github.com/tailscale/tailscale-android
the Synology package is at https://github.com/tailscale/tailscale-synology
the QNAP package is at https://github.com/tailscale/tailscale-qpkg
the Chocolatey packaging is at https://github.com/tailscale/tailscale-chocolatey

For background on which parts of Tailscale are open source and why, see https://tailscale.com/opensource/.

Using

We serve packages for a variety of distros and platforms at https://pkgs.tailscale.com.

Other clients

The macOS, iOS, and Windows clients use the code in this repository but additionally include small GUI wrappers. The GUI wrappers on non-open source platforms are themselves not open source.

Building

We always require the latest Go release, currently Go 1.26. (While we build releases with our Go fork, its use is not required.)

go install tailscale.com/cmd/tailscale{,d}

If you're packaging Tailscale for distribution, use build_dist.sh instead, to burn commit IDs and version info into the binaries:

./build_dist.sh tailscale.com/cmd/tailscale
./build_dist.sh tailscale.com/cmd/tailscaled

If your distro has conventions that preclude the use of build_dist.sh, please do the equivalent of what it does in your distro's way, so that bug reports contain useful version information.

Bugs

Please file any issues about this code or the hosted service on the issue tracker.

Contributing

PRs welcome! But please file bugs. Commit messages should reference bugs.

We require Developer Certificate of Origin Signed-off-by lines in commits.

See commit-messages.md (or skim git log) for our commit message style.

About Us

Tailscale is primarily developed by the people at https://github.com/orgs/tailscale/people. For other contributors, see:

Legal

WireGuard is a registered trademark of Jason A. Donenfeld.

chenyme/grok2api

Multi-account API gateway for Grok Build, Grok Web, and Grok Console

A multi-account API gateway for Grok Build, Grok Web, and Grok Console

English | 简体中文

Tip

Check out DEEIX-AI / DEEIX-Chat, a lightweight, integrated AI platform for model routing, chat, files, tools, billing, identity, and operations.

Note

This project is for technical research and learning purposes only. Please comply with Grok's official terms of use and local laws when using it; otherwise, you will be solely responsible for all consequences!

Overview

Grok2API is a Go gateway with a built-in React admin console. It manages independent Grok Build, Grok Web, and Grok Console account pools and exposes unified OpenAI- and Anthropic-compatible APIs.

Architecture

flowchart LR
    %% Color definitions
    classDef access fill:#e1f5fe,stroke:#01579b
    classDef core fill:#fff3e0,stroke:#e65100
    classDef providers fill:#f3e5f5,stroke:#4a148c
    classDef infra fill:#e8f5e9,stroke:#1b5e20
    classDef upstream fill:#fce4ec,stroke:#880e4f

    subgraph Access["Access Domain"]
        direction LR
        Clients["API Clients"]
        Admin["React Admin"]
    end

    subgraph Core["Gateway Core Domain"]
        direction LR
        Management["Management Services<br/>Accounts · Models · Keys · Settings"]
        Sync["Account Sync<br/>Credentials · Quota · Models"]
        Gateway["Gateway Service<br/>Protocols · Routing · Selection · Retry"]
        Audit["Audit Service<br/>Usage · Client Billing"]
        Management --> Sync
        Gateway -.-> Audit
    end

    subgraph Providers["Provider Channel Domain"]
        direction LR
        Registry["Provider Registry"]
        Build["Grok Build<br/>OAuth · Dynamic Models · Billing"]
        Web["Grok Web<br/>SSO · Remote Quota · Media"]
        Console["Grok Console<br/>SSO · Local Window · Stateless"]
        Registry --> Build
        Registry --> Web
        Registry --> Console
    end

    subgraph Infra["Shared Infrastructure Domain"]
        direction LR
        Egress["Egress Manager<br/>Scopes · Proxy Pool · Fallback · Clearance"]
        Database[("SQLite / PostgreSQL")]
        Runtime[("Memory / Redis")]
    end

    Upstream["🌐 Grok Upstream"]

    %% Cross-domain calls
    Clients --> Gateway
    Admin --> Management
    Gateway --> Registry
    Sync --> Registry
    Build -->|grok_build| Egress
    Web -->|grok_web / asset| Egress
    Console -->|grok_console| Egress
    Egress --> Upstream
    Management --> Database
    Audit --> Database
    Gateway <--> Runtime

    %% Application styles
    class Clients,Admin access
    class Management,Sync,Gateway,Audit core
    class Registry,Build,Web,Console providers
    class Egress,Database,Runtime infra
    class Upstream upstream

The Gateway routes requests through the Provider Registry. Account Sync refreshes credentials, quota, and models. Each Provider keeps independent account state and uses an isolated egress scope; usage, audits, and client billing are finalized after the request.

Core capabilities

Area	Capabilities
APIs	Responses, Chat Completions, Anthropic Messages, Images, and asynchronous Videos
Clients	Codex, Claude Code, OpenAI-compatible SDKs, and Anthropic-compatible SDKs
Accounts	Bulk import/export, quota sync, credential renewal, conversion, tools, and cleanup
Routing	Model discovery, Provider pinning, sticky sessions, quota/concurrency guards, and bounded failover
Sessions	Stored responses, compact, prompt-cache affinity, and optional reasoning replay
Media	Image generation/editing, video jobs, local archiving, and URL/Base64/SSE output
Egress	HTTP/SOCKS/Resin and Trojan/VLESS/Shadowsocks/VMess tunnels, subscriptions, probes, proxy pools, allocation, fallback, and FlareSolverr
Operations	Dashboard, model routes, client keys, audits, runtime settings, and media libraries

Provider boundaries

Provider	Authentication	Models	Main capabilities
Grok Build	OAuth / Device OAuth	Discovered per account	Responses, Chat, Messages, compact, stored responses, paid-account video
Grok Web	SSO	Built-in, filtered by tier	Responses, Chat, Messages, stored responses, images, image editing, video
Grok Console	SSO	Built-in	Stateless Responses, Chat, Messages, images, image editing, video, TTS, STT, Realtime

Each Provider keeps its own credentials, quota, health, cooldown, concurrency, and model capabilities. Account retries stay within one route; when one public model ID intentionally aggregates multiple routes, the gateway may select another schedulable route without mixing Provider state.

Quick start

Official images support linux/amd64 and linux/arm64.

git clone https://github.com/chenyme/grok2api.git
cd grok2api
cp config.example.yaml config.yaml

Generate secrets and place them in config.yaml:

openssl rand -hex 32
openssl rand -base64 32

secrets:
  jwtSecret: "replace-with-the-generated-hex-value"
  credentialEncryptionKey: "replace-with-the-generated-base64-key"

bootstrapAdmin:
  username: "admin"
  password: "replace-with-a-strong-password"

Start the service:

docker compose pull
docker compose up -d
docker compose logs -f grok2api

Open http://127.0.0.1:8000. The image already includes the frontend; SQLite data and local media are stored in the Compose volume.

Run from source

cp config.example.yaml config.yaml
make run

For frontend development:

cd frontend
pnpm install
pnpm dev

Set up the gateway

Sign in with the bootstrap administrator.
Connect a Build, Web, or Console account.
Wait for its quota and model capabilities to sync.
Review the public routes under Model Routes.
Create a client key under Client Keys.
Call a /v1/* endpoint with that key.

After first sign-in, change the administrator password and remove bootstrapAdmin from the configuration. Never rotate credentialEncryptionKey after credentials have been stored.

Account operations

Provider	Connect or import	Export
Build	Device OAuth, JSON/JSONL	Re-importable account file
Web	Pasted/TXT SSO, JSON/JSONL	Re-importable account file
Console	Pasted/TXT SSO, JSON/JSONL	Re-importable account file

Imports accept UTF-8 BOM. Bulk quota sync, Build credential renewal, Web→Build/Console conversion, account tools, and cleanup report live progress.

Web account tools can accept the terms, set a random birthday corresponding to an age of 20–40, and enable NSFW. Completed steps are recorded and skipped on later runs.

Automatic deletion of old reauthRequired accounts is available but disabled by default. Active inference leases and video jobs are protected.

Tip

To migrate from the Python version, export Grok Web SSO tokens as TXT and import them under Grok Web. Old pool metadata and databases are not compatible.

Models and routing

Build models are discovered from each account's actual capabilities. Web and Console use built-in catalogs. The Model Routes page shows Provider-qualified routes, endpoint capabilities, and supporting-account counts; clients should treat the currently serviceable results from GET /v1/models as authoritative.

Grok Build

Build does not use one global static model list. Account synchronization reads the upstream /models endpoint, and different accounts, subscription tiers, or staged rollouts may expose different models. Routing retains these per-account capabilities instead of replacing the global catalog with one account's response.

Model	Type	Availability	Gateway surfaces
Conversation models returned by upstream `/models` (for example, `grok-4.5`)	Conversation	Returned by the selected account	Chat Completions, Responses, Messages, compact, stored responses
`grok-composer-2.5-fast`	Conversation	Grok Build OAuth accounts	Chat Completions, Responses, Messages; supplemented from the OAuth session contract when a sparse upstream catalog omits it
`grok-imagine-video-1.5`	Video	Super/paid Build accounts	Videos; not assigned to Free or unknown-entitlement accounts

Conversation requests are translated to the Build Responses protocol while preserving the tool, reasoning, multi-turn, and prompt-cache compatibility required by Codex and Claude Code. Build currently exposes no image generation or image editing routes.

Grok Web

Web uses a built-in catalog filtered by account tier; higher tiers inherit lower-tier models.

Model	Type	Minimum tier	Gateway surfaces
`grok-chat-fast`	Conversation	Basic	Chat Completions, Responses, Messages
`grok-chat-auto`	Conversation	Super	Chat Completions, Responses, Messages
`grok-chat-expert`	Conversation	Super	Chat Completions, Responses, Messages
`grok-chat-heavy`	Conversation	Heavy	Chat Completions, Responses, Messages
`grok-imagine-image-lite`	Image	Basic	Images Generations
`grok-imagine-image-quality-lite`	Image	Basic	Images Generations
`grok-imagine-image-edit`	Image Edit	Super	Images Edits
`grok-imagine-video`	Video	Super	Videos

Grok Console

Console uses the catalog built into the current release. Conversation forwarding is stateless, while image, video, and voice use the standard xAI resource APIs.

Model	Type	Gateway surfaces
`grok-4.20-0309-non-reasoning`	Conversation	Chat Completions, Responses, Messages
`grok-4.20-0309-reasoning`	Conversation	Chat Completions, Responses, Messages; the model reasons but the upstream rejects configurable `reasoningEffort`
`grok-4.20-multi-agent-0309`	Conversation	Chat Completions, Responses, Messages
`grok-4.5`	Conversation	Chat Completions, Responses, Messages
`grok-4.3`	Conversation	Chat Completions, Responses, Messages
`grok-build-0.1`	Conversation	Chat Completions, Responses, Messages
`grok-imagine-image`	Image, Image Edit	Images Generations, Images Edits
`grok-imagine-image-quality`	Image, Image Edit	Images Generations, Images Edits
`grok-imagine-image-2.0`	Image, Image Edit	Images Generations, Images Edits
`grok-imagine-video`	Video	Videos
`grok-imagine-video-1.5`	Video	Video generation, including Free Console accounts
`grok-voice-latest`, `grok-voice-think-fast-2.0`, `grok-voice-think-fast-1.0`	Voice	TTS and Realtime WebSocket proxy
`grok-stt`	Voice	STT and OpenAI-compatible audio transcriptions

Generation and editing capabilities for the same Console image model are grouped into one logical model row; no separate -edit model copy is required.

Public names normally omit the Provider. Internally, routes use Build/, Web/, or Console/; qualified names can pin a request to one source.

Web can be weakly linked one-to-one with matching Build and Console accounts. Links share only an anonymous egress identity and provenance display. They never merge credentials, quota, health, cooldown, concurrency, capabilities, or billing.

Codex, Claude Code, and prompt caching

Responses and Messages support streaming, tools, reasoning, multi-turn sessions, and compaction. Stable client session signals are preserved for Grok Build prompt-cache affinity. Cache hits still require a compatible upstream account and an unchanged prompt prefix.

Responses and Chat Completions report OpenAI-style total input. Messages reports Anthropic-style uncached input and cache reads separately. Audits retain total and cached input for billing reconciliation.

API

Inference endpoints use a client key:

Authorization: Bearer g2a_xxx_xxx

Method	Path	Purpose
`GET`	`/healthz`, `/readyz`	Liveness and readiness
`GET`	`/v1/models`	Serviceable models
`POST`	`/v1/responses`	Responses JSON/SSE
`POST`	`/v1/responses/compact`	Compact a supported Response session
`GET`, `DELETE`	`/v1/responses/{id}`	Read or delete a stored response
`POST`	`/v1/chat/completions`	Chat Completions JSON/SSE
`POST`	`/v1/messages`	Anthropic Messages JSON/SSE
`POST`	`/v1/images/generations`, `/v1/images/edits`	Generate or edit images
`POST`, `GET`	`/v1/videos/*`	Create and inspect video jobs
`POST`	`/v1/tts`, `/v1/audio/speech`, `/v1/audio/tasks`	Synthesize speech
`POST`	`/v1/stt`, `/v1/audio/transcriptions`	Transcribe audio
`GET`	`/v1/stt`, `/v1/realtime`	Proxy voice WebSocket sessions
`GET`	`/v1/media/images/{asset_id}`, `/v1/media/videos/{asset_id}`	Read archived media

Stored responses and compact depend on the selected Provider. The signed-in admin console provides live examples at /docs; Swagger is available only when server.swaggerEnabled: true.

/v1/audio/transcriptions supports json (default), verbose_json, and text. Video edit/extension routes must resolve to Console grok-imagine-video; custom public model names remain supported. Monetary billing is applied only when the gateway can reliably measure the official pricing unit: TTS is reserved and settled from its input character count, while REST and streaming STT are settled from the actual audio duration returned by a successful response. Because STT duration is known only after completion, concurrent requests may briefly take a billing-limited key beyond its spend limit. Realtime, video edits/extensions, and custom routes without a recognized official price are currently audited as unpriced; they remain callable and do not consume the spend limit.

Client keys support model allowlists and optional RPM, concurrency, spend, and expiry limits.

curl http://127.0.0.1:8000/v1/responses \
  -H "Authorization: Bearer g2a_xxx_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model",
    "input": "Explain quantum tunneling in three sentences.",
    "stream": true
  }'

Egress and Cloudflare

Egress nodes are scoped to Build, Web, Console, or Web assets. The admin console supports:

HTTP, HTTPS, SOCKS4/4A, SOCKS5/5H, Resin, Trojan, VLESS, Shadowsocks, and VMess
TCP, WebSocket, and TLS tunnel transports; unsupported variants are rejected during import
Subscription and text/Base64 import
Batch probes, filtering, deletion, assignment, and balancing
Fallback per scope: none, direct, or a fixed node
Proxy-pool mode without global cooldown after one connection failure
Immediate recovery probes after fixed-proxy transport failures, with per-node coalescing and bounded waiting for fast retry
Optional Egress Quality Guard for active per-node model probes, guarded quarantine, and recovery; enable it with the built-in quality-guard Compose profile

Hysteria and TUIC are not supported yet. FlareSolverr accepts only HTTP/SOCKS proxy URLs, so automatic clearance refresh cannot use a tunnel share URL directly.

To enable the guard, add a qualityGuard section to config.yaml, then start the profile. The main service creates and reuses a non-exportable system probe identity automatically:

qualityGuard:
  enabled: true
  model: "grok-4.5"

docker compose --profile quality-guard up -d --build

Existing preview deployments that still contain clientKeyID can upgrade directly. The field is accepted for compatibility but ignored and can be removed; any manually created probe key is intentionally left untouched.

After changing this configuration, run docker compose --profile quality-guard restart grok2api egress-quality-guard to reload the base settings; policy edits made in the admin page still hot-reload.

The normal docker compose up -d command does not start the guard or generate probe traffic. The sidecar receives a narrowly scoped internal credential from the main service and never stores or uses the administrator password. See the linked guide before enabling automatic quarantine.

Resin usernames can contain {account}:

socks5h://Default.{account}:RESIN_PROXY_TOKEN@resin:2260

The placeholder becomes a stable anonymous identity. Linked Web, Build, and Console accounts can share it; raw tokens and email addresses are not used.

For managed Web/Console Cloudflare Clearance:

docker compose --profile flaresolverr up -d

Then use http://flaresolverr:8191 under Runtime Settings → Media & Network → Clearance and select one of the managed modes:

FlareSolverr proactively refreshes stale fixed-egress Clearance on the configured schedule.
On demand keeps the last successful Clearance regardless of age and solves again only after an upstream rejection explicitly invalidates it. Scheduled refresh does not launch a browser in this mode.

Manual never invokes FlareSolverr. The on-demand mode can make the first request without a managed Clearance; if Cloudflare rejects it, the next lease performs one deduplicated solve.

The egress layer retries only connection failures known to occur before request submission. It does not replay submitted generation requests, authentication failures, exhausted quotas, or upstream rate limits.

When a fixed proxy enters cooldown after a transport failure, grok2api starts an independent connectivity probe immediately. Concurrent failures share one probe. A later request bound to that node waits for at most five seconds, reloads persisted node state after a healthy probe, and continues without waiting for the full cooldown. An unhealthy probe preserves the cooldown. Proxy-pool leases use fresh tunnels, so one rotating exit failure never cools the whole pool. See Immediate egress failure probe and bounded retry for the design and safety invariants.

Configuration and deployment

config.yaml contains startup settings; Provider and operational settings are managed in the admin console and hot-reload unless marked otherwise.

Deployment	Database	Runtime store	Media
Single instance	SQLite	Memory	Local directory
Multiple instances	PostgreSQL	Redis	Shared read/write directory

Multi-instance deployments require a unique deployment.instanceID per replica, one shared clusterID, and sharedMedia: true only after the media directory is shared correctly.

PostgreSQL credentials can be injected without storing them in config.yaml:

GROK2API_DATABASE_URL='postgresql://user:password@host:5432/grok2api?sslmode=require' docker compose up -d

A non-empty GROK2API_DATABASE_URL overrides database.postgres.dsn and automatically selects the postgres driver. An empty value is ignored. Supported URL schemes are postgres:// and postgresql://; SQLAlchemy's postgresql+asyncpg:// form is rejected with a migration hint. The application does not implicitly read the generic DATABASE_URL; platforms that provide it can map it explicitly with GROK2API_DATABASE_URL: "${DATABASE_URL}". Database configuration precedence is built-in defaults, config.yaml, then GROK2API_DATABASE_URL. The current CLI has no database override.

Important optional settings:

audit.ledgerMode: observe reports ledger faults; enforce can pause new inference to protect billing integrity.
routing.accountIsolatedConnections: partitions outbound TCP/HTTP pools by account for external L4 or connection-hash load balancers. It is off by default because it increases connections, TLS handshakes, memory, and file-descriptor usage.
routing.segmentedSelectorEnabled: enabled by default for pools with at least 3,000 eligible accounts; bounds dynamic concurrency reads while retaining quota/tier priorities, sticky sessions, full-planner fallback, and atomic guards.
Build response-header timeout and exact-match 403 invalidation rules are hot-reloadable.
Sync latest version applies the validated Grok Build client version and User-Agent.

Production checklist

Use HTTPS and enable auth.secureCookies.
Keep Swagger disabled on public deployments.
Use strong, backed-up secrets; never commit credentials, cookies, exports, or databases.
Back up config.yaml, the database, and media storage.
Use PostgreSQL, Redis, and shared media for multiple instances.
Put a reverse proxy and access controls in front of public deployments.

Development

cd backend
go test ./...
go test -race ./...
go vet ./...
go build ./cmd/grok2api

cd frontend
pnpm install --frozen-lockfile
pnpm lint
pnpm build

Regenerate Swagger after changing public API annotations:

make swagger

Documentation

yorukot/superfile

Pretty fancy and modern terminal file manager

superfile is supported by the community.

Demo

Perform common operations

Content

Installation

macOS and Linux

bash -c "$(curl -sLo- https://superfile.dev/install.sh)"

If you want to inspect the script, see : install.sh

Windows

Powershell

powershell -ExecutionPolicy Bypass -Command "Invoke-Expression ((New-Object System.Net.WebClient).DownloadString('https://superfile.dev/install.ps1'))"

If you want to inspect the script, see : install.ps1

Winget

winget install --id yorukot.superfile

Scoop

scoop install superfile

More installation methods

Click me to check on how to install

Build

You can build the source code yourself by using these steps:

Requirements

golang

Build Steps

Clone this repository using the following command:

git clone https://github.com/yorukot/superfile.git --depth=1

Enter the downloaded directory:

cd superfile

For macOS/Linux

Run the build.sh file:

./build.sh

Add the binary file to your $PATH, e.g., in /usr/local/bin:

sudo mv ./bin/spf /usr/local/bin

For Windows

go build -o bin/spf.exe

Edit System Environment Variables and add superfile repo's bin directory to your PATH

Start superfile

spf

Supported Systems

[x] Linux
[x] macOS
[x] Windows (Not fully supported yet)

Tutorial

After you install superfile, you can go here to briefly understand how to use superfile!

Plugins

Click me to the plugins wiki

Themes

Click me to the theme wiki

Hotkeys

If you are vim/nvim user please change your default hotkeys config to vim version!

Click me to see the hotkey wiki

Notes

We have an auto update functionality, that fetches superfile's latest released version from github (if last timestamp of last version check was less than 24 hours) and prints a prompt to user, if there is a newer version available.

You can turn this off, by setting auto_check_update to false in superfile config. Click me to see the config wiki

Troubleshooting

Click me to see common problem fix

Uninstalling

macOS and Linux

bash -c "$(curl -sLo- https://superfile.dev/uninstall.sh)"

If you want to inspect the script, see : uninstall.sh

Windows

To uninstall superfile on Windows, use this powershell script.

powershell -ExecutionPolicy Bypass -Command "Invoke-Expression ((New-Object System.Net.WebClient).DownloadString('https://superfile.dev/uninstall.ps1'))"

Contributing

If you want to contribute please follow the contribution guide

Click me to see changelog

Thanks

Support

a Star on my GitHub repository would be nice 🌟
You can buy a coffee for me 💖

Core maintainer

We welcome anyone who wants to become a core maintainer. Feel free to reach out!

@yorukot - Original author and maintainer
@lazysegtree - Core maintainer

Contributors

Thanks to all the contributors for making this project even greater!

Powered by

Thanks to JetBrains team for providing open-source licenses to support the maintenance of superfile.

Star History

THANKS FOR All OF YOUR STARS! Your stars are my motivation to keep updating!

༼ つ ◕_◕ ༽つ Please share.

sundowndev/phoneinfoga

Information gathering framework for phone numbers

Documentation • API documentation • Related blog post

About

PhoneInfoga is one of the most advanced tools to scan international phone numbers. It allows you to first gather basic information such as country, area, carrier and line type, then use various techniques to try to find the VoIP provider or identify the owner. It works with a collection of scanners that must be configured in order for the tool to be effective. PhoneInfoga doesn't automate everything, it's just there to help investigating on phone numbers.

Current status

This project is stable but unmaintained. Upcoming bugs won't be fixed and repository could be archived at any time.

Features

Check if phone number exists
Gather basic information such as country, line type and carrier
OSINT footprinting using external APIs, phone books & search engines
Check for reputation reports, social media, disposable numbers and more
Use the graphical user interface to run scans from the browser
Programmatic usage with the REST API and Go modules

Anti-features

Does not claim to provide relevant or verified data, it's just a tool !
Does not allow to "track" a phone or its owner in real time
Does not allow to get the precise phone location
Does not allow to hack a phone

License

This tool is licensed under the GNU General Public License v3.0.

Icon made by Freepik from flaticon.com is licensed by CC 3.0 BY.

Support

Support me by signing up to DigitalOcean using my link ($200 free credits)

traefik/traefik

The Cloud Native Application Proxy

Traefik (pronounced traffic) is a modern HTTP reverse proxy and load balancer that makes deploying microservices easy. Traefik integrates with your existing infrastructure components (Docker, Swarm mode, Kubernetes, Consul, Etcd, Rancher v2, Amazon ECS, ...) and configures itself automatically and dynamically. Pointing Traefik at your orchestrator should be the only configuration step you need.

. Overview . Features . Supported backends . Quickstart . Web UI . Documentation .

. Support . Release cycle . Contributing . Maintainers . Credits .

⚠️ When migrating to a new major version of Traefik, please refer to the migration guide to ensure a smooth transition and to be aware of any breaking changes.

Overview

Imagine that you have deployed a bunch of microservices with the help of an orchestrator (like Swarm or Kubernetes) or a service registry (like etcd or consul). Now you want users to access these microservices, and you need a reverse proxy.

Traditional reverse-proxies require that you configure each route that will connect paths and subdomains to each microservice. In an environment where you add, remove, kill, upgrade, or scale your services many times a day, the task of keeping the routes up to date becomes tedious.

This is when Traefik can help you!

Traefik listens to your service registry/orchestrator API and instantly generates the routes so your microservices are connected to the outside world -- without further intervention from your part.

Run Traefik and let it do the work for you! (But if you'd rather configure some of your routes manually, Traefik supports that too!)

Features

Continuously updates its configuration (No restarts!)
Supports multiple load balancing algorithms
Provides HTTPS to your microservices by leveraging Let's Encrypt (wildcard certificates support)
Circuit breakers, retry
See the magic through its clean web UI
WebSocket, HTTP/2, gRPC ready
Provides metrics (Rest, Prometheus, Datadog, Statsd, InfluxDB 2.X)
Keeps access logs (JSON, CLF)
Fast
Exposes a Rest API
Packaged as a single binary file (made with ❤️ with go) and available as an official docker image

Supported Backends

Quickstart

To get your hands on Traefik, you can use the 5-Minute Quickstart in our documentation (you will need Docker).

Web UI

You can access the simple HTML frontend of Traefik.

Documentation

You can find the complete documentation of Traefik v3 at https://doc.traefik.io/traefik/.

Support

To get community support, you can:

join the Traefik community forum:

If you need commercial support, please contact Traefik.io by mail: mailto:support@traefik.io.

Download

Grab the latest binary from the releases page and run it with the sample configuration file:

./traefik --configFile=traefik.toml

Or use the official tiny Docker image and run it with the sample configuration file:

docker run -d -p 8080:8080 -p 80:80 -v $PWD/traefik.toml:/etc/traefik/traefik.toml traefik

Or get the sources:

git clone https://github.com/traefik/traefik

Introductory Videos

You can find high level and deep dive videos on videos.traefik.io.

Maintainers

We are strongly promoting a philosophy of openness and sharing, and firmly standing against the elitist closed approach. Being part of the core team should be accessible to anyone who is motivated and want to be part of that journey! This document describes how to be part of the maintainers' team as well as various responsibilities and guidelines for Traefik maintainers. You can also find more information on our process to review pull requests and manage issues in this document.

Contributing

If you'd like to contribute to the project, refer to the contributing documentation.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project, you agree to abide by its terms.

Release Cycle

We usually release 3/4 new versions (e.g. 1.1.0, 1.2.0, 1.3.0) per year.
Release Candidates are available before the release (e.g. 1.1.0-rc1, 1.1.0-rc2, 1.1.0-rc3, 1.1.0-rc4, before 1.1.0).
Bug-fixes (e.g. 1.1.1, 1.1.2, 1.2.1, 1.2.3) are released as needed (no additional features are delivered in those versions, bug-fixes only).

Each version is supported until the next one is released (e.g. 1.1.x will be supported until 1.2.0 is out).

We use Semantic Versioning.

Mailing Lists

General announcements, new releases: mail at news+subscribe@traefik.io or on the online viewer.
Security announcements: mail at security+subscribe@traefik.io or on the online viewer.

Credits

Kudos to Peka for his awesome work on the gopher's logo!.

The gopher's logo of Traefik is licensed under the Creative Commons 3.0 Attributions license.

The gopher's logo of Traefik was inspired by the gopher stickers made by Takuya Ueda. The original Go gopher was designed by Renee French.

caddyserver/caddy

Fast and extensible multi-platform HTTP/1-2-3 web server with automatic HTTPS

a project

Every site on HTTPS

Caddy is an extensible server platform that uses TLS by default.

Releases · Documentation · Get Help

Powered by

^{Special thanks to:}

Warp, built for coding with multiple AI agents

Available for MacOS, Linux, & Windows

Features

Easy configuration with the Caddyfile
Powerful configuration with its native JSON config
Dynamic configuration with the JSON API
Config adapters if you don't like JSON
Automatic HTTPS by default
- ZeroSSL and Let's Encrypt for public names
- Fully-managed local CA for internal names & IPs
- Can coordinate with other Caddy instances in a cluster
- Multi-issuer fallback
- Encrypted ClientHello (ECH) support
Stays up when other servers go down due to TLS/OCSP/certificate-related issues
Production-ready after serving trillions of requests and managing millions of TLS certificates
Scales to hundreds of thousands of sites as proven in production
HTTP/1.1, HTTP/2, and HTTP/3 all supported by default
Highly extensible modular architecture lets Caddy do anything without bloat
Runs anywhere with no external dependencies (not even libc)
Written in Go, a language with higher memory safety guarantees than other servers
Actually fun to use
So much more to discover

Install

The simplest, cross-platform way to get started is to download Caddy from GitHub Releases and place the executable file in your PATH.

See our online documentation for other install instructions.

Build from source

Requirements:

Go 1.25.0 or newer

For development

Note: These steps will not embed proper version information. For that, please follow the instructions in the next section.

$ git clone "https://github.com/caddyserver/caddy.git"
$ cd caddy/cmd/caddy/
$ go build

When you run Caddy, it may try to bind to low ports unless otherwise specified in your config. If your OS requires elevated privileges for this, you will need to give your new binary permission to do so. On Linux, this can be done easily with: sudo setcap cap_net_bind_service=+ep ./caddy

If you prefer to use go run which only creates temporary binaries, you can still do this with the included setcap.sh like so:

$ go run -exec ./setcap.sh main.go

If you don't want to type your password for setcap, use sudo visudo to edit your sudoers file and allow your user account to run that command without a password, for example:

username ALL=(ALL:ALL) NOPASSWD: /usr/sbin/setcap

replacing username with your actual username. Please be careful and only do this if you know what you are doing! We are only qualified to document how to use Caddy, not Go tooling or your computer, and we are providing these instructions for convenience only; please learn how to use your own computer at your own risk and make any needful adjustments.

Then you can run the tests in all modules or a specific one:

$ go test ./...
$ go test ./modules/caddyhttp/tracing/

With version information and/or plugins

Using our builder tool, xcaddy...

$ xcaddy build

...the following steps are automated:

Create a new folder: mkdir caddy
Change into it: cd caddy
Copy Caddy's main.go into the empty folder. Add imports for any custom plugins you want to add.
Initialize a Go module: go mod init caddy
(Optional) Pin Caddy version: go get github.com/caddyserver/caddy/v2@version replacing version with a git tag, commit, or branch name.
(Optional) Add plugins by adding their import: _ "import/path/here"
Compile: go build -tags=nobadger,nomysql,nopgx

Quick start

The Caddy website has documentation that includes tutorials, quick-start guides, reference, and more.

We recommend that all users -- regardless of experience level -- do our Getting Started guide to become familiar with using Caddy.

If you've only got a minute, the website has several quick-start tutorials to choose from! However, after finishing a quick-start tutorial, please read more documentation to understand how the software works. 🙂

Overview

Caddy is most often used as an HTTPS server, but it is suitable for any long-running Go program. First and foremost, it is a platform to run Go applications. Caddy "apps" are just Go programs that are implemented as Caddy modules. Two apps -- tls and http -- ship standard with Caddy.

Caddy apps instantly benefit from automated documentation, graceful on-line config changes via API, and unification with other Caddy apps.

Although JSON is Caddy's native config language, Caddy can accept input from config adapters which can essentially convert any config format of your choice into JSON: Caddyfile, JSON 5, YAML, TOML, NGINX config, and more.

The primary way to configure Caddy is through its API, but if you prefer config files, the command-line interface supports those too.

Caddy exposes an unprecedented level of control compared to any web server in existence. In Caddy, you are usually setting the actual values of the initialized types in memory that power everything from your HTTP handlers and TLS handshakes to your storage medium. Caddy is also ridiculously extensible, with a powerful plugin system that makes vast improvements over other web servers.

To wield the power of this design, you need to know how the config document is structured. Please see our documentation site for details about Caddy's config structure.

Nearly all of Caddy's configuration is contained in a single config document, rather than being scattered across CLI flags and env variables and a configuration file as with other web servers. This makes managing your server config more straightforward and reduces hidden variables/factors.

Full documentation

Our website has complete documentation:

https://caddyserver.com/docs/

The docs are also open source. You can contribute to them here: https://github.com/caddyserver/website

Getting help

We advise companies using Caddy to secure a support contract through Ardan Labs before help is needed.
A sponsorship goes a long way! We can offer private help to sponsors. If Caddy is benefitting your company, please consider a sponsorship. This not only helps fund full-time work to ensure the longevity of the project, it provides your company the resources, support, and discounts you need; along with being a great look for your company to your customers and potential customers!
Individuals can exchange help for free on our community forum at https://caddy.community. Remember that people give help out of their spare time and good will. The best way to get help is to give it first!

Please use our issue tracker only for bug reports and feature requests, i.e. actionable development items (support questions will usually be referred to the forums).

About

Matthew Holt began developing Caddy in 2014 while studying computer science at Brigham Young University. (The name "Caddy" was chosen because this software helps with the tedious, mundane tasks of serving the Web, and is also a single place for multiple things to be organized together.) It soon became the first web server to use HTTPS automatically and by default, and now has hundreds of contributors and has served trillions of HTTPS requests.

The name "Caddy" is trademarked. The name of the software is "Caddy", not "Caddy Server" or "CaddyServer". Please call it "Caddy" or, if you wish to clarify, "the Caddy web server". Caddy is a registered trademark of Stack Holdings GmbH.

Project on X: @caddyserver
Author on X: @mholt6

Caddy is a project of ZeroSSL, an HID Global company.

Debian package repository hosting is graciously provided by Cloudsmith. Cloudsmith is the only fully hosted, cloud-native, universal package management solution, that enables your organization to create, store and share packages in any format, to any place, with total confidence.

multica-ai/multica

Assign issues to Claude Code, Codex, Cursor, and 17 more coding agents like teammates — open-source and self-hostable.

Multica

Agents that show up on the board.

Multica is an open-source workspace where you assign work to AI coding agents the way you'd assign it to a teammate — they pick up the issue, report progress, raise blockers, and hand it back for review. Self-hostable, works with 20 agent CLIs, no lock-in.

Website · Docs · Quickstart · Download · Vision · Self-Hosting · Discord · X

English | 简体中文

_{Your next 10 hires won't be human.}

What is Multica?

You already run Claude Code, Codex, and three other agents. Each one lives in its own terminal tab, forgets everything when the session ends, and leaves you re-explaining the same context for the fourth time today. The more agents you add, the more of your day goes to babysitting them.

Multica puts those agents and your teammates in one workspace. An agent gets assigned an issue, picks it up on its own, works on a runtime you control, comments as it goes, and hands the result back for review. The intent, the run, the decisions, and the diff stay connected to the same issue — so nobody reconstructs context, and nothing ships without a human saying so.

Build the team.

Claude Code, Codex, Cursor, Kimi — you don't pick one. You hire them all.

20 agent CLIs → Claude Code, Codex, Cursor, Copilot, Kimi, OpenCode, and more.
Agents as teammates → Give each one a name, a provider, and a runtime — they show up on the board like anyone else.
Squads → Put agents and people on one team; the leader routes the work.
Skills → Turn a solved problem into a playbook every agent reuses.
Your own runtime → Their desk is your machine — a daemon on your laptop or cloud box. Code never leaves it.

Hand off the work.

It starts as three rough sentences in an issue. It ends as a pull request.

Assign an issue → Pick an agent as assignee the way you'd pick a colleague — it takes the work from there.
Autopilots → Run standups, audits, and reports on a cron — nobody to remind.
Chat → Ask your workspace a question, or start work without filing anything.
Projects → Group work and attach the repos and docs agents need as context.

Stay in the loop.

Which agent touched this? What did it run? What did it cost? Open the run.

Execution log → Replay every tool call, command, and error, timestamped.
Token usage → See what each run cost, per agent and per issue.
Review gates → Work lands in review, not in main. You decide what ships.
Inbox → Get pinged when an agent needs a call, not for every step.
Retries and timeouts → Failed runs retry on their own, or stop and tell you why.

Make it yours.

Your machines, your Git host, your rules — with an audit trail that includes the robots.

Self-host everything → Docker Compose or Helm, on your own infrastructure.
Any Git host → GitHub, GitLab, Gitea, or Forgejo — self-hosted included.
Workspaces → Separate agents, issues, and settings per team.
Roles and access scopes → owner, admin, and member — and exactly which agents each member can run.
Security model → What an agent can reach, and what it can't.
Slack, Lark, DingTalk, and WeCom → Trigger and follow agent work where your team already talks. DingTalk and WeCom are community-maintained.
Web, desktop, and mobile → The same workspace on macOS, Windows, Linux, and iPhone — iOS builds from source today, not yet on the App Store.
CLI and API → Every surface is scriptable. Agents drive Multica through the same CLI you do.

Get started

No terminal required: sign up at multica.ai, or download Multica Desktop for macOS, Windows, and Linux — it connects the computer it runs on as a runtime automatically.

The one prerequisite: the machine that will run agents needs at least one supported agent CLI installed and signed in — Claude Code, Codex, Cursor, and friends. Multica drives them; it doesn't ship them.

Self-hosting the whole thing

curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --with-server
multica setup self-host

On Windows, set $env:MULTICA_MODE="with-server", then run the PowerShell installer: irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex.

This pulls the official images from GHCR and requires Docker. See the Self-Hosting Guide; if the selected GHCR tag has not been published yet, fall back to make selfhost-build from a checkout.

Your first agent in five minutes

1. Sign in. multica.ai in the browser, or open Multica Desktop.

2. Connect a computer. A runtime is any machine agents can work on — your laptop, or a cloud box. Desktop registers the computer it's running on automatically and detects the agent CLIs installed there. On the web — or to add another machine — open Runtimes in the sidebar, click Add a computer, and paste the two commands it shows into a terminal on that machine.

3. Create an agent. Open Agents in the sidebar and click New agent. Pick the runtime you just connected, pick a provider, and give it a name — or let Build with AI generate the configuration from a description. That name is how it shows up on the board and in comments.

4. Assign it something. File an issue and set the agent as assignee. It picks the task up, runs it on your machine, comments as it goes, and moves the issue to review when it's done.

Full walkthrough: Quickstart · Tutorial

Runtimes

Multica does not ship a model. It drives the agent CLIs you already have installed and authenticated, so switching providers is a dropdown, not a migration.

Provider	CLI	Provider	CLI
Claude Code	`claude`	OpenAI Codex	`codex`
Cursor Agent	`cursor-agent`	GitHub Copilot CLI	`copilot`
OpenCode	`opencode`	OpenClaw	`openclaw`
Hermes	`hermes`	Pi	`pi`
Antigravity	`agy`	CodeBuddy	`codebuddy`
DevEco Code	`deveco`	Grok	`grok`
Kimi	`kimi`	Kiro CLI	`kiro-cli`
Qoder CLI	`qodercli`	Qoder CN	`qoderclicn`
Qwen Code	`qwen`	QwenPaw	`qwenpaw`
Reasonix	`reasonix`	Trae CLI	`traecli`
DeepSeek Harness	`dsh`	Oh-My-Pi	`omp`

Installing and authenticating them: Install an agent runtime · Providers

Documentation

I want to…	Start here
Get an agent doing something today	Quickstart · Tutorial
Understand how the pieces fit	Core concepts · How Multica works
Create and configure agents	Agents · Create an agent · Skills
Get work to an agent	Triggering agents · Assigning issues · Mentions
Connect my machines	Daemon and runtimes · Install an agent runtime
Connect Git and chat tools	GitHub · Self-hosted Git · Channels
Run it on my own infrastructure	Self-hosting · Security model · Environment variables
Script it	CLI reference · CLI and daemon guide · Auth tokens
Drive Multica from Codex, Claude Code, or Cursor	Multica CLI skill
Work out why an agent is stuck	Tasks · Troubleshooting

Architecture

        Web  ·  Desktop (macOS/Windows/Linux)  ·  iOS
                          │
                          ▼
   ┌──────────────┐   ┌──────────────┐   ┌──────────────────┐
   │   Next.js    │──>│  Go backend  │──>│   PostgreSQL     │
   │   frontend   │<──│  (Chi + WS)  │<──│   (pgvector)     │
   └──────────────┘   └──────┬───────┘   └──────────────────┘
                             │  tasks over WebSocket
                      ┌──────┴───────┐
                      │ Agent daemon │  runs on your machine, next to your code
                      └──────┬───────┘
                             │  spawns
                      ┌──────┴───────────────────────────────┐
                      │  Claude Code · Codex · Cursor · …    │
                      │  (any of the 20 runtimes above)      │
                      └──────────────────────────────────────┘

Layer	Stack
Web	Next.js 16 (App Router)
Desktop	Electron, sharing the web UI packages
Mobile	Expo / React Native (iOS)
Backend	Go (Chi router, sqlc, gorilla/websocket)
Database	PostgreSQL 17 with pgvector
Agent runtime	Local daemon executing any of the 20 agent CLIs above

Development

Contributors: start with the Contributing Guide.

Prerequisites: Node.js v20+, pnpm v10.28+, Go v1.26+, Docker

make dev

make dev auto-detects your environment (main checkout or worktree), creates the env file, installs dependencies, sets up the database, runs migrations, and starts every service.

See CONTRIBUTING.md for the full workflow, worktree support, testing, and troubleshooting. The iOS client lives in apps/mobile/ — its README covers building it onto your own iPhone.

We release most weekdays, so main moves quickly — pull often.

Why "Multica"?

Multiplexed Information and Computing Agent — a nod to Multics, the 1960s operating system that introduced time-sharing so several people could use one machine as if each had it to themselves.

Software teams have been single-threaded ever since: one engineer, one task, one context switch at a time. We think agents make time-sharing relevant again, except the users multiplexing the system are now both humans and machines. A small team shouldn't feel small.

The longer argument, and where we think this goes: VISION.md.

License

Multica License — the complete Apache License 2.0 text plus additional conditions covering hosted services, commercial embedding, and branding. Self-host it, modify it, build on it; the exact terms are in the LICENSE, attribution notices in NOTICE.

rclone/rclone

"rsync for cloud storage" - Google Drive, S3, Dropbox, Backblaze B2, One Drive, Swift, Hubic, Wasabi, Google Cloud Storage, Azure Blob, Azure Files, Yandex Files

Rclone

Rclone ("rsync for cloud storage") is a command-line program to sync files and directories to and from different cloud storage providers.

Storage providers

1Fichier 📄
Akamai Netstorage 📄
Alibaba Cloud (Aliyun) Object Storage System (OSS) 📄
Amazon S3 📄
ArvanCloud Object Storage (AOS) 📄
Bizfly Cloud Simple Storage 📄
Backblaze B2 📄
Box 📄
Ceph 📄
China Mobile Ecloud Elastic Object Storage (EOS) 📄
Citrix ShareFile 📄
Cloudflare R2 📄
Cloudinary 📄
Cubbit DS3 📄
DigitalOcean Spaces 📄
Digi Storage 📄
Dreamhost 📄
Drime 📄
Dropbox 📄
Enterprise File Fabric 📄
Exaba 📄
Fastly Object Storage 📄
Fastmail Files 📄
FileLu 📄
Filen 📄
Files.com 📄
FlashBlade 📄
FTP 📄
GoFile 📄
Google Cloud Storage 📄
Google Drive 📄
Google Photos 📄
HDFS (Hadoop Distributed Filesystem) 📄
Hetzner Object Storage 📄
Hetzner Storage Box 📄
HiDrive 📄
Hitachi Content Platform (HCP) 📄
HTTP 📄
Huawei Cloud Object Storage Service(OBS) 📄
Huawei Drive 📄
iCloud Drive 📄
ImageKit 📄
Internet Archive 📄
Internxt 📄
Jottacloud 📄
IBM COS S3 📄
Impossible Cloud 📄
Intercolo Object Storage 📄
IONOS Cloud 📄
Koofr 📄
Leviia Object Storage 📄
Liara Object Storage 📄
Linkbox 📄
Linode Object Storage 📄
Magalu Object Storage 📄
Mail.ru Cloud 📄
Memset Memstore 📄
MEGA 📄
MEGA S4 Object Storage 📄
Memory 📄
Microsoft Azure Blob Storage 📄
Microsoft Azure Files Storage 📄
Microsoft OneDrive 📄
Minio 📄
Nextcloud 📄
Blomp Cloud Storage 📄
OpenDrive 📄
OpenStack Swift 📄
Oracle Cloud Storage 📄
Oracle Object Storage 📄
Outscale 📄
OVHcloud Object Storage (Swift) 📄
OVHcloud Object Storage (S3-compatible) 📄
ownCloud 📄
pCloud 📄
Petabox 📄
PikPak 📄
Pixeldrain 📄
premiumize.me 📄
put.io 📄
Proton Drive 📄
QingStor 📄
Qiniu Cloud Object Storage (Kodo) 📄
Rabata Cloud Storage 📄
Quatrix 📄
Rackspace Cloud Files 📄
RackCorp Object Storage 📄
rsync.net 📄
Scaleway 📄
Scality (RING / ARTESCA) 📄
Seafile 📄
Seagate Lyve Cloud 📄
SeaweedFS 📄
Selectel Object Storage 📄
Servercore Object Storage 📄
SFTP 📄
Shade 📄
SMB / CIFS 📄
Spectra Logic 📄
Storj 📄
SugarSync 📄
Synology C2 Object Storage 📄
Tencent Cloud Object Storage (COS) 📄
Uloz.to 📄
US3 Object Storage 📄
Wasabi 📄
WebDAV 📄
Yandex Disk 📄
Zadara Object Storage 📄
Zero Services (ZERO-Z3) 📄
Zoho WorkDrive 📄
Zata.ai 📄
The local filesystem 📄

Please see the full list of all storage providers and their features

Virtual storage providers

These backends adapt or modify other storage providers

Alias: rename existing remotes 📄
Archive: read archive files 📄
Cache: cache remotes (DEPRECATED) 📄
Chunker: split large files 📄
Combine: combine multiple remotes into a directory tree 📄
Compress: compress files 📄
Crypt: encrypt files 📄
Hasher: hash files 📄
Union: join multiple remotes to work together 📄

Features

MD5/SHA-1 hashes checked at all times for file integrity
Timestamps preserved on files
Partial syncs supported on a whole file basis
Copy mode to just copy new/changed files
Sync (one way) mode to make a directory identical
Bisync (two way) to keep two directories in sync bidirectionally
Check mode to check for file hash equality
Can sync to and from network, e.g. two different cloud accounts
Optional large file chunking (Chunker)
Optional transparent compression (Compress)
Optional encryption (Crypt)
Optional FUSE mount (rclone mount)
Multi-threaded downloads to local disk
Can serve local or remote files over HTTP/WebDAV/FTP/SFTP/DLNA

Installation & documentation

Please see the rclone website for:

Downloads

https://rclone.org/downloads/

License

This is free software under the terms of the MIT license (check the COPYING file included in this package).

netbirdio/netbird

Connect your devices into a secure WireGuard®-based overlay network with SSO, MFA and granular access controls.

Start using NetBird at netbird.io
See Documentation
Join our Slack channel or our Community forum

🚀 We are hiring! Join us at https://netbird.io/careers

🤖 NetBird Agent Network (Beta)

Identity-aware access control for AI agents — keyless access to LLM APIs and private resources over the encrypted NetBird tunnel. See agent-network/ or read the docs at netbird.ai.

NetBird combines a configuration-free peer-to-peer private network and a centralized access control system in a single platform, making it easy to create secure private networks for your organization or home.

Connect. NetBird creates a WireGuard-based overlay network that automatically connects your machines over an encrypted tunnel, leaving behind the hassle of opening ports, complex firewall rules, VPN gateways, and so forth.

Secure. NetBird enables secure remote access by applying granular access policies while allowing you to manage them intuitively from a single place. Works universally on any infrastructure.

https://github.com/user-attachments/assets/10cec749-bb56-4ab3-97af-4e38850108d2

Self-host NetBird (video)

Key features

Connectivity	Management	Security	Automation	Platforms
✓ Kernel WireGuard	✓ Admin Web UI	✓ SSO & MFA support	✓ Public API	✓ Linux
✓ Peer-to-peer connections	✓ Auto peer discovery and configuration	✓ Access control: groups & rules	✓ Setup keys for bulk provisioning	✓ macOS
✓ Connection relay fallback	✓ IdP integrations	✓ Activity logging	✓ Self-hosting quickstart script	✓ Windows
✓ Routes to external networks	✓ Private DNS	✓ Traffic events	✓ IdP groups sync with JWT	✓ Android
✓ Domain-based DNS routes	✓ Custom DNS zones	✓ Device posture checks	✓ Terraform provider	✓ Android TV
✓ Exit nodes	✓ Multiuser support	✓ Peer-to-peer encryption	✓ Ansible collection	✓ iOS
✓ IPv6 dual-stack overlay	✓ Multi-account profile switching	✓ SSH with central access policies		✓ Apple TV
✓ Browser SSH & RDP		✓ Quantum-resistance with Rosenpass		✓ FreeBSD
✓ Reverse proxy with auto-TLS		✓ Periodic re-authentication		✓ pfSense
				✓ OPNsense
				✓ MikroTik RouterOS
				✓ OpenWRT
				✓ Synology
				✓ TrueNAS
				✓ Proxmox
				✓ Raspberry Pi
				✓ Serverless
				✓ Container

Quickstart with NetBird Cloud

Download and install NetBird at https://app.netbird.io/install.
Follow the steps to sign up with Google, Microsoft, GitHub or your email address.
Check the NetBird admin UI.

Quickstart with self-hosted NetBird

This is the quickest way to try self-hosted NetBird. It should take around 5 minutes to get started if you already have a public domain and a VM. Follow the Advanced guide with a custom identity provider for installations with different IdPs.

Infrastructure requirements:

A Linux VM with at least 1 CPU and 2 GB of memory.
The VM should be publicly accessible on TCP ports 80 and 443 and UDP port 3478.
A public domain name pointing to the VM.

Software requirements:

Docker with the Compose plugin (Compose v2 or higher). See the Docker installation guide.

Steps

Download and run the installation script:

export NETBIRD_DOMAIN=netbird.example.com; curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

A bit on NetBird internals

Every machine in the network runs the NetBird agent, which manages WireGuard.
Every agent connects to the Management Service, which holds network state, manages peer IPs, and distributes updates to agents.
Agents use ICE (via pion/ice) to discover connection candidates for peer-to-peer connections.
Candidates are discovered with the help of STUN servers.
Agents negotiate a connection through the Signal Service, exchanging end-to-end encrypted messages with candidates.
When NAT traversal fails (e.g. mobile carrier-grade NAT) and a direct p2p connection isn't possible, the system falls back to a Relay Service and a secure WireGuard tunnel is established through it.

See a complete architecture overview for details.

Community projects

NetBird installer script
netbird-tui - terminal UI for managing NetBird peers, routes, and settings
caddy-netbird - Caddy plugin that embeds a NetBird client for proxying HTTP and TCP/UDP traffic through NetBird networks

Note: The main branch may be in an unstable or even broken state during development. For stable versions, see releases.

Support acknowledgement

In November 2022, NetBird joined the StartUpSecure program sponsored by the Federal Ministry of Education and Research of the Federal Republic of Germany. Together with the CISPA Helmholtz Center for Information Security, NetBird brings security best practices and simplicity to private networking.

Acknowledgements

We build on open source technologies like WireGuard®, Pion ICE, and Rosenpass. We greatly appreciate the work these projects are doing, and we'd love it if you could support them too (e.g., by starring or contributing).

Legal

This repository is licensed under the BSD-3-Clause license, which applies to all parts of the repository except for the directories management/, signal/ and relay/. Those directories are licensed under the GNU Affero General Public License version 3.0 (AGPLv3). See the respective LICENSE files inside each directory.

WireGuard and the WireGuard logo are registered trademarks of Jason A. Donenfeld.

schollz/croc

Easily and securely send things from one computer to another 🐊 📦

This project’s future depends on community support. Become a sponsor today.

About

croc is a tool that allows any two computers to simply and securely transfer files and folders. AFAIK, croc is the only CLI file-transfer tool that does all of the following:

Allows any two computers to transfer data (using a relay)
Provides end-to-end encryption (using PAKE)
Enables easy cross-platform transfers (Windows, Linux, Mac, Browser)
Allows multiple file transfers
Allows resuming transfers that are interrupted
No need for local server or port-forwarding
IPv6-first with IPv4 fallback
Can use a proxy, like Tor

For more information about croc, see my blog post or read a recent interview I did.

No-install

You can use croc without installing anything at getcroc.com.

The browser version is fully compatible with the CLI, so you can send and receive files between them.

Install

You can download the latest release for your system, or install a release from the command-line:

curl https://getcroc.com | bash

On macOS

Using Homebrew:

brew install croc

Using MacPorts:

sudo port selfupdate
sudo port install croc

On Windows

You can install the latest release with Scoop, Chocolatey, or Winget:

scoop install croc

choco install croc

winget install schollz.croc

Using nix-env

You can install the latest release with Nix:

nix-env -i croc

On NixOS

You can add this to your configuration.nix:

environment.systemPackages = [
  pkgs.croc
];

On Alpine Linux

First, install dependencies:

apk add bash coreutils
wget -qO- https://getcroc.com | bash

On Debian

Install from the pkg.haus APT archive:

# Add the repository (see https://pkg.haus for setup instructions)
sudo apt install croc

On Arch Linux

Install with pacman:

pacman -S croc

On Fedora

Install with dnf:

dnf install croc

On Gentoo

Install with portage:

emerge net-misc/croc

On Termux

Install with pkg:

pkg install croc

On FreeBSD

Install with pkg:

pkg install croc

On Linux, macOS, and Windows via Conda

You can install from conda-forge globally with pixi:

pixi global install croc

Or install into a particular environment with conda:

conda install --channel conda-forge croc

On Linux, macOS via Docker

Add the following one-liner function to your ~/.profile (works with any POSIX-compliant shell):

croc() { [ $# -eq 0 ] && set -- ""; mkdir -p "$HOME/.config/croc"; docker run --rm -it --user "$(id -u):$(id -g)" -v "$(pwd):/c" -v "$HOME/.config/croc:/.config/croc" -w /c -e CROC_SECRET docker.io/schollz/croc "$@"; }

You can also just paste it in the terminal for current session. On first run Docker will pull the image. croc via Docker will only work within the current directory and its subdirectories.

Build from Source

If you prefer, you can install Go and build from source (requires Go 1.26+):

go install github.com/schollz/croc/v11@latest

On Android

There are F-Droid apps available:

crocgui — original port (Go, basic UI)
croc-app — native Kotlin/Jetpack Compose client with a modern, mobile-first interface
FlCroc — cross-platform Flutter GUI (Android, Windows, Linux) that wraps the croc binary as its transfer core.

On Desktop

Community made desktop apps:

Croc GUI — unofficial desktop GUI for macOS, Windows, and Linux that bundles the croc binary for drag-and-drop transfers, QR codes, LAN mode, and relay/proxy options.
croc-desktop — unofficial desktop GUI for Linux, macOS, and Windows (experimental iOS/Android) built with Wails v3; embeds croc in-process for send/receive, QR codes, history, logs, and optional relay hosting.
Swamp Swap — unofficial PyQt6 GUI desktop app for macOS, Windows, and Linux, requires installing croc on its own normally in order to use. Made to be compact and simple.

Usage

To send a file, simply do:

$ croc send [file(s)-or-folder]
Sending 'file-or-folder' (X MB)
Code is: code-phrase

Then, to receive the file (or folder) on another computer, run:

croc code-phrase

The code phrase is used to establish password-authenticated key agreement (PAKE) which generates a secret key for the sender and recipient to use for end-to-end encryption.

Customizations & Options

Encrypted temporary storage

When an immediate peer-to-peer transfer is inconvenient, croc can upload regular files as client-side encrypted ciphertext:

croc send --store [file1] [file2]
croc send --store --store-downloads 3 [file1] [file2]
croc send --store --store-expiration 3d [file1] [file2]

The command prints a browser link and a CLI token. The transfer expires after the selected lifetime, measured from successful upload completion, or after its configured number of receivers download, authenticate, and verify every file—whichever happens first. The lifetime defaults to one day and accepts whole minutes (m), hours (h), days (d), or weeks (w). The download limit defaults to one. Both values are subject to server policy. Run croc with no arguments and paste the token at the prompt to receive it. For automation, keep the token out of the process list:

CROC_STORE_TOKEN='croc-store-v1....' croc --out ./downloads

The browser link has the form https://host/s/id#v1.decryption-key. The decryption key is after # because URL fragments are not included in HTTP requests, so the storage service gets the opaque transfer ID but not the key. The full link is still a secret: anyone who has it can decrypt the files and claim one of the allowed downloads.

While a transfer remains available, its sender can delete it with the locally saved revoke receipt:

croc --revoke [transfer-id]

Stored mode is opt-in and separate from croc's normal live relay transfers. A self-hosted service can be selected with --store-url or CROC_STORE_URL. See the stored-transfer design and operator guide for protocol, privacy, limits, and deployment details.

Using `croc` on Linux or macOS

On Linux and macOS, the sending and receiving process is slightly different to avoid leaking the secret via the process name. You will need to run croc with the secret as an environment variable. For example, to receive with the secret ***:

CROC_SECRET=*** croc

For single-user systems, the default behavior can be permanently enabled by running:

croc --classic

Custom Code Phrase

You can send with your own code phrase (must be at least 6 characters):

croc send --code [code-phrase] [file(s)-or-folder]

Allow Overwriting Without Prompt

To automatically overwrite files without prompting, use the --overwrite flag:

croc --yes --overwrite <code>

Keep Both Files Without Prompt

To keep an existing file and receive the incoming one under a new name (e.g. video (1).mkv), use the --rename flag:

croc --yes --rename <code>

Excluding Folders

To exclude folders from being sent, use the --exclude flag with comma-delimited exclusions. This does a case-insensitive substring match against each file's relative path, so any path containing one of the given strings anywhere is excluded:

croc send --exclude "node_modules,.venv" [folder]

If you need to exclude one specific file rather than every path containing a substring (for example, two files share a name at different depths and only one should be excluded), use --exclude-file instead. It takes comma-delimited relative paths and matches them exactly:

croc send --exclude-file "subfolder/image.jpg" [folder]

Use Pipes - stdin and stdout

You can pipe to croc:

cat [filename] | croc send

To receive the file to stdout, you can use:

croc --yes [code-phrase] > out

Send Text

To send URLs or short text, use:

croc send --text "hello world"

Send Multiple Files

You can send multiple files directly by listing the files and/or folders:

croc send [file1] [file2] [file3] [folder1] [folder2]

Show QR Code

To show QR code (for mobile devices), use:

croc send --qr [file(s)-or-folder]

The QR code opens https://getcroc.com/?code=..., where the web client automatically connects in receive-only mode.

Use a Proxy

You can send files via a proxy by adding --socks5:

croc --socks5 "127.0.0.1:9050" send SOMEFILE

Change Encryption Curve

To choose a different elliptic curve for encryption, use the --curve flag:

croc --curve p521 <codephrase>

Change Hash Algorithm

For faster hashing, use the imohash algorithm:

croc send --hash imohash SOMEFILE

Clipboard Options

By default, the code phrase is copied to your clipboard. To disable this:

croc --disable-clipboard send [filename]

To copy the full command with the secret as an environment variable (useful on Linux/macOS):

croc --extended-clipboard send [filename]

This copies the full command like CROC_SECRET="code-phrase" croc (including any relay/pass flags).

Quiet Mode

To suppress all output (useful for scripts and automation):

croc --quiet send [filename]

Self-host Relay

You can run your own relay:

croc relay

By default, it uses TCP ports 9009-9013. You can customize the ports (e.g., croc relay --ports 1111,1112), but at least 2 ports are required.

To send files using your relay:

croc --relay "myrelay.example.com:9009" send [filename]

Self-host Relay with Docker

You can also run a relay with Docker:

docker run -d -p 9009-9013:9009-9013 -e CROC_PASS='YOURPASSWORD' docker.io/schollz/croc

To send files using your custom relay:

croc --pass YOURPASSWORD --relay "myreal.example.com:9009" send [filename]

To use custom ports, set CROC_PORTS (comma-separated) or CROC_PORT (base port):

docker run -d -p 9010-9011:9010-9011 -e CROC_PORTS='9010,9011' -e CROC_PASS='YOURPASSWORD' docker.io/schollz/croc

Web client

The React/Vite client in web/ can send and receive multiple files with normal croc CLI peers. The production client and its WebAssembly protocol runtime are bundled only in the standalone croc-web server, keeping generated assets and web-server code out of the cross-platform croc binary. Linux amd64 builds of croc-web are published separately with each release. It serves both the site and its same-origin WebSocket relay:

croc-web getcroc.com

This binds to 127.0.0.1:9014 by default for an HTTPS reverse proxy. / serves the website and /ws bridges to ipv4.getcroc.com. For a directly accessible local development server, croc-web localhost:5173 binds and serves on localhost:5173. Use --bind, --relay, and --ports before the website address to customize the local listener or upstream croc relay.

Run make build-web to generate the ignored production assets and build a local server. See web/README.md for frontend development, custom relay, and reverse-proxy instructions.

Deployment

Disco

Disco is used to deploy. The root Dockerfile and disco.json deploy the croc-web web client and croc TCP relay as two Disco services built from the same image. Disco serves the website over HTTPS, while relay ports 9009-9017 are published directly as TCP ports.

Set the deployment environment variables with:

disco env:set \
  SITE_URL=yoururl.com \
  CROC_RELAY_PORTS=9009,9010,9011,9012,9013,9014,9015,9016,9017 \
  CROC_PASS=yourpass \
  --project croc

SITE_URL must be the public website hostname without https://. Change the project name if it is not croc. The web service mounts the named croc-store volume at /www/croc/storage, which is also its configured --store-dir, so stored ciphertext and metadata survive container replacement and redeployment. The web service also reserves published TCP port 9020 and maps it to unused container port 65535. This deliberate port collision makes Disco stop the previous volume-owning web service before starting its replacement, avoiding concurrent access to the store. Port 9020 carries no application traffic and should remain blocked by the server firewall.

The ports in CROC_RELAY_PORTS must match the publishedPorts entries in the relay service in disco.json; do not include the web service's deployment-only port 9020. Disco cannot generate host port mappings from an environment variable. Make sure the relay TCP ports are also open in the server's firewall or cloud security group.

Acknowledgements

croc has evolved through many iterations, and I am thankful for the contributions! Special thanks to:

@warner for the idea
@tscholl2 for the encryption gists
@skorokithakis for proxying two connections

And many more!

pranshuparmar/witr

Why is this running? Trace any process, port, container, or file back to what started it - CLI + TUI.

witr

Why is this running?

Trace any process, port, container, or file back to the exact chain that started it —
one command, machine-readable JSON, or an interactive TUI.

🎮 Try witr in your browser →

Investigate a simulated Linux box — a guided tutorial and free-play sandbox, no install required.

Purpose • Installation • TUI • Flags • Core Concept • Examples
Output Behavior • Platforms • Success Criteria • Sponsors

1. Purpose

witr exists to answer a single question:

Why is this running?

When something is running on a system, whether it is a process, a service, or something bound to a port, there is always a cause. That cause is often indirect, non-obvious, or spread across multiple layers such as supervisors, containers, services, or shells.

Existing tools (ps, top, lsof, ss, systemctl, docker ps) expose state and metadata. They show what is running, but leave the user to infer why by manually correlating outputs across tools.

witr makes that causality explicit.

It explains where a running thing came from, how it was started, and what chain of systems is responsible for it existing right now, in a single, human-readable output or an interactive TUI dashboard.

📖 Curious how witr came to be? Read the story or browse the Hacker News discussion.

2. Installation

witr is distributed as a single static binary for Linux, macOS, FreeBSD, and Windows.

witr is also independently packaged and maintained across multiple operating systems and ecosystems. An up-to-date overview of packaging status is available on Repology. Please note that community packages may lag GitHub releases due to independent review and validation.

Tip

If you use a package manager (Homebrew, Conda, Winget, etc.), we recommend installing via that for easier updates. Otherwise, the install script is the quickest way to get started.

2.1 Quick Install

Unix (Linux, macOS & FreeBSD)

curl -fsSL https://raw.githubusercontent.com/pranshuparmar/witr/main/install.sh | bash

Script Details

The script will:

Detect your operating system (linux, darwin or freebsd)
Detect your CPU architecture (amd64 or arm64)
Download the latest released binary and man page
Install it to /usr/local/bin/witr
Install the man page to /usr/local/share/man/man1/witr.1
Pass INSTALL_PREFIX to override default install path

Windows (PowerShell)

irm https://raw.githubusercontent.com/pranshuparmar/witr/main/install.ps1 | iex

Script Details

The script will:

Download the latest release (zip) and verify checksum.
Extract witr.exe to %LocalAppData%\witr\bin.
Add the bin directory to your User PATH.

2.2 Package Managers

APT (Debian, Ubuntu & Derivatives)

You can install witr from the official Debian and Ubuntu repositories (Ubuntu 26.04+, Debian sid and later), as well as derivative distributions like Kali Linux, Devuan, and Raspbian:

sudo apt install witr

Note: The apt-shipped version may lag the latest GitHub release. For the newest features, use the install script or another installation method.

Homebrew (macOS & Linux)

You can install witr using Homebrew on macOS or Linux:

brew install witr

MacPorts (macOS)

You can install witr using MacPorts on macOS:

sudo port install witr

Conda (macOS, Linux & Windows)

You can install witr using conda, mamba, or pixi on macOS, Linux, and Windows:

conda install -c conda-forge witr
# alternatively using mamba
mamba install -c conda-forge witr
# alternatively using pixi
pixi global install witr

Arch Linux (AUR)

On Arch Linux and derivatives, install from the AUR package:

yay -S witr-bin
# alternatively using paru
paru -S witr-bin
# or use your preferred AUR helper

Winget (Windows)

You can install witr via winget:

winget install -e --id PranshuParmar.witr

NPM (Cross-platform)

You can install witr using npm:

npm install -g @pranshuparmar/witr

FreeBSD Ports

You can install witr on FreeBSD from the FreshPorts port:

pkg install witr
# or
pkg install sysutils/witr

Or build from Ports:

cd /usr/ports/sysutils/witr/
make install clean

Chocolatey (Windows)

You can install witr using Chocolatey:

choco install witr

Scoop (Windows)

You can install witr using Scoop:

scoop install main/witr

AOSC OS

You can install witr from the AOSC OS repository:

oma install witr

GNU Guix

You can install witr from the GNU Guix repository:

guix install witr

Uniget (Linux)

You can install witr using uniget:

uniget install witr

Aqua (macOS, Linux & Windows)

You can install witr using aqua:

# Add package
aqua g -i pranshuparmar/witr

# Install package
aqua i pranshuparmar/witr

Brioche (Linux)

You can install witr using brioche:

brioche install -r witr

Mise (macOS, Linux & Windows)

You can install witr using mise:

mise use github:pranshuparmar/witr

Prebuilt Packages (deb, rpm, apk)

witr provides native packages for major Linux distributions. You can download the latest .deb, .rpm, or .apk package from the GitHub releases page.

Generic download command using curl:

# Replace <package name with the actual package that you need>
curl -LO https://github.com/pranshuparmar/witr/releases/latest/download/<package-name>

Debian/Ubuntu (.deb):

sudo dpkg -i ./witr-*.deb
# Or, using apt for dependency resolution:
sudo apt install ./witr-*.deb

Fedora/RHEL/CentOS (.rpm):
```
sudo rpm -i ./witr-*.rpm
```

Alpine Linux (.apk):

sudo apk add --allow-untrusted ./witr-*.apk

2.3 Source & Manual Installation

Go (cross-platform)

You can install the latest version directly from source:

go install github.com/pranshuparmar/witr/cmd/witr@latest

This will place the witr binary in your $GOPATH/bin or $HOME/go/bin directory. Make sure this directory is in your PATH.

Manual Installation

If you prefer manual installation, follow these simple steps for your platform:

Unix (Linux, macOS, FreeBSD)

# 1. Determine OS and Architecture
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)
[ "$ARCH" = "x86_64" ] && ARCH="amd64"
[ "$ARCH" = "aarch64" ] && ARCH="arm64"

# 2. Download the binary
curl -fsSL "https://github.com/pranshuparmar/witr/releases/latest/download/witr-${OS}-${ARCH}" -o witr

# 3. Verify checksum (Optional)
curl -fsSL "https://github.com/pranshuparmar/witr/releases/latest/download/SHA256SUMS" -o SHA256SUMS
grep "witr-${OS}-${ARCH}" SHA256SUMS | (sha256sum -c - 2>/dev/null || shasum -a 256 -c - 2>/dev/null)
rm SHA256SUMS

# 4. Rename and install
chmod +x witr
sudo mkdir -p /usr/local/bin
sudo mv witr /usr/local/bin/witr

# 5. Install man page (Optional)
sudo mkdir -p /usr/local/share/man/man1
sudo curl -fsSL https://github.com/pranshuparmar/witr/releases/latest/download/witr.1 -o /usr/local/share/man/man1/witr.1

Windows (PowerShell)

# 1. Determine Architecture
if ($env:PROCESSOR_ARCHITECTURE -eq "AMD64") {
    $ZipName = "witr-windows-amd64.zip"
} elseif ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") {
    $ZipName = "witr-windows-arm64.zip"
} else {
    Write-Error "Unsupported architecture: $($env:PROCESSOR_ARCHITECTURE)"
    exit 1
}

# 2. Download the zip
Invoke-WebRequest -Uri "https://github.com/pranshuparmar/witr/releases/latest/download/$ZipName" -OutFile "witr.zip"
# 3. Extract the binary
Expand-Archive -Path "witr.zip" -DestinationPath "." -Force

# 4. Verify checksum (Optional)
Invoke-WebRequest -Uri "https://github.com/pranshuparmar/witr/releases/latest/download/SHA256SUMS" -OutFile "SHA256SUMS"
$hash = Get-FileHash -Algorithm SHA256 .\witr.zip
$expected = Select-String -Path .\SHA256SUMS -Pattern $ZipName
if ($expected -and $hash.Hash.ToLower() -eq $expected.Line.Split(' ')[0]) { Write-Host "Checksum OK" } else { Write-Host "Checksum Mismatch" }

# 5. Install to local bin directory
$InstallDir = "$env:LocalAppData\witr\bin"
New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null
Move-Item .\witr.exe $InstallDir\witr.exe -Force

# 6. Add to User Path (Persistent)
$UserPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($UserPath -notlike "*$InstallDir*") {
    [Environment]::SetEnvironmentVariable("Path", "$UserPath;$InstallDir", "User")
    $env:Path += ";$InstallDir"
    Write-Host "Added to Path. You may need to restart PowerShell."
}

# 7. Cleanup
Remove-Item witr.zip
Remove-Item SHA256SUMS

2.4 Run Without Installation

Nix Flake

If you use Nix, you can build witr from source and run without installation:

nix run github:pranshuparmar/witr -- --help

Pixi

If you use pixi, you can run without installation on Linux or macOS:

pixi exec witr --help

2.5 Other Operations

Verify Installation

witr --version
man witr

Shell Completions

witr supports tab completion for all flags. To enable it, add the appropriate line to your shell configuration:

Bash

echo 'eval "$(witr completion bash)"' >> ~/.bashrc
source ~/.bashrc

Zsh

echo 'eval "$(witr completion zsh)"' >> ~/.zshrc
source ~/.zshrc

Fish

witr completion fish | source
# To make it permanent:
witr completion fish > ~/.config/fish/completions/witr.fish

PowerShell

witr completion powershell | Out-String | Invoke-Expression
# To make it permanent, add the above line to your $PROFILE

Uninstallation

If you installed via a package manager (Homebrew, Conda, etc.), please use the respective uninstall command (e.g., brew uninstall witr).

To completely remove script/manual installation of witr:

Unix (Linux, macOS, FreeBSD)

sudo rm -f /usr/local/bin/witr
sudo rm -f /usr/local/share/man/man1/witr.1

Windows

Remove-Item -Recurse -Force "$env:LocalAppData\witr"

3. Interactive Mode (TUI)

Running witr without any arguments or with the -i flag launches the Interactive Mode (TUI). This provides a real-time, terminal-based dashboard with four tabs for exploring processes, ports, containers, and file locks.

Key Features:

Processes Tab: Live, sortable, filterable list of all running processes with a side panel showing the ancestry tree of the highlighted process.
Ports Tab: Open/listening ports with the owning processes attached in a side panel. Toggle between LISTEN-only and ALL with a.
Containers Tab: All running containers across Docker, Podman, nerdctl, K8s/crictl, Incus, LXC, LXD, and FreeBSD jails in one list - name, image, status, ports, command, plus a per-container detail view with mounts, networks, and compose project metadata.
Locks Tab: System-wide file locks (POSIX/FLOCK on Linux, lsof-derived on macOS/FreeBSD). Press a to switch into "all open files" mode, where locked entries are merged with every interesting open fd; type into / to search across the merged set.
Process Details: Deep-dive into a process to see its full ancestry tree, child processes, environment variables, working directory, sockets, file context, and more.
Process Actions: Send signals (Kill, Terminate, Pause, Resume) or Renice processes directly from the UI (Unix only).
Mouse Support: Navigate, sort columns, and click rows using your mouse.
Adaptive Theme: Colors adapt automatically to light and dark terminal backgrounds.
Auto-Refresh: The process, port, container, and lock lists refresh automatically on an adaptive cadence (starts at 3 seconds, backing off under load).

4. Flags & Options

  -c, --container strings container(s) to look up (repeatable)
      --env              show environment variables for the process
  -x, --exact            use exact name matching (no substring search)
  -f, --file strings     file(s) held open by a process (repeatable)
  -h, --help             help for witr
  -i, --interactive      interactive mode (TUI)
      --json             show result as JSON
      --no-color         disable colorized output
  -p, --pid strings      pid(s) to look up (repeatable)
  -o, --port strings     port(s) to look up (repeatable)
  -s, --short            show only ancestry
  -t, --tree             show only ancestry as a tree
      --verbose          show extended process information
  -v, --version          version for witr
      --warnings         show only warnings

Positional arguments (without flags) are treated as process or service names. Multiple names can be passed. By default, name matching uses substring matching (fuzzy search). Use --exact to match only processes with the exact name.

All target flags (--pid, --port, --file, --container) are repeatable and can be mixed with each other and with positional name arguments. When multiple targets are provided, results are shown sequentially with labeled dividers. All output modes (standard, short, tree, JSON, env, warnings, verbose) work with multiple inputs.

The --container flag searches across Docker, Podman, nerdctl, K8s/crictl, Incus, LXC, LXD, and FreeBSD jails, and matches against container name, image, command, and compose project/service labels.

The TUI is launched if no arguments or relevant flags (--pid, --port, --file, --container) are provided, or if the --interactive flag is explicitly used.

5. Core Concept

witr treats everything as a process question.

Ports, services, containers, and commands all eventually map to PIDs. Once a PID is identified, witr builds a causal chain explaining why that PID exists.

At its core, witr answers:

What is running?
How did it start?
What is keeping it running?
What context does it belong to?

6. Example Outputs

💡 Prefer learning by doing? The interactive browser tutorial walks you through outputs like these live on a simulated box — for a better feel of witr, no install required.

6.1 Name Based Query

witr node

Target      : node

Process     : node (pid 14233)
User        : pm2
Command     : node index.js
Started     : 2 days ago (Mon 2025-02-02 11:42:10 +05:30)

Why It Exists :
  systemd (pid 1) → pm2 (pid 5034) → node (pid 14233)

Source      : pm2

Working Dir : /opt/apps/expense-manager
Git Repo    : expense-manager (main)
Sockets     : 127.0.0.1:5001 (TCP | LISTENING)

6.2 Short Output

witr --port 5000 --short

systemd (pid 1) → PM2 v5.3.1: God (pid 1481580) → python (pid 1482060)

6.3 Tree Output

witr --pid 143895 --tree

systemd (pid 1)
  └─ init-systemd(Ub (pid 2)
    └─ SessionLeader (pid 143858)
      └─ Relay(143860) (pid 143859)
        └─ bash (pid 143860)
          └─ sh (pid 143886)
            └─ node (pid 143895)
              ├─ node (pid 143930)
              ├─ node (pid 144189)
              └─ node (pid 144234)

Note: Tree view includes child processes (up to 10) and highlights the target process.

6.4 Multiple Matches

witr ng

Multiple matching processes found:

[1] nginx (pid 2311)
    nginx -g daemon off;
[2] nginx (pid 24891)
    nginx -g daemon off;
[3] ngrok (pid 14233)
    ngrok http 5000

Re-run with:
  witr --pid <pid>

To avoid substring matching and only find processes with an exact name, use the --exact flag:

witr nginx -x

6.5 File Based Query

witr --file /var/lib/dpkg/lock

Explains the process holding a file open.

6.6 Container Based Query

witr --container redis

Looks up a container by name, image, command, or compose project/service across every detected runtime (Docker, Podman, nerdctl, K8s/crictl, Incus, LXC, LXD, FreeBSD jails). Pass --verbose to include mounts, networks, and compose metadata in the output.

6.7 Multiple Inputs

witr nginx --port 5432 --pid 1234

----- [name: nginx] -----
Target      : nginx
Process     : nginx (pid 2311)
...

----- [port: 5432] -----
Target      : postgres
Process     : postgres (pid 891)
...

----- [pid: 1234] -----
Target      : node
Process     : node (pid 1234)
...

All target flags are repeatable and can be mixed. Results appear in the order you typed them. All output modes (--short, --tree, --json, --env, --warnings, --verbose) work with multiple inputs.

7. Output Behavior

7.1 Output Principles

Single screen by default (best effort)
Deterministic ordering
Narrative-style explanation
Best-effort detection with explicit uncertainty

7.2 Exit Codes

witr returns meaningful exit codes for use in scripts, CI pipelines, and monitoring:

Code	Meaning
0	Clean: process found, no warnings
1	Warnings: process found but has one or more warnings
2	Not found: no matching process or service
3	Permission denied: insufficient privileges
4	Invalid input: bad arguments or ambiguous match
5	Internal error: an unexpected failure occurred

Example Usage:

witr nginx --short
case $? in
  0) echo "All clear" ;;
  1) echo "Warnings detected" ;;
  2) echo "Process not running" ;;
  3) echo "Need elevated privileges" ;;
  4) echo "Invalid input or ambiguous match" ;;
  5) echo "Internal error" ;;
esac

7.3 Standard Output Sections

Target

What the user asked about.

Process

Executable, PID, user, command, start time and restart count.

Why It Exists

A causal ancestry chain showing how the process came to exist. This is the core value of witr.

Source

The primary system responsible for starting or supervising the process (best effort).

Examples:

systemd unit with schedule info for timer-triggered services (Linux)
launchd service with schedule/trigger details (macOS)
SSH session (with remote IP and terminal)
docker container
pm2
cron
interactive shell (detects tmux/screen sessions)
Snap/Flatpak sandbox (Linux)

Only one primary source is selected.

Context (best effort)

Working directory
Git repository name and branch
Container name / image (docker, podman, kubernetes, colima, containerd)
Public vs private bind

Warnings

Non‑blocking observations such as:

Process is running as root
Dangerous Linux capabilities on non-root processes (CAP_SYS_ADMIN, etc.)
Process is listening on a public interface (0.0.0.0 / :😃
Restarted multiple times (warning only if above threshold)
Process is using high memory (>1GB RSS)
Process has been running for over 90 days
Deleted binary, library injection indicators (LD_PRELOAD, DYLD_*)

8. Platform Support

Linux (x86_64, arm64) - Full feature support (/proc).
macOS (x86_64, arm64) - Uses ps, lsof, sysctl, pgrep.
Windows (x86_64, arm64) - Native Win32 APIs (ToolHelp32, PSAPI, Service Control Manager). No PowerShell or WMI dependency.
FreeBSD (x86_64, arm64) - Uses procstat, ps, lsof.

8.1 Feature Compatibility Matrix

Feature	Linux	macOS	Windows	FreeBSD	Notes
Process Selection
By Name	✅	✅	✅	✅
By PID	✅	✅	✅	✅
By Port	✅	✅	✅	✅
By File	✅	✅	✅	✅
By Container	✅	✅	✅	✅	Requires the runtime CLI on PATH (docker/podman/nerdctl/crictl/incus/lxc/lxc-ls/jls).
Multiple/mixed inputs	✅	✅	✅	✅	Repeatable flags, mixed types.
Exact Match	✅	✅	✅	✅
Full command line	✅	✅	✅	✅
Process start time	✅	✅	✅	✅
Working directory	✅	✅	✅	✅
Environment variables	✅	⚠️	⚠️	✅	macOS: SIP restrictions; Windows: protected processes inaccessible.
Network
Listening ports	✅	✅	✅	✅
Bind addresses	✅	✅	✅	✅
Port → PID resolution	✅	✅	✅	✅
Port → Container fallback	✅	✅	✅	✅	Used when the port is owned by PID 1 via systemd socket activation or a container runtime.
Service Detection
Service Manager	✅	✅	✅	✅	Linux: systemd, macOS: launchd, Windows: Services, FreeBSD: rc.d
Service Description	✅	✅	✅	✅	Linux: `Description`, macOS: `Comment`, Windows: `Display Name`, FreeBSD: `rc` header
Configuration Source	✅	✅	✅	✅	Linux: Unit File, macOS: Plist, Windows: Registry Key, FreeBSD: Rc Script
Supervisor	✅	✅	✅	✅
Containers	✅	✅	✅	✅	Docker (plus compose mappings), Podman, nerdctl, K8s (Kubepods/crictl), Containerd. Colima on macOS/Linux. Incus/LXC/LXD on Linux. Jails on FreeBSD.
SSH session detection	✅	✅	✅	✅	Detects remote IP and terminal.
tmux/screen detection	✅	✅	❌	✅	Shows session name in source.
Schedule detection	✅	✅	❌	❌	Linux: systemd timers, macOS: launchd intervals/calendar.
Snap/Flatpak detection	✅	❌	❌	❌
Health & Diagnostics
CPU usage detection	✅	✅	✅	✅
Memory usage detection	✅	✅	✅	✅
Health status detection	✅	✅	✅	✅
Open Files / Handles	✅	✅	⚠️	✅	Windows: count only.
File Locks	✅	✅	❌	✅	Linux: `/proc/locks`; macOS/FreeBSD: derived from `lsof`/`fstat`.
Deleted binary detection	✅	✅	✅	✅	Warns if executable is missing.
Capability warnings	✅	❌	❌	❌	Warns about dangerous capabilities on non-root processes.
Context
Git repo/branch detection	✅	✅	✅	✅
Interactive Mode (TUI)
Processes Tab	✅	✅	✅	✅
Ports Tab	✅	✅	✅	✅
Containers Tab	✅	✅	✅	✅
Locks Tab	✅	✅	❌	✅	Toggle (`a`) shows all open files.
Process Details	✅	✅	✅	✅
Process Actions	✅	✅	❌	✅

Legend: ✅ Full support | ⚠️ Partial/limited support | ❌ Not available

8.2 Permissions Note

Linux/FreeBSD

witr inspects system directories which may require elevated permissions.

If you are not seeing the expected information, try running witr with sudo:

sudo witr [your arguments]

macOS

On macOS, witr uses ps, lsof, and launchctl to gather process information. Some operations may require elevated permissions:

sudo witr [your arguments]

Note: Due to macOS System Integrity Protection (SIP), some system process details may not be accessible even with sudo.

Windows

On Windows, witr talks directly to Win32 APIs (ToolHelp32, PSAPI, Service Control Manager) rather than spawning PowerShell or WMI, startup is fast and there's no Get-CimInstance hang. To see details for processes owned by other users or system services, you must run the terminal as Administrator.

# Run in Administrator PowerShell
.\witr.exe [your arguments]

9. Success Criteria

witr is successful if:

A user can answer "why is this running?" within seconds
It reduces reliance on multiple tools
Output is understandable under stress
Users trust it during incidents

10. Sponsors

Special thanks to the people who supported witr ❤️

AlexxIT/go2rtc

Ultimate camera streaming application

Ultimate camera streaming application with support for dozens formats and protocols.

zero-dependency small app for all OS (Windows, macOS, Linux, FreeBSD)
zero-delay for many supported protocols (lowest possible streaming latency)
streaming input from dozens formats and protocols
streaming output in all popular formats
streaming ingest in a number of popular formats
publish any source to popular streaming services (YouTube, Telegram)
on-the-fly transcoding only if necessary via FFmpeg
two-way audio support for many formats
streaming audio to all cameras with two-way audio support
mixing tracks from different sources to single stream
auto-match client-supported streaming formats and codecs
streaming stats for all active connections
can be integrated to any project or be used as standalone app

Inspired by

series of streaming projects from @deepch
webrtc go library and whole @pion team
rtsp-simple-server idea from @aler9
GStreamer framework pipeline idea
MediaSoup framework routing idea
HomeKit Accessory Protocol from @brutella
creator of the project's logo @v_novoseltsev

Table of Contents

Installation

Download binary or use Docker or Home Assistant add-on or integration
Open web interface: http://localhost:1984/
Add streams to config

Developers: integrate HTTP API into your smart home platform.

go2rtc: Binary

Download binary for your OS from latest release:

name	description
go2rtc_win64.zip	Windows 10+ 64-bit
go2rtc_win32.zip	Windows 10+ 32-bit
go2rtc_win_arm64.zip	Windows ARM 64-bit
go2rtc_linux_amd64	Linux 64-bit
go2rtc_linux_i386	Linux 32-bit
go2rtc_linux_arm64	Linux ARM 64-bit (ex. Raspberry 64-bit OS)
go2rtc_linux_arm	Linux ARM 32-bit (ex. Raspberry 32-bit OS)
go2rtc_linux_armv6	Linux ARMv6 (for old Raspberry 1 and Zero)
go2rtc_linux_mipsel	Linux MIPS (ex. Xiaomi Gateway 3, Wyze cameras)
go2rtc_mac_amd64.zip	macOS 11+ Intel 64-bit
go2rtc_mac_arm64.zip	macOS ARM 64-bit
go2rtc_freebsd_amd64.zip	FreeBSD 64-bit
go2rtc_freebsd_arm64.zip	FreeBSD ARM 64-bit

Don't forget to fix the rights chmod +x go2rtc_xxx_xxx on Linux and Mac.

PS. The application is compiled with the latest versions of the Go language for maximum speed and security. Therefore, the minimum OS versions depend on the Go language.

go2rtc: Docker

The Docker containers alexxit/go2rtc and ghcr.io/alexxit/go2rtc support multiple architectures including 386, amd64, arm/v6, arm/v7 and arm64. These containers offer the same functionality as the Home Assistant add-on but are designed to operate independently of Home Assistant. It comes preinstalled with FFmpeg and Python.

go2rtc: Home Assistant add-on

Settings > Add-ons > Plus > Repositories > Add
```
https://github.com/AlexxIT/hassio-addons
```
go2rtc > Install > Start

go2rtc: Home Assistant Integration

WebRTC Camera custom component can be used on any Home Assistant installation, including HassWP on Windows. It can automatically download and use the latest version of go2rtc. Or it can connect to an existing version of go2rtc. Addon installation in this case is optional.

go2rtc: Master version

Latest, but maybe unstable version:

Binary: latest master build
Docker: alexxit/go2rtc:master or alexxit/go2rtc:master-hardware versions
Home Assistant add-on: go2rtc master or go2rtc master hardware versions

Configuration

This is the go2rtc.yaml file in YAML-format. The configuration can be changed in the WebUI at http://localhost:1984. The editor provides syntax highlighting and checking.

The simplest config looks like this:

streams:
  hall-camera: rtsp://admin:password@192.168.1.123/cam/realmonitor?channel=1&subtype=0

by default go2rtc will search go2rtc.yaml in the current work directory
api server will start on default 1984 port (TCP)
rtsp server will start on default 8554 port (TCP)
webrtc will use port 8555 (TCP/UDP) for connections

More information can be found here.

Features

A summary table of all modules and features can be found here.

Core modules

app - Reading configs and setting up logs.
api - Handle HTTP and WebSocket API.
streams - Handle a list of streams.

Streaming input

public protocols

mpjpeg - The legacy but still used MJPEG protocol for real-time media transmission.
onvif - A popular ONVIF protocol for receiving media in RTSP format.
rtmp - The legacy but still used RTMP protocol for real-time media transmission.
rtsp - The most common RTSP protocol for real-time media transmission.
webrtc - WebRTC web-compatible protocol for real-time media transmission.
yuv4mpegpipe - Raw YUV frame stream with YUV4MPEG header.

private protocols

bubble - Some NVR from dvr163.com and eseecloud.com.
doorbird - Doorbird devices with two-way audio.
dvrip - DVR-IP NVR, NetSurveillance, Sofia protocol (XMeye SDK).
eseecloud - Some NVR from dvr163.com and eseecloud.com.
gopro - GoPro cameras, connected via USB or Wi-Fi.
hass - Import cameras from Home Assistant config files.
homekit - Cameras with Apple HomeKit protocol.
isapi - Two-way audio for Hikvision ISAPI protocol.
kasa - TP-Link Kasa cameras.
multitrans - Two-way audio for Chinese version of TP-Link cameras.
nest - Google Nest cameras through user-unfriendly and paid APIs.
ring - Ring cameras with two-way audio support.
roborock - Roborock vacuums with cameras with two-way audio support.
tapo - TP-Link Tapo cameras with two-way audio support.
vigi - TP-Link Vigi cameras.
tuya - Tuya ecosystem cameras with two-way audio support.
webtorrent - Stream from another go2rtc via WebTorrent protocol.
wyze - Wyze cameras using native P2P protocol
xiaomi - Xiaomi Mi Home ecosystem cameras with two-way audio support.

devices

alsa - A framework for receiving audio from devices on Linux OS.
v4l2 - A framework for receiving video from devices on Linux OS.

files

adts - Audio stream in AAC codec with Audio Data Transport Stream headers.
flv - The legacy but still used Flash Video format.
h264 - AVC/H.264 bitstream.
hevc - HEVC/H.265 bitstream.
hls - A popular HTTP Live Streaming format.
mjpeg - A continuous sequence of JPEG frames (without HTTP headers).
mpegts - The legacy MPEG transport stream format.
wav - Audio stream in Waveform Audio File format.

scripts

echo - If the source has a dynamic link, you can use a bash or python script to get it.
exec - You can run an external application (ffmpeg, gstreamer, rpicam, etc.) and receive a media stream from it.
expr - If the source has a dynamic link, you can use Expr language to get it.
ffmpeg - Use FFmpeg as a stream source. Hardware-accelerated transcoding and streaming from USB devices are supported.

webrtc

creality - Creality 3D printer cameras.
kinesis - Amazon Kinesis video streams.
openipc - Cameras on open-source OpenIPC firmware.
switchbot - SwitchBot cameras.
whep - WebRTC/WHEP is replaced by WebRTC/WISH standard for WebRTC video/audio viewers.
wyze - Legacy method to connect to Wyze cameras via docker-wyze-bridge.

Streaming output

adts - Output stream in ADTS format with AAC audio.
ascii - Just for fun stream as ASCII to Terminal.
flv - Output stream in Flash Video format.
hls - Output stream in HTTP Live Streaming format.
homekit - Output stream to Apple Home using HomeKit protocol.
jpeg - Output snapshots in JPEG format.
mpjpeg - Output a stream in MJPEG format.
mp4 - Output as MP4 stream or Media Source Extensions (MSE) compatible format.
mpegts - Output stream in MPEG transport stream format.
onvif - Output stream using ONVIF protocol.
rtmp - Output stream using Real-Time Messaging protocol.
rtsp - Output stream using Real-Time Streaming protocol.
webrtc - Output stream using Web Real-Time Communication API.
webtorrent - Output stream using WebTorrent protocol.
yuv4mpegpipe - Output in raw YUV frame stream with YUV4MPEG header.

Streaming ingest

Supported for: flv, mjpeg, mpegts, rtmp, rtsp, webrtc.

This is a feature when go2rtc expects to receive an incoming stream from an external application. The stream transmission is started and stopped by an external application.

You can push data only to an existing stream (create a stream with empty source in config).
You can push multiple incoming sources to the same stream.
You can push data to a non-empty stream, so it will have additional codecs inside.

Two-way audio

Supported for: doorbird, dvrip, exec, isapi, multitrans, ring, roborock, rtsp, tapo, tuya, webrtc, wyze, xiaomi.

Two-way audio can be used in browser with WebRTC technology. The browser will give access to the microphone only for HTTPS sites (read more).

Stream to camera

You can play audio files or live streams on any camera with two-way audio support.

Publish stream

You can publish any stream to streaming services (YouTube, Telegram, etc.) via RTMP/RTMPS.

Preload stream

You can preload any stream on go2rtc start. This is useful for cameras that take a long time to start up.

Streaming stats

WebUI provides detailed information about all active connections, including IP-addresses, formats, protocols, number of packets and bytes transferred. Via the HTTP API in json or dot format on an interactive connection map.

Codecs

If you have questions about why video or audio is not displayed, you need to read the following sections.

Name	FFmpeg	RTSP	Aliases
Advanced Audio Coding	`aac`	MPEG4-GENERIC
Advanced Video Coding	`h264`	H264	AVC, H.264
G.711 PCM (A-law)	`alaw`	PCMA	G711A
G.711 PCM (µ-law)	`mulaw`	PCMU	G711u
High Efficiency Video Coding	`hevc`	H265	HEVC, H.265
Motion JPEG	`mpjpeg`	JPEG
MPEG-1 Audio Layer III	`mp3`	MPA
Opus Codec	`opus`	OPUS
PCM signed 16-bit big-endian	`s16be`	L16

Codecs filters

go2rtc can automatically detect which codecs your device supports for WebRTC and MSE technologies.

But it cannot be done for RTSP, HTTP progressive streaming, HLS technologies. You can manually add a codec filter when you create a link to a stream. The filters work the same for all three technologies. Filters do not create a new codec, they only select the suitable codec from existing sources. You can add new codecs to the stream using the FFmpeg transcoding.

Without filters:

RTSP will provide only the first video and only the first audio (any codec)
MP4 will include only compatible codecs (H264, H265, AAC)
HLS will output in the legacy TS format (H264 without audio)

Some examples:

rtsp://192.168.1.123:8554/camera1?mp4 - useful for recording as MP4 files (e.g. Home Assistant or Frigate)
rtsp://192.168.1.123:8554/camera1?video=h264,h265&audio=aac - full version of the filter above
rtsp://192.168.1.123:8554/camera1?video=h264&audio=aac&audio=opus - H264 video codec and two separate audio tracks
rtsp://192.168.1.123:8554/camera1?video&audio=all - any video codec and all audio codecs as separate tracks
http://192.168.1.123:1984/api/stream.m3u8?src=camera1&mp4 - HLS stream with MP4 compatible codecs (HLS/fMP4)
http://192.168.1.123:1984/api/stream.m3u8?src=camera1&mp4=flac - HLS stream with PCMA/PCMU/PCM audio support (HLS/fMP4), won't work on old devices
http://192.168.1.123:1984/api/stream.mp4?src=camera1&mp4=flac - MP4 file with PCMA/PCMU/PCM audio support, won't work on old devices (ex. iOS 12)
http://192.168.1.123:1984/api/stream.mp4?src=camera1&mp4=all - MP4 file with non-standard audio codecs, won't work on some players

Codecs madness

AVC/H.264 video can be played almost anywhere. But HEVC/H.265 has many limitations in supporting different devices and browsers.

Device	WebRTC	MSE	HTTP*	HLS
latency	best	medium	bad	bad
Desktop Chrome 136+ Desktop Edge Android Chrome 136+	H264, H265* PCMU, PCMA OPUS	H264, H265* AAC, FLAC* OPUS	H264, H265* AAC, FLAC* OPUS, MP3	no
Desktop Firefox	H264 PCMU, PCMA OPUS	H264 AAC, FLAC* OPUS	H264 AAC, FLAC* OPUS	no
Desktop Safari 14+ iPad Safari 14+ iPhone Safari 17.1+	H264, H265* PCMU, PCMA OPUS	H264, H265 AAC, FLAC*	no!	H264, H265 AAC, FLAC*
iPhone Safari 14+	H264, H265* PCMU, PCMA OPUS	no!	no!	H264, H265 AAC, FLAC*
macOS Hass App	no	no	no	H264, H265 AAC, FLAC*

HTTP* - HTTP Progressive Streaming, not related to progressive download, because the file has no size and no end
WebRTC H265 - supported in Chrome 136+, supported in Safari 18+
MSE iPhone - supported in iOS 17.1+

Audio

go2rtc supports automatic repackaging of PCMA/PCMU/PCM codecs into FLAC for MSE/MP4/HLS so they'll work almost anywhere
WebRTC audio codecs: PCMU/8000, PCMA/8000, OPUS/48000/2
OPUS and MP3 inside MP4 are part of the standard, but some players do not support them anyway (especially Apple)

Apple devices

all Apple devices don't support HTTP progressive streaming
old iPhone firmwares don't support MSE technology because it competes with the HTTP Live Streaming (HLS) technology, invented by Apple
HLS is the worst technology for live streaming, it still exists only because of iPhones

Built-in transcoding

There are no plans to embed complex transcoding algorithms inside go2rtc. FFmpeg source does a great job with this. Including hardware acceleration support.

But go2rtc has some simple algorithms. They are turned on automatically; you do not need to set them up additionally.

PCM for MSE/MP4/HLS

Go2rtc can pack PCMA, PCMU and PCM codecs into an MP4 container so that they work in all browsers and all built-in players on modern devices. Including Apple QuickTime:

PCMA/PCMU => PCM => FLAC => MSE/MP4/HLS

Resample PCMA/PCMU for WebRTC

By default WebRTC supports only PCMA/8000 and PCMU/8000. But go2rtc can automatically resample PCMA and PCMU codecs with a different sample rate. Also, go2rtc can transcode PCM codec to PCMA/8000, so WebRTC can play it:

PCM/xxx => PCMA/8000 => WebRTC
PCMA/xxx => PCMA/8000 => WebRTC
PCMU/xxx => PCMU/8000 => WebRTC

Important

FLAC codec not supported in an RTSP stream. If you are using Frigate or Home Assistant for recording MP4 files with PCMA/PCMU/PCM audio, you should set up transcoding to the AAC codec.
PCMA and PCMU are VERY low-quality codecs. They support only 256! different sounds. Use them only when you have no other options.

Codecs negotiation

For example, you want to watch an RTSP stream from a Dahua IPC-K42 camera in your Chrome browser.

this camera supports two-way audio standard ONVIF Profile T
this camera supports codecs H264, H265 for sending video, and you select H264 in camera settings
this camera supports codecs AAC, PCMU, PCMA for sending audio (from mic), and you select AAC/16000 in camera settings
this camera supports codecs AAC, PCMU, PCMA for receiving audio (to speaker), you don't need to select them
your browser supports codecs H264, VP8, VP9, AV1 for receiving video, you don't need to select them
your browser supports codecs OPUS, PCMU, PCMA for sending and receiving audio, you don't need to select them
you can't get the camera audio directly because its audio codecs don't match your browser's codecs
- so you decide to use transcoding via FFmpeg and add this setting to the config YAML file
- you have chosen OPUS/48000/2 codec, because it is higher quality than the PCMU/8000 or PCMA/8000

Now you have a stream with two sources - RTSP and FFmpeg:

streams:
  dahua:
    - rtsp://admin:password@192.168.1.123/cam/realmonitor?channel=1&subtype=0&unicast=true&proto=Onvif
    - ffmpeg:rtsp://admin:password@192.168.1.123/cam/realmonitor?channel=1&subtype=0#audio=opus

go2rtc automatically matches codecs for your browser across all of your stream sources. This is called multi-source two-way codec negotiation, and it's one of the main features of this app.

PS. You can select PCMU or PCMA codec in camera settings and not use transcoding at all. Or you can select AAC codec for main stream and PCMU codec for second stream and add both RTSP to YAML config, this also will work fine.

Security

Important

If an attacker gains access to the API, you are in danger. Through the API, an attacker can use insecure sources such as echo and exec. And get full access to your server.

For maximum (paranoid) security, go2rtc has special settings:

app:
  # use only allowed modules
  modules: [api, rtsp, webrtc, exec, ffmpeg, mjpeg]

api:
  # use only allowed API paths
  allow_paths: [/api, /api/streams, /api/webrtc, /api/frame.jpeg]
  # enable auth for localhost (used together with username and password)
  local_auth: true

exec:
  # use only allowed exec paths
  allow_paths: [ffmpeg]

By default, go2rtc starts the Web interface on port 1984 and RTSP on port 8554, as well as uses port 8555 for WebRTC connections. The three ports are accessible from your local network. So anyone on your local network can watch video from your cameras without authorization. The same rule applies to the Home Assistant add-on.

This is not a problem if you trust your local network as much as I do. But you can change this behaviour with a go2rtc.yaml config:

api:
  listen: "127.0.0.1:1984" # localhost

rtsp:
  listen: "127.0.0.1:8554" # localhost

webrtc:
  listen: ":8555" # external TCP/UDP port

local access to RTSP is not a problem for FFmpeg integration, because it runs locally on your server
local access to API is not a problem for the Home Assistant add-on, because Home Assistant runs locally on the same server, and the add-on web UI is protected with Home Assistant authorization (Ingress feature)
external access to WebRTC TCP port is not a problem, because it is used only for transmitting encrypted media data
- anyway you need to open this port to your local network and to the Internet for WebRTC to work

If you need web interface protection without the Home Assistant add-on, you need to use a reverse proxy, like Nginx, Caddy, etc.

PS. Additionally, WebRTC will try to use the 8555 UDP port to transmit encrypted media. It works without problems on the local network, and sometimes also works for external access, even if you haven't opened this port on your router (read more). But for stable external WebRTC access, you need to open the 8555 port on your router for both TCP and UDP.

Projects using go2rtc

Home Assistant 2024.11+ - top open-source smart home project
Frigate 0.12+ - open-source NVR built around real-time AI object detection
camera.ui - The modern, local-first platform for professional video surveillance.
Advanced Camera Card - custom card for Home Assistant
OpenIPC - alternative IP camera firmware from an open community
wz_mini_hacks - custom firmware for Wyze cameras
EufyP2PStream - a small project that provides a video/audio stream from Eufy cameras that don't directly support RTSP
ioBroker.euSec - ioBroker adapter for controlling Eufy security devices
MMM-go2rtc - MagicMirror² module
ring-mqtt - Ring-to-MQTT bridge
lightNVR

Distributions

Camera experience

Dahua - reference implementation streaming protocols, a lot of settings, high stream quality, multiple streaming clients
EZVIZ - awful RTSP protocol implementation, many bugs in SDP
Hikvision - a lot of proprietary streaming technologies
Reolink - some models have an awful, unusable RTSP implementation and not the best RTMP alternative (I recommend that you contact Reolink support for new firmware), few settings
Sonoff - very low stream quality, no settings, not the best protocol implementation
TP-Link - few streaming clients, packet loss?
Cheap noname cameras, Wyze Cams, Xiaomi cameras with hacks (usually have /live/ch00_1 in RTSP URL) - awful but usable RTSP protocol implementation, low stream quality, few settings, packet loss?

Tips

Using apps for low RTSP delay

ffplay -fflags nobuffer -flags low_delay "rtsp://192.168.1.123:8554/camera1"
VLC > Preferences > Input / Codecs > Default Caching Level: Lowest Latency

Snapshots to Telegram

github/github-mcp-server

GitHub's official MCP Server

GitHub MCP Server

The GitHub MCP Server connects AI tools directly to GitHub's platform. This gives AI agents, assistants, and chatbots the ability to read repositories and code files, manage issues and PRs, analyze code, and automate workflows. All through natural language interactions.

Use Cases

Repository Management: Browse and query code, search files, analyze commits, and understand project structure across any repository you have access to.
Issue & PR Automation: Create, update, and manage issues and pull requests. Let AI help triage bugs, review code changes, and maintain project boards.
CI/CD & Workflow Intelligence: Monitor GitHub Actions workflow runs, analyze build failures, manage releases, and get insights into your development pipeline.
Code Analysis: Examine security findings, review Dependabot alerts, understand code patterns, and get comprehensive insights into your codebase.
Team Collaboration: Access discussions, manage notifications, analyze team activity, and streamline processes for your team.

Built for developers who want to connect their AI tools to GitHub context and capabilities, from simple natural language queries to complex multi-step agent workflows.

Remote GitHub MCP Server

The remote GitHub MCP Server is hosted by GitHub and provides the easiest method for getting up and running. If your MCP host does not support remote MCP servers, don't worry! You can use the local version of the GitHub MCP Server instead.

Prerequisites

A compatible MCP host with remote server support (VS Code 1.101+, Claude Desktop, Cursor, Windsurf, etc.)
Any applicable policies enabled

Install in VS Code

For quick installation, use one of the one-click install buttons above. Once you complete that flow, toggle Agent mode (located by the Copilot Chat text input) and the server will start. Make sure you're using VS Code 1.101 or later for remote MCP and OAuth support.

Alternatively, to manually configure VS Code, choose the appropriate JSON block from the examples below and add it to your host configuration:

Using OAuth Using a GitHub PAT

VS Code (version 1.101 or greater)

Using OAuth	Using a GitHub PAT
VS Code (version 1.101 or greater)
`{ "servers": { "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/" } } }`	`{ "servers": { "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/", "headers": { "Authorization": "Bearer ${input:github_mcp_pat}" } } }, "inputs": [ { "type": "promptString", "id": "github_mcp_pat", "description": "GitHub Personal Access Token", "password": true } ] }`

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${input:github_mcp_pat}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "github_mcp_pat",
      "description": "GitHub Personal Access Token",
      "password": true
    }
  ]
}

Install in other MCP hosts

Copilot CLI - Installation guide for GitHub Copilot CLI
GitHub Copilot in other IDEs - Installation for JetBrains, Visual Studio, Eclipse, and Xcode with GitHub Copilot
Claude Applications - Installation guide for Claude Desktop and Claude Code CLI
Codex - Installation guide for OpenAI Codex
Cursor - Installation guide for Cursor IDE
OpenCode - Installation guide for the OpenCode terminal agent
Windsurf - Installation guide for Windsurf IDE
Zed - Installation guide for Zed editor
Rovo Dev CLI - Installation guide for Rovo Dev CLI

Note: Each MCP host application needs to configure a GitHub App or OAuth App to support remote access via OAuth. Any host application that supports remote MCP servers should support the remote GitHub server with PAT authentication. Configuration details and support levels vary by host. Make sure to refer to the host application's documentation for more info.

Configuration

Toolset configuration

See Remote Server Documentation for full details on remote server configuration, toolsets, headers, and advanced usage. This file provides comprehensive instructions and examples for connecting, customizing, and installing the remote GitHub MCP Server in VS Code and other MCP hosts.

When no toolsets are specified, default toolsets are used.

Insiders Mode

Try new features early! The remote server offers an insiders version with early access to new features and experimental tools.

Using URL Path Using Header

Using URL Path	Using Header
`{ "servers": { "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/insiders" } } }`	`{ "servers": { "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/", "headers": { "X-MCP-Insiders": "true" } } } }`

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/insiders"
    }
  }
}

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "X-MCP-Insiders": "true"
      }
    }
  }
}

See Remote Server Documentation for more details and examples, and Insiders Features for a full list of what's available.

GitHub Enterprise

GitHub Enterprise Cloud with data residency (ghe.com)

GitHub Enterprise Cloud can also make use of the remote server.

Example for https://octocorp.ghe.com with GitHub PAT token:

{
    ...
    "github-octocorp": {
      "type": "http",
      "url": "https://copilot-api.octocorp.ghe.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:github_mcp_pat}"
      }
    },
    ...
}

Note: When using OAuth with GitHub Enterprise with VS Code and GitHub Copilot, you also need to configure your VS Code settings to point to your GitHub Enterprise instance - see Authenticate from VS Code

GitHub Enterprise Server

GitHub Enterprise Server does not support remote server hosting. Please refer to GitHub Enterprise Server and Enterprise Cloud with data residency (ghe.com) from the local server configuration.

Local GitHub MCP Server

Prerequisites

To run the server in a container, you will need to have Docker installed.
Once Docker is installed, you will also need to ensure Docker is running. The Docker image is available at ghcr.io/github/github-mcp-server. The image is public; if you get errors on pull, you may have an expired token and need to docker logout ghcr.io.
Authentication. On github.com you don't need to create anything up front — the one-click buttons above log you in with OAuth on first use (a browser-based flow; the token is kept in memory only). The Docker buttons publish a fixed callback port (127.0.0.1:8085) so the container's login callback is reachable. See Local Server OAuth Login for how it works, headless/device-code fallback, and bringing your own OAuth or GitHub App (required for GitHub Enterprise Server and ghe.com).

Prefer a token? You can still authenticate with a GitHub Personal Access Token by setting GITHUB_PERSONAL_ACCESS_TOKEN instead (it takes precedence over OAuth). The MCP server can use many of the GitHub APIs, so enable the permissions that you feel comfortable granting your AI tools (to learn more about access tokens, please check out the documentation).

Handling PATs Securely

Environment Variables (Recommended)

To keep your GitHub PAT secure and reusable across different MCP hosts:

Store your PAT in environment variables

export GITHUB_PAT=your_token_here

Or create a .env file:

GITHUB_PAT=your_token_here

Protect your .env file

# Add to .gitignore to prevent accidental commits
echo ".env" >> .gitignore

Reference the token in configurations

# CLI usage
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PAT -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

# In config files (where supported)
"env": {
  "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT"
}

Note: Environment variable support varies by host app and IDE. Some applications (like Windsurf) require hardcoded tokens in config files.

Token Security Best Practices

Minimum scopes: Only grant necessary permissions
- repo - Repository operations
- read:packages - Docker image access
- read:org - Organization team access
Separate tokens: Use different PATs for different projects/environments
Regular rotation: Update tokens periodically
Never commit: Keep tokens out of version control
File permissions: Restrict access to config files containing tokens
```
chmod 600 ~/.your-app/config.json
```

GitHub Enterprise Server and Enterprise Cloud with data residency (ghe.com)

The flag --gh-host and the environment variable GITHUB_HOST can be used to set the hostname for GitHub Enterprise Server or GitHub Enterprise Cloud with data residency.

For GitHub Enterprise Server, prefix the hostname with the https:// URI scheme. HTTPS is required and enforced: non-HTTPS hosts are refused so that credentials are never sent over cleartext (the only exception is a loopback host such as http://localhost for local development).
For GitHub Enterprise Cloud with data residency, use https://YOURSUBDOMAIN.ghe.com as the hostname.

"github": {
    "command": "docker",
    "args": [
    "run",
    "-i",
    "--rm",
    "-e",
    "GITHUB_PERSONAL_ACCESS_TOKEN",
    "-e",
    "GITHUB_HOST",
    "ghcr.io/github/github-mcp-server"
    ],
    "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}",
        "GITHUB_HOST": "https://<your GHES or ghe.com domain name>"
    }
}

Installation

Install in GitHub Copilot on VS Code

For quick installation, use one of the one-click install buttons above. Once you complete that flow, toggle Agent mode (located by the Copilot Chat text input) and the server will start.

More about using MCP server tools in VS Code's agent mode documentation.

Install in GitHub Copilot on other IDEs (JetBrains, Visual Studio, Eclipse, etc.)

Add one of the following JSON blocks to your IDE's MCP settings.

Log in with OAuth (no token to create or store). On github.com the official image already includes the app credentials, so you provide none yourself: it runs a browser-based login on first use and keeps the resulting token in memory only. In Docker this needs a fixed callback port published to loopback so the container's login callback is reachable:

{
  "mcp": {
    "servers": {
      "github": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-p",
          "127.0.0.1:8085:8085",
          "-e",
          "GITHUB_OAUTH_CALLBACK_PORT",
          "ghcr.io/github/github-mcp-server"
        ],
        "env": {
          "GITHUB_OAUTH_CALLBACK_PORT": "8085"
        }
      }
    }
  }
}

See Local Server OAuth Login for the native-binary flow (no fixed port needed), the headless/device-code fallback, GitHub Enterprise Server / ghe.com, and bringing your own OAuth or GitHub App.

For non-interactive stdio deployments, see GitHub App Authentication.

Or authenticate with a Personal Access Token. Set GITHUB_PERSONAL_ACCESS_TOKEN instead (it takes precedence over OAuth):

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "github_token",
        "description": "GitHub Personal Access Token",
        "password": true
      }
    ],
    "servers": {
      "github": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "GITHUB_PERSONAL_ACCESS_TOKEN",
          "ghcr.io/github/github-mcp-server"
        ],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
        }
      }
    }
  }
}

Optionally, you can add a similar example (i.e. without the mcp key) to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with other host applications that accept the same format.

Example JSON block without the MCP key included

{
  "inputs": [
    {
      "type": "promptString",
      "id": "github_token",
      "description": "GitHub Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
      }
    }
  }
}

Install in Other MCP Hosts

For other MCP host applications, please refer to our installation guides:

Copilot CLI - Installation guide for GitHub Copilot CLI
GitHub Copilot in other IDEs - Installation for JetBrains, Visual Studio, Eclipse, and Xcode with GitHub Copilot
Claude Code & Claude Desktop - Installation guide for Claude Code and Claude Desktop
Cursor - Installation guide for Cursor IDE
Google Gemini CLI - Installation guide for Google Gemini CLI
OpenCode - Installation guide for the OpenCode terminal agent
Windsurf - Installation guide for Windsurf IDE
Zed - Installation guide for Zed editor

For a complete overview of all installation options, see our Installation Guides Index.

Note: Any host application that supports local MCP servers should be able to access the local GitHub MCP server. However, the specific configuration process, syntax and stability of the integration will vary by host application. While many may follow a similar format to the examples above, this is not guaranteed. Please refer to your host application's documentation for the correct MCP configuration syntax and setup process.

Build from source

If you don't have Docker, you can use go build to build the binary in the cmd/github-mcp-server directory, and use the github-mcp-server stdio command with the GITHUB_PERSONAL_ACCESS_TOKEN environment variable set to your token. To specify the output location of the build, use the -o flag. You should configure your server to use the built executable as its command. For example:

{
  "mcp": {
    "servers": {
      "github": {
        "command": "/path/to/github-mcp-server",
        "args": ["stdio"],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
        }
      }
    }
  }
}

CLI utilities

The github-mcp-server binary includes a few CLI subcommands that are helpful for debugging and exploring the server.

github-mcp-server tool-search "<query>" searches tools by name, description, and input parameter names. Use --max-results to return more matches. Example (color output requires a TTY; use docker run -t (or -it) when running in Docker):

docker run -it --rm ghcr.io/github/github-mcp-server tool-search "issue" --max-results 5
github-mcp-server tool-search "issue" --max-results 5

Tool Configuration

The GitHub MCP Server supports enabling or disabling specific groups of functionalities via the --toolsets flag. This allows you to control which GitHub API capabilities are available to your AI tools. Enabling only the toolsets that you need can help the LLM with tool choice and reduce the context size.

Toolsets are not limited to Tools. Relevant MCP Resources and Prompts are also included where applicable.

When no toolsets are specified, default toolsets are used.

Looking for examples? See the Server Configuration Guide for common recipes like minimal setups, read-only mode, and combining tools with toolsets.

Specifying Toolsets

To specify toolsets you want available to the LLM, you can pass an allow-list in two ways:

Using Command Line Argument:

github-mcp-server --toolsets repos,issues,pull_requests,actions,code_security

Using Environment Variable:

GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security" ./github-mcp-server

The environment variable GITHUB_TOOLSETS takes precedence over the command line argument if both are provided.

Specifying Individual Tools

You can also configure specific tools using the --tools flag. Tools can be used independently or combined with toolsets for fine-grained control.

Using Command Line Argument:

github-mcp-server --tools get_file_contents,issue_read,create_pull_request

Using Environment Variable:

GITHUB_TOOLS="get_file_contents,issue_read,create_pull_request" ./github-mcp-server

Combining with Toolsets (additive):
```
github-mcp-server --toolsets repos,issues --tools get_gist
```
This registers all tools from repos and issues toolsets, plus get_gist.

Important Notes:

Tools and toolsets can be used together
Read-only mode takes priority: write tools are skipped if --read-only is set, even if explicitly requested via --tools
Tool names must match exactly (e.g., get_file_contents, not getFileContents). Invalid tool names will cause the server to fail at startup with an error message
When tools are renamed, old names are preserved as aliases for backward compatibility. See Tool Renaming for details.

Using Toolsets With Docker

When using Docker, you can pass the toolsets as environment variables:

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
  -e GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security" \
  ghcr.io/github/github-mcp-server

Using Tools With Docker

When using Docker, you can pass specific tools as environment variables. You can also combine tools with toolsets:

# Tools only
docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
  -e GITHUB_TOOLS="get_file_contents,issue_read,create_pull_request" \
  ghcr.io/github/github-mcp-server

# Tools combined with toolsets (additive)
docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
  -e GITHUB_TOOLSETS="repos,issues" \
  -e GITHUB_TOOLS="get_gist" \
  ghcr.io/github/github-mcp-server

Special toolsets

"all" toolset

The special toolset all can be provided to enable all available toolsets regardless of any other configuration:

./github-mcp-server --toolsets all

Or using the environment variable:

GITHUB_TOOLSETS="all" ./github-mcp-server

"default" toolset

The default toolset default is the configuration that gets passed to the server if no toolsets are specified.

The default configuration is:

context
repos
issues
pull_requests
users

To keep the default configuration and add additional toolsets:

GITHUB_TOOLSETS="default,stargazers" ./github-mcp-server

Insiders Mode

The local GitHub MCP Server offers an insiders version with early access to new features and experimental tools.

Using Command Line Argument:
```
./github-mcp-server --insiders
```

Using Environment Variable:

GITHUB_INSIDERS=true ./github-mcp-server

When using Docker:

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
  -e GITHUB_INSIDERS=true \
  ghcr.io/github/github-mcp-server

Available Toolsets

The following sets of tools are available:

	Toolset	Description
	`context`	Strongly recommended: Tools that provide context about the current user and GitHub context you are operating in
	`actions`	GitHub Actions workflows and CI/CD operations
	`code_quality`	GitHub Code Quality related tools
	`code_security`	Code security related tools, such as GitHub Code Scanning
	`copilot`	Copilot related tools
	`copilot_issue_intents`	Opt-in Copilot issue assignment tools that carry intent metadata (rationale, confidence, suggestion)
	`dependabot`	Dependabot tools
	`discussions`	GitHub Discussions related tools
	`gists`	GitHub Gist related tools
	`git`	GitHub Git API related tools for low-level Git operations
	`issues`	GitHub Issues related tools
	`labels`	GitHub Labels related tools
	`notifications`	GitHub Notifications related tools
	`orgs`	GitHub Organization related tools
	`projects`	GitHub Projects related tools
	`pull_requests`	GitHub Pull Request related tools
	`repos`	GitHub Repository related tools
	`secret_protection`	Secret protection related tools, such as GitHub Secret Scanning
	`security_advisories`	Security advisories related tools
	`stargazers`	GitHub Stargazers related tools
	`users`	GitHub User related tools

Additional Toolsets in Remote GitHub MCP Server

Toolset	Description
`copilot`	Copilot related tools (e.g. Copilot Coding Agent)
`copilot_spaces`	Copilot Spaces related tools
`github_support_docs_search`	Search docs to answer GitHub product and support questions

Tools

Actions

actions_get - Get details of GitHub Actions resources (workflows, workflow runs, jobs, and artifacts)
- Required OAuth Scopes: repo
- method: The method to execute (string, required)
- owner: Repository owner (string, required)
- repo: Repository name (string, required)
- resource_id: The unique identifier of the resource. This will vary based on the "method" provided, so ensure you provide the correct ID:
  - Provide a workflow ID or workflow file name (e.g. ci.yaml) for 'get_workflow' method.
  - Provide a workflow run ID for 'get_workflow_run', 'get_workflow_run_usage', and 'get_workflow_run_logs_url' methods.
  - Provide an artifact ID for 'download_workflow_run_artifact' method.
  - Provide a job ID for 'get_workflow_job' method. (string, required)
actions_list - List GitHub Actions workflows in a repository
- Required OAuth Scopes: repo
- method: The action to perform (string, required)
- owner: Repository owner (string, required)
- page: Page number for pagination (default: 1) (number, optional)
- per_page: Results per page for pagination (default: 30, max: 100) (number, optional)
- repo: Repository name (string, required)
- resource_id: The unique identifier of the resource. This will vary based on the "method" provided, so ensure you provide the correct ID:
  - Do not provide any resource ID for 'list_workflows' method.
  - Provide a workflow ID or workflow file name (e.g. ci.yaml) for 'list_workflow_runs' method, or omit to list all workflow runs in the repository.
  - Provide a workflow run ID for 'list_workflow_jobs' and 'list_workflow_run_artifacts' methods. (string, optional)
- workflow_jobs_filter: Filters for workflow jobs. ONLY used when method is 'list_workflow_jobs' (object, optional)
- workflow_runs_filter: Filters for workflow runs. ONLY used when method is 'list_workflow_runs' (object, optional)
actions_run_trigger - Trigger GitHub Actions workflow actions
- Required OAuth Scopes: repo
- inputs: Inputs the workflow accepts. Only used for 'run_workflow' method. (object, optional)
- method: The method to execute (string, required)
- owner: Repository owner (string, required)
- ref: The git reference for the workflow. The reference can be a branch or tag name. Required for 'run_workflow' method. (string, optional)
- repo: Repository name (string, required)
- run_id: The ID of the workflow run. Required for all methods except 'run_workflow'. (number, optional)
- workflow_id: The workflow ID (numeric) or workflow file name (e.g., main.yml, ci.yaml). Required for 'run_workflow' method. (string, optional)
get_job_logs - Get GitHub Actions workflow job logs
- Required OAuth Scopes: repo
- failed_only: When true, gets logs for all failed jobs in the workflow run specified by run_id. Requires run_id to be provided. (boolean, optional)
- job_id: The unique identifier of the workflow job. Required when getting logs for a single job. (number, optional)
- owner: Repository owner (string, required)
- repo: Repository name (string, required)
- return_content: Returns actual log content instead of URLs (boolean, optional)
- run_id: The unique identifier of the workflow run. Required when failed_only is true to get logs for all failed jobs in the run. (number, optional)
- tail_lines: Number of lines to return from the end of the log (number, optional)

Code Quality

get_code_quality_finding - Get code quality finding
- Required OAuth Scopes: repo
- findingNumber: The number of the finding. (number, required)
- owner: The owner of the repository. (string, required)
- repo: The name of the repository. (string, required)

Code Security

get_code_scanning_alert - Get code scanning alert
- Required OAuth Scopes: security_events
- Accepted OAuth Scopes: repo, security_events
- alertNumber: The number of the alert. (number, required)
- owner: The owner of the repository. (string, required)
- repo: The name of the repository. (string, required)
list_code_scanning_alerts - List code scanning alerts
- Required OAuth Scopes: security_events
- Accepted OAuth Scopes: repo, security_events
- owner: The owner of the repository. (string, required)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- ref: The Git reference for the results you want to list. (string, optional)
- repo: The name of the repository. (string, required)
- severity: Filter code scanning alerts by severity (string, optional)
- state: Filter code scanning alerts by state. Defaults to open (string, optional)
- tool_name: The name of the tool used for code scanning. (string, optional)

Context

get_me - Get my user profile
- No parameters required
get_team_members - Get team members
- Required OAuth Scopes: read:org
- Accepted OAuth Scopes: admin:org, read:org, write:org
- org: Organization login (owner) that contains the team. (string, required)
- team_slug: Team slug (string, required)
get_teams - Get teams
- Required OAuth Scopes: read:org
- Accepted OAuth Scopes: admin:org, read:org, write:org
- user: Username to get teams for. If not provided, uses the authenticated user. (string, optional)

Copilot

assign_copilot_to_issue - Assign Copilot to issue
- Required OAuth Scopes: repo
- base_ref: Git reference (e.g., branch) that the agent will start its work from. If not specified, defaults to the repository's default branch (string, optional)
- custom_instructions: Optional custom instructions to guide the agent beyond the issue body. Use this to provide additional context, constraints, or guidance that is not captured in the issue description (string, optional)
- issue_number: Issue number (number, required)
- owner: Repository owner (string, required)
- repo: Repository name (string, required)
request_copilot_review - Request Copilot review
- Required OAuth Scopes: repo
- owner: Repository owner (string, required)
- pullNumber: Pull request number (number, required)
- repo: Repository name (string, required)

Copilot Issue Intents

assign_copilot_to_issue_with_intent - Assign Copilot to issue with intent
- Required OAuth Scopes: repo
- base_ref: Git reference (e.g., branch) that the agent will start its work from. If not specified, defaults to the repository's default branch. Ignored when is_suggestion is true (string, optional)
- confidence: How confident you are in this choice. 'HIGH' for clear signal or explicit user request, 'MEDIUM' for reasonable inference with some ambiguity, 'LOW' for best guess with limited signal. (string, required)
- custom_instructions: Optional custom instructions to guide the agent beyond the issue body. Ignored when is_suggestion is true (string, optional)
- is_suggestion: If true, records a pending Copilot assignment intent rather than launching the agent. Approval later supplies the launch context; base_ref and custom_instructions are ignored in this case. (boolean, required)
- issue_number: Issue number (number, required)
- owner: Repository owner (string, required)
- rationale: One concise sentence explaining what specifically about the issue led to choosing Copilot. State the concrete signal (e.g. 'Well-scoped task with clear acceptance criteria'). (string, required)
- repo: Repository name (string, required)

Dependabot

get_dependabot_alert - Get dependabot alert
- Required OAuth Scopes: security_events
- Accepted OAuth Scopes: repo, security_events
- alertNumber: The number of the alert. (number, required)
- owner: The owner of the repository. (string, required)
- repo: The name of the repository. (string, required)
list_dependabot_alerts - List dependabot alerts
- Required OAuth Scopes: security_events
- Accepted OAuth Scopes: repo, security_events
- after: Cursor for pagination. Use the cursor from the previous response. (string, optional)
- owner: The owner of the repository. (string, required)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- repo: The name of the repository. (string, required)
- severity: Filter dependabot alerts by severity (string, optional)
- state: Filter dependabot alerts by state. Defaults to open (string, optional)

Discussions

discussion_comment_write - Manage discussion comments
- Required OAuth Scopes: repo
- body: Comment content (required for 'add', 'reply', and 'update' methods) (string, optional)
- commentNodeID: The Node ID of the discussion comment (required for 'reply', 'update', 'delete', 'mark_answer', and 'unmark_answer' methods). For 'reply', this is the top-level comment to reply to; GitHub Discussions only support one level of nesting. (string, optional)
- discussionNumber: Discussion number (required for 'add' and 'reply' methods) (number, optional)
- method: Write operation to perform on a discussion comment. Options are:
  - 'add' - adds a new top-level comment to a discussion.
  - 'reply' - replies to a top-level discussion comment (GitHub Discussions only support one level of nesting).
  - 'update' - updates an existing discussion comment.
  - 'delete' - deletes a discussion comment.
  - 'mark_answer' - marks a discussion comment as the answer (Q&A only).
  - 'unmark_answer' - unmarks a discussion comment as the answer (Q&A only). (string, required)
- owner: Repository owner (required for 'add' and 'reply' methods) (string, optional)
- repo: Repository name (required for 'add' and 'reply' methods) (string, optional)
get_discussion - Get discussion
- Required OAuth Scopes: repo
- discussionNumber: Discussion Number (number, required)
- owner: Repository owner (string, required)
- repo: Repository name (string, required)
get_discussion_comments - Get discussion comments
- Required OAuth Scopes: repo
- after: Cursor for pagination. Use the cursor from the previous response. (string, optional)
- discussionNumber: Discussion Number (number, required)
- includeReplies: When true, each top-level comment will include its replies nested within it (up to 100 replies per comment, which is the GitHub API maximum). Defaults to false. (boolean, optional)
- owner: Repository owner (string, required)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- repo: Repository name (string, required)
list_discussion_categories - List discussion categories
- Required OAuth Scopes: repo
- owner: Repository owner (string, required)
- repo: Repository name. If not provided, discussion categories will be queried at the organisation level. (string, optional)
list_discussions - List discussions
- Required OAuth Scopes: repo
- after: Cursor for pagination. Use the cursor from the previous response. (string, optional)
- category: Optional filter by discussion category ID. If provided, only discussions with this category are listed. (string, optional)
- direction: Order direction. (string, optional)
- orderBy: Order discussions by field. If provided, the 'direction' also needs to be provided. (string, optional)
- owner: Repository owner (string, required)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- repo: Repository name. If not provided, discussions will be queried at the organisation level. (string, optional)

Gists

create_gist - Create Gist
- Required OAuth Scopes: gist
- content: Content for simple single-file gist creation (string, required)
- description: Description of the gist (string, optional)
- filename: Filename for simple single-file gist creation (string, required)
- public: Whether the gist is public (boolean, optional)
get_gist - Get Gist Content
- gist_id: The ID of the gist (string, required)
list_gists - List Gists
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- since: Only gists updated after this time (ISO 8601 timestamp) (string, optional)
- username: GitHub username (omit for authenticated user's gists) (string, optional)
update_gist - Update Gist
- Required OAuth Scopes: gist
- content: Content for the file (string, required)
- description: Updated description of the gist (string, optional)
- filename: Filename to update or create (string, required)
- gist_id: ID of the gist to update (string, required)

Git

get_repository_tree - Get repository tree
- Required OAuth Scopes: repo
- owner: Repository owner (username or organization) (string, required)
- path_filter: Optional path prefix to filter the tree results (e.g., 'src/' to only show files in the src directory) (string, optional)
- recursive: Setting this parameter to true returns the objects or subtrees referenced by the tree. Default is false (boolean, optional)
- repo: Repository name (string, required)
- tree_sha: The SHA1 value or ref (branch or tag) name of the tree. Defaults to the repository's default branch (string, optional)

Issues

add_issue_comment - Add comment to issue or pull request
- Required OAuth Scopes: repo
- body: Comment content. Required unless reaction is provided. (string, optional)
- comment_id: The numeric ID of the issue or pull request comment to react to. Use this for reactions to comments; omit it to react to the issue or pull request itself. Cannot be combined with body. (number, optional)
- issue_number: Issue or pull request number to comment on or react to. (number, required)
- owner: Repository owner (string, required)
- reaction: Emoji reaction to add. Required unless body is provided. (string, optional)
- repo: Repository name (string, required)
get_label - Get a specific label from a repository
- Required OAuth Scopes: repo
- name: Label name. (string, required)
- owner: Repository owner (username or organization name) (string, required)
- repo: Repository name (string, required)
issue_read - Get issue details
- Required OAuth Scopes: repo
- issue_number: The number of the issue (number, required)
- method: The read operation to perform on a single issue. Options are:
  1. get - Get issue details. Also returns best-effort hierarchy flags (has_parent, has_children); parent and sub_issues_summary are optional relationship summaries, and closed_by_pull_requests summarizes the pull requests configured to close the issue as total_count plus up to 5 references.
  2. get_comments - Get issue comments.
  3. get_sub_issues - Get sub-issues (children) of the issue.
  4. get_parent - Get the parent issue, if this issue is a sub-issue of another.
  5. get_labels - Get labels assigned to the issue. (string, required)
- owner: The owner of the repository (string, required)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- repo: The name of the repository (string, required)
issue_write - Create or update issue/pull request
- Required OAuth Scopes: repo
- assignees: Usernames to assign to this issue (string[], optional)
- body: Issue body content (string, optional)
- duplicate_of: Issue number that this issue is a duplicate of. Required when state_reason is 'duplicate'. (number, optional)
- issue_fields: Issue field values to set or clear. Each item requires 'field_name' and exactly one of 'value', 'field_option_name', or 'delete: true'. (object[], optional)
- issue_number: Issue number to update (number, optional)
- labels: Labels to apply to this issue (string[], optional)
- method: Write operation to perform on a single issue. Options are:
  - 'create' - creates a new issue.
  - 'update' - updates an existing issue. (string, required)
- milestone: Milestone number (number, optional)
- owner: Repository owner (string, required)
- repo: Repository name (string, required)
- state: New state (string, optional)
- state_reason: Reason for the state change. Ignored unless state is changed. (string, optional)
- title: Issue title (string, optional)
- type: Type of this issue. For updates, pass null to remove the current type. Only use if issue types are enabled for this repository. Use list_issue_types to get valid type values for this repository or its owner organization. If the repository doesn't support issue types, omit this parameter. (string | null, optional)
list_issue_fields - List issue fields
- Required OAuth Scopes (any of): repo, read:org
- Accepted OAuth Scopes: admin:org, read:org, repo, write:org
- owner: The account owner of the repository or organization. The name is not case sensitive. (string, required)
- repo: The name of the repository. When provided, returns fields for this specific repository (inherited from its organization). When omitted, returns org-level fields directly. (string, optional)
list_issue_types - List available issue types
- Required OAuth Scopes (any of): repo, read:org
- Accepted OAuth Scopes: admin:org, read:org, repo, write:org
- owner: The account owner of the repository or organization. (string, required)
- repo: The name of the repository. When provided, returns issue types for this specific repository. When omitted, returns org-level issue types directly. (string, optional)
list_issues - List issues
- Required OAuth Scopes: repo
- after: Cursor for pagination. Use the cursor from the previous response. (string, optional)
- direction: Order direction. If provided, the 'orderBy' also needs to be provided. (string, optional)
- field_filters: Filter by custom issue field values. Each entry takes a field_name and a value; the server looks up the field and coerces the value to its type (single-select option name, text, number, or YYYY-MM-DD date). (object[], optional)
- fields: Subset of fields to return for each issue. If omitted, all fields are returned. Use this to reduce response size when you only need specific fields; omitting 'body' and 'field_values' in particular drops the largest per-result data. (string[], optional)
- labels: Filter by labels (string[], optional)
- orderBy: Order issues by field. If provided, the 'direction' also needs to be provided. (string, optional)
- owner: Repository owner (string, required)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- repo: Repository name (string, required)
- since: Filter by date (ISO 8601 timestamp) (string, optional)
- state: Filter by state, by default both open and closed issues are returned when not provided (string, optional)
search_issues - Search issues
- Required OAuth Scopes: repo
- fields: Subset of fields to return for each issue result. If omitted, all fields are returned. Use this to reduce response size when you only need specific fields; omitting 'body', 'reactions', and 'labels' in particular drops the largest per-result data. (string[], optional)
- order: Sort order (string, optional)
- owner: Optional repository owner. If provided with repo, only issues for this repository are listed. (string, optional)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- query: The search query, as natural language. When the user gives alternative wordings, include them as plain words rather than joining them with OR. (string, required)
- repo: Optional repository name. If provided with owner, only issues for this repository are listed. (string, optional)
- sort: Sort field by number of matches of categories, defaults to best match (string, optional)
sub_issue_write - Change sub-issue
- Required OAuth Scopes: repo
- after_id: The ID of the sub-issue to be prioritized after (either after_id OR before_id should be specified) (number, optional)
- before_id: The ID of the sub-issue to be prioritized before (either after_id OR before_id should be specified) (number, optional)
- issue_number: The number of the parent issue (number, required)
- method: The action to perform on a single sub-issue Options are:
  - 'add' - add a sub-issue to a parent issue in a GitHub repository.
  - 'remove' - remove a sub-issue from a parent issue in a GitHub repository.
  - 'reprioritize' - change the order of sub-issues within a parent issue in a GitHub repository. Use either 'after_id' or 'before_id' to specify the new position. Writes issue hierarchy. To move a sub-issue to a new parent, use add with replace_parent=true; there is no writable parent field. (string, required)
- owner: Repository owner (string, required)
- replace_parent: When true, replaces the sub-issue's current parent issue. Use with 'add' method only. (boolean, optional)
- repo: Repository name (string, required)
- sub_issue_id: The ID of the sub-issue to add. ID is not the same as issue number (number, required)

Labels

get_label - Get a specific label from a repository
- Required OAuth Scopes: repo
- name: Label name. (string, required)
- owner: Repository owner (username or organization name) (string, required)
- repo: Repository name (string, required)
label_write - Write operations on repository labels
- Required OAuth Scopes: repo
- color: Label color as 6-character hex code without '#' prefix (e.g., 'f29513'). Required for 'create', optional for 'update'. (string, optional)
- description: Label description text. Optional for 'create' and 'update'. (string, optional)
- method: Operation to perform: 'create', 'update', or 'delete' (string, required)
- name: Label name - required for all operations (string, required)
- new_name: New name for the label (used only with 'update' method to rename) (string, optional)
- owner: Repository owner (username or organization name) (string, required)
- repo: Repository name (string, required)
list_label - List labels from a repository
- Required OAuth Scopes: repo
- owner: Repository owner (username or organization name) - required for all operations (string, required)
- repo: Repository name - required for all operations (string, required)

Notifications

dismiss_notification - Dismiss notification
- Required OAuth Scopes: notifications
- state: The new state of the notification (read/done) (string, required)
- threadID: The ID of the notification thread (string, required)
get_notification_details - Get notification details
- Required OAuth Scopes: notifications
- notificationID: The ID of the notification (string, required)
list_notifications - List notifications
- Required OAuth Scopes: notifications
- before: Only show notifications updated before the given time (ISO 8601 format) (string, optional)
- filter: Filter notifications to, use default unless specified. Read notifications are ones that have already been acknowledged by the user. Participating notifications are those that the user is directly involved in, such as issues or pull requests they have commented on or created. (string, optional)
- owner: Optional repository owner. If provided with repo, only notifications for this repository are listed. (string, optional)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- repo: Optional repository name. If provided with owner, only notifications for this repository are listed. (string, optional)
- since: Only show notifications updated after the given time (ISO 8601 format) (string, optional)
manage_notification_subscription - Manage notification subscription
- Required OAuth Scopes: notifications
- action: Action to perform: ignore, watch, or delete the notification subscription. (string, required)
- notificationID: The ID of the notification thread. (string, required)
manage_repository_notification_subscription - Manage repository notification subscription
- Required OAuth Scopes: notifications
- action: Action to perform: ignore, watch, or delete the repository notification subscription. (string, required)
- owner: The account owner of the repository. (string, required)
- repo: The name of the repository. (string, required)
mark_all_notifications_read - Mark all notifications as read
- Required OAuth Scopes: notifications
- lastReadAt: Describes the last point that notifications were checked (optional). Default: Now (string, optional)
- owner: Optional repository owner. If provided with repo, only notifications for this repository are marked as read. (string, optional)
- repo: Optional repository name. If provided with owner, only notifications for this repository are marked as read. (string, optional)

Organizations

search_orgs - Search organizations
- Required OAuth Scopes: read:org
- Accepted OAuth Scopes: admin:org, read:org, write:org
- order: Sort order (string, optional)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- query: Organization search query. Examples: 'microsoft', 'location:california', 'created:>=2025-01-01'. Search is automatically scoped to type:org. (string, required)
- sort: Sort field by category (string, optional)

Projects

projects_get - Get details of GitHub Projects resources
- Required OAuth Scopes: read:project
- Accepted OAuth Scopes: project, read:project
- field_id: The field's ID. Required for 'get_project_field' method. (number, optional)
- field_names: Specific list of field names to include in the response when getting a project item (e.g. ["Status", "Priority"]). Resolved server-side to field IDs — pass this instead of 'fields' when you only know the human-readable names. Mutually exclusive with 'fields' — provide one, not both. Only used for 'get_project_item' method. (string[], optional)
- fields: Specific list of field IDs to include in the response when getting a project item (e.g. ["102589", "985201", "169875"]). If neither 'fields' nor 'field_names' is provided, only the title field is included. Mutually exclusive with 'field_names' — provide one, not both. Only used for 'get_project_item' method. (string[], optional)
- item_id: The item's ID. Required for 'get_project_item' method. (number, optional)
- method: The method to execute (string, required)
- owner: The owner (user or organization login). The name is not case sensitive. (string, optional)
- owner_type: Owner type (user or org). If not provided, will be automatically detected. (string, optional)
- project_number: The project's number. (number, optional)
- status_update_id: The node ID of the project status update. Required for 'get_project_status_update' method. (string, optional)
- view_id: The node ID of the project view. Required for 'get_project_view' method. (string, optional)
projects_list - List GitHub Projects resources
- Required OAuth Scopes: read:project
- Accepted OAuth Scopes: project, read:project
- after: Forward pagination cursor from previous pageInfo.nextCursor. (string, optional)
- before: Backward pagination cursor from previous pageInfo.prevCursor (rare). (string, optional)
- field_names: Field names to include when listing project items (e.g. ["Status", "Priority"]). Resolved server-side to field IDs — pass this instead of 'fields' when you only know the human-readable names. Names that fail to resolve return a structured error. Mutually exclusive with 'fields' — provide one, not both. Only used for 'list_project_items' method. (string[], optional)
- fields: Field IDs to include when listing project items (e.g. ["102589", "985201"]). CRITICAL: Always provide to get field values. Without this (and without 'field_names'), only titles returned. Mutually exclusive with 'field_names' — provide one, not both. Only used for 'list_project_items' method. (string[], optional)
- method: The action to perform (string, required)
- owner: The owner (user or organization login). The name is not case sensitive. (string, required)
- owner_type: Owner type (user or org). If not provided, will automatically try both. (string, optional)
- per_page: Results per page (max 50) (number, optional)
- project_number: The project's number. Required for 'list_project_fields', 'list_project_items', 'list_project_views', and 'list_project_status_updates' methods. (number, optional)
- query: Filter/query string. For list_projects: filter by title text and state (e.g. "roadmap is:open"). For list_project_items: advanced filtering using GitHub's project filtering syntax. (string, optional)
projects_write - Manage GitHub Projects
- Required OAuth Scopes: project
- body: The body of the status update (markdown). Used for 'create_project_status_update' method. (string, optional)
- field_name: The name of the iteration field (e.g. 'Sprint'). Required for 'create_iteration_field' method. (string, optional)
- filter: Saved view filter; omit on update to preserve it, or pass null to clear it. (string | null, optional)
- issue_number: The issue number. Required for 'add_project_item' when item_type is 'issue'. Also accepted by 'update_project_item' to resolve the item by issue number (combine with item_owner and item_repo). (number, optional)
- item_id: The project item ID. Required for 'delete_project_item'. For 'update_project_item', provide either item_id, or (item_owner + item_repo + issue_number) to resolve the item by issue. (number, optional)
- item_owner: The owner (user or organization) of the repository containing the issue or pull request. Required for 'add_project_item' method. Also accepted by 'update_project_item' when resolving the item by issue number. (string, optional)
- item_repo: The name of the repository containing the issue or pull request. Required for 'add_project_item' method. Also accepted by 'update_project_item' when resolving the item by issue number. (string, optional)
- item_type: The item's type, either issue or pull_request. Required for 'add_project_item' method. (string, optional)
- items: The items to update with the top-level 'updated_field'. Required for 'update_project_items'; prefer it over calling 'update_project_item' in a loop. Each entry must match exactly one reference variant: 'node_id', numeric 'item_id', or 'item_owner' + 'item_repo' + 'issue_number'. Limit: 50 items per call. (object[], optional)
- iteration_duration: Duration in days for iterations of the field (e.g. 7 for weekly, 14 for bi-weekly). Required for 'create_iteration_field' method. (number, optional)
- iterations: Custom iterations for 'create_iteration_field' method. Only set this when you need iterations with varying durations, breaks between them, or specific titles. Otherwise omit it: GitHub auto-creates three iterations of 'iteration_duration' days starting on 'start_date', which is the right choice for most cases. (object[], optional)
- layout: View layout; required when creating a view. (string, optional)
- method: The method to execute (string, required)
- name: View name; required when creating a view. (string, optional)
- owner: The project owner (user or organization login). The name is not case sensitive. (string, required)
- owner_type: Owner type (user or org). Required for 'create_project' method. If not provided for other methods, will be automatically detected. (string, optional)
- project_number: The project's number. Required for all methods except 'create_project'. (number, optional)
- pull_request_number: The pull request number (use when item_type is 'pull_request' for 'add_project_item' method). Provide either issue_number or pull_request_number. (number, optional)
- start_date: Start date in YYYY-MM-DD format. Used for 'create_project_status_update' and 'create_iteration_field' methods. (string, optional)
- status: The status of the project. Used for 'create_project_status_update' method. (string, optional)
- target_date: The target date of the status update in YYYY-MM-DD format. Used for 'create_project_status_update' method. (string, optional)
- title: The project title. Required for 'create_project' method. (string, optional)
- updated_field: The field/value to apply, using {"id": 123, "value": ...} or {"name": "Status", "value": ...}; null clears the field. Required for 'update_project_item' and 'update_project_items', where one top-level field/value applies to every item in a batch. For 'update_project_item' SINGLE_SELECT fields, the name form accepts option names; the ID form expects an option ID. (object, optional)
- view_id: Project view node ID for update or delete; must belong to owner/project_number. (string, optional)
- visible_field_names: Ordered project field names to show on create or replace on update; omit on update to preserve, or pass [] to reset. Mutually exclusive with visible_fields. Roadmap accepts only []. (string[], optional)
- visible_fields: Ordered project field database IDs to show on create or replace on update; omit on update to preserve, or pass [] to reset. Mutually exclusive with visible_field_names. Roadmap accepts only []. (string[], optional)

Pull Requests

add_comment_to_pending_review - Add review comment to the requester's latest pending pull request review
- Required OAuth Scopes: repo
- body: The text of the review comment (string, required)
- line: The line of the blob in the pull request diff that the comment applies to. For multi-line comments, the last line of the range (number, optional)
- owner: Repository owner (string, required)
- path: The relative path to the file that necessitates a comment (string, required)
- pullNumber: Pull request number (number, required)
- repo: Repository name (string, required)
- side: The side of the diff to comment on. LEFT indicates the previous state, RIGHT indicates the new state (string, optional)
- startLine: For multi-line comments, the first line of the range that the comment applies to (number, optional)
- startSide: For multi-line comments, the starting side of the diff that the comment applies to. LEFT indicates the previous state, RIGHT indicates the new state (string, optional)
- subjectType: The level at which the comment is targeted (string, required)
add_reply_to_pull_request_comment - Add reply to pull request comment
- Required OAuth Scopes: repo
- body: The text of the reply. Required unless reaction is provided. (string, optional)
- commentId: The numeric ID of the pull request review comment to reply or react to. Use the number from a #discussion_r... anchor, not the GraphQL thread node ID (PRRT_...). (number, required)
- owner: Repository owner (string, required)
- pullNumber: Pull request number. Required when body is provided. (number, optional)
- reaction: Emoji reaction to add. Required unless body is provided. (string, optional)
- repo: Repository name (string, required)
create_pull_request - Open new pull request
- Required OAuth Scopes: repo
- base: Branch to merge into (string, required)
- body: PR description (string, optional)
- draft: Create as draft PR (boolean, optional)
- head: Branch containing changes (string, required)
- maintainer_can_modify: Allow maintainer edits (boolean, optional)
- owner: Repository owner (string, required)
- repo: Repository name (string, required)
- reviewers: GitHub usernames or ORG/team-slug team reviewers to request reviews from (string[], optional)
- title: PR title (string, required)
list_pull_requests - List pull requests
- Required OAuth Scopes: repo
- base: Filter by base branch (string, optional)
- direction: Sort direction (string, optional)
- fields: Subset of fields to return for each pull request. If omitted, all fields are returned. Use this to reduce response size when you only need specific fields; omitting 'body' in particular drops the largest per-result data. (string[], optional)
- head: Filter by head user/org and branch (string, optional)
- owner: Repository owner (string, required)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- repo: Repository name (string, required)
- sort: Sort by (string, optional)
- state: Filter by state (string, optional)
merge_pull_request - Merge pull request
- Required OAuth Scopes: repo
- commit_message: Extra detail for merge commit (string, optional)
- commit_title: Title for merge commit (string, optional)
- merge_method: Merge method (string, optional)
- owner: Repository owner (string, required)
- pullNumber: Pull request number (number, required)
- repo: Repository name (string, required)
pull_request_read - Get details for a single pull request
- Required OAuth Scopes: repo
- after: Cursor for pagination, used only by the get_review_comments method. Pass the endCursor from the previous page's PageInfo to fetch the next page. (string, optional)
- method: Action to specify what pull request data needs to be retrieved from GitHub. Possible options:
  1. get - Get details of a specific pull request.
  2. get_diff - Get the diff of a pull request.
  3. get_status - Get combined commit status of a head commit in a pull request.
  4. get_files - Get the list of files changed in a pull request. Use with pagination parameters to control the number of results returned.
  5. get_commits - Get the list of commits on a pull request. Use with pagination parameters to control the number of results returned.
  6. get_review_comments - Get review threads on a pull request. Each thread contains logically grouped review comments made on the same code location during pull request reviews. Returns threads with metadata (isResolved, isOutdated, isCollapsed) and their associated comments. Use cursor-based pagination (perPage, after) to control results.
  7. get_reviews - Get the reviews on a pull request. When asked for review comments, use get_review_comments method. Use with pagination parameters to control the number of results returned.
  8. get_comments - Get comments on a pull request. Use this if user doesn't specifically want review comments. Use with pagination parameters to control the number of results returned.
  9. get_check_runs - Get check runs for the head commit of a pull request. Check runs are the individual CI/CD jobs and checks that run on the PR. (string, required)
- owner: Repository owner (string, required)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- pullNumber: Pull request number (number, required)
- repo: Repository name (string, required)
pull_request_review_write - Write operations (create, submit, delete) on pull request reviews
- Required OAuth Scopes: repo
- body: Review comment text (string, optional)
- commitID: SHA of commit to review (string, optional)
- event: Review action to perform. (string, optional)
- method: The write operation to perform on pull request review. (string, required)
- owner: Repository owner (string, required)
- pullNumber: Pull request number (number, required)
- repo: Repository name (string, required)
- threadId: The node ID of the review thread (e.g., PRRT_kwDOxxx). Required for resolve_thread and unresolve_thread methods. Get thread IDs from pull_request_read with method get_review_comments. (string, optional)
search_pull_requests - Search pull requests
- Required OAuth Scopes: repo
- fields: Subset of fields to return for each pull request result. If omitted, all fields are returned. Use this to reduce response size when you only need specific fields; omitting 'body', 'reactions', and 'labels' in particular drops the largest per-result data. (string[], optional)
- order: Sort order (string, optional)
- owner: Optional repository owner. If provided with repo, only pull requests for this repository are listed. (string, optional)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- query: Search query using GitHub pull request search syntax (string, required)
- repo: Optional repository name. If provided with owner, only pull requests for this repository are listed. (string, optional)
- sort: Sort field by number of matches of categories, defaults to best match (string, optional)
update_pull_request - Edit pull request
- Required OAuth Scopes: repo
- base: New base branch name (string, optional)
- body: New description (string, optional)
- draft: Mark pull request as draft (true) or ready for review (false) (boolean, optional)
- maintainer_can_modify: Allow maintainer edits (boolean, optional)
- owner: Repository owner (string, required)
- pullNumber: Pull request number to update (number, required)
- repo: Repository name (string, required)
- reviewers: GitHub usernames or ORG/team-slug team reviewers to request reviews from (string[], optional)
- state: New state (string, optional)
- title: New title (string, optional)
update_pull_request_branch - Update pull request branch
- Required OAuth Scopes: repo
- expectedHeadSha: The expected SHA of the pull request's HEAD ref (string, optional)
- owner: Repository owner (string, required)
- pullNumber: Pull request number (number, required)
- repo: Repository name (string, required)

Repositories

create_branch - Create branch
- Required OAuth Scopes: repo
- branch: Name for new branch (string, required)
- from_branch: Source branch (defaults to repo default) (string, optional)
- owner: Repository owner (string, required)
- repo: Repository name (string, required)
create_or_update_file - Create or update file
- Required OAuth Scopes: repo
- branch: Branch to create/update the file in (string, required)
- content: Content of the file, exactly as it should appear once written. Do not base64-encode it; this server does that before calling the REST API. (string, required)
- message: Commit message (string, required)
- owner: Repository owner (username or organization) (string, required)
- path: Path where to create/update the file (string, required)
- repo: Repository name (string, required)
- sha: The blob SHA of the file being replaced. Required if the file already exists. (string, optional)
create_repository - Create repository
- Required OAuth Scopes: repo
- autoInit: Initialize with README (boolean, optional)
- description: Repository description (string, optional)
- name: Repository name (string, required)
- organization: Organization to create the repository in (omit to create in your personal account) (string, optional)
- private: Whether the repository should be private. Defaults to true (private) when omitted. (boolean, optional)
delete_file - Delete file
- Required OAuth Scopes: repo
- branch: Branch to delete the file from (string, required)
- message: Commit message (string, required)
- owner: Repository owner (username or organization) (string, required)
- path: Path to the file to delete (string, required)
- repo: Repository name (string, required)
fork_repository - Fork repository
- Required OAuth Scopes: repo
- organization: Organization to fork to (string, optional)
- owner: Repository owner (string, required)
- repo: Repository name (string, required)
get_commit - Get commit details
- Required OAuth Scopes: repo
- detail: Level of detail to include for changed files. "none" omits stats and files entirely. "stats" (default) includes per-file metadata: filename, status, and lines-of-code counts (additions, deletions, changes), with no patch content. "full_patch" additionally includes the unified diff content for each file and can be very large. (string, optional)
- owner: Repository owner (string, required)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- repo: Repository name (string, required)
- sha: Commit SHA, branch name, or tag name (string, required)
get_file_contents - Get file or directory contents
- Required OAuth Scopes: repo
- fields: Subset of fields to return for each entry when the path is a directory. If omitted, all fields are returned. Ignored when the path is a single file. Use this to reduce response size when listing directories and you only need specific fields, e.g. just 'name' and 'type'. (string[], optional)
- owner: Repository owner (username or organization) (string, required)
- path: Path to file/directory (string, optional)
- ref: Accepts optional git refs such as refs/tags/{tag}, refs/heads/{branch} or refs/pull/{pr_number}/head (string, optional)
- repo: Repository name (string, required)
- sha: Accepts optional commit SHA. If specified, it will be used instead of ref (string, optional)
get_latest_release - Get latest release
- Required OAuth Scopes: repo
- owner: Repository owner (string, required)
- repo: Repository name (string, required)
get_release_by_tag - Get a release by tag name
- Required OAuth Scopes: repo
- owner: Repository owner (string, required)
- repo: Repository name (string, required)
- tag: Tag name (e.g., 'v1.0.0') (string, required)
get_tag - Get tag details
- Required OAuth Scopes: repo
- owner: Repository owner (string, required)
- repo: Repository name (string, required)
- tag: Tag name (string, required)
list_branches - List branches
- Required OAuth Scopes: repo
- owner: Repository owner (string, required)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- repo: Repository name (string, required)
list_commits - List commits
- Required OAuth Scopes: repo
- author: Author username or email address to filter commits by (string, optional)
- fields: Subset of fields to return for each commit. If omitted, all fields are returned. Use this to reduce response size when you only need specific fields, e.g. just 'sha' and 'html_url'. (string[], optional)
- owner: Repository owner (string, required)
- page: Page number for pagination (min 1) (number, optional)
- path: Only commits containing this file path will be returned (string, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- repo: Repository name (string, required)
- sha: Commit SHA, branch or tag name to list commits of. If not provided, uses the default branch of the repository. If a commit SHA is provided, will list commits up to that SHA. (string, optional)
- since: Only commits after this date will be returned (ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DD) (string, optional)
- until: Only commits before this date will be returned (ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DD) (string, optional)
list_releases - List releases
- Required OAuth Scopes: repo
- fields: Subset of fields to return for each release. If omitted, all fields are returned. Use this to reduce response size when you only need specific fields; omitting 'body' in particular drops the largest per-release data. (string[], optional)
- owner: Repository owner (string, required)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- repo: Repository name (string, required)
list_repository_collaborators - List repository collaborators
- Required OAuth Scopes: repo
- affiliation: Filter by affiliation. Can be one of: 'outside' (outside collaborators), 'direct' (all with permissions regardless of org membership), 'all' (all collaborators). Default: 'all' (string, optional)
- owner: Repository owner (string, required)
- page: Page number for pagination (default 1, min 1) (number, optional)
- perPage: Results per page for pagination (default 30, min 1, max 100) (number, optional)
- repo: Repository name (string, required)
list_tags - List tags
- Required OAuth Scopes: repo
- owner: Repository owner (string, required)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- repo: Repository name (string, required)
push_files - Push files to repository
- Required OAuth Scopes: repo
- branch: Branch to push to (string, required)
- files: Array of file objects to push, each object with path (string) and content (string) (object[], required)
- message: Commit message (string, required)
- owner: Repository owner (string, required)
- repo: Repository name (string, required)
search_code - Search code
- Required OAuth Scopes: repo
- fields: Subset of fields to return for each code search result. If omitted, all fields are returned. Use this to reduce response size when you only need specific fields; omitting 'repository' and 'text_matches' in particular drops the largest per-result data. (string[], optional)
- order: Sort order for results (string, optional)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- query: Search query (GitHub code search REST). Implicit AND between terms; supports OR, NOT, and "quoted phrase" for exact match. Qualifiers: repo:owner/repo, org:, user:, language:, path:dir (prefix match), filename:exact.ext, extension:, in:file, in:path, size:, is:archived, is:fork. Max 256 chars. Examples: WithContext language:go org:github; "package main" repo:o/r; func extension:go path:cmd repo:o/r; NOT TODO language:go repo:o/r. (string, required)
- sort: Sort field ('indexed' only) (string, optional)
search_commits - Search commits
- Required OAuth Scopes: repo
- order: Sort order (string, optional)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- query: Commit search query (GitHub commit search REST). Searches commit messages on the default branch only. Scope the search with repo:owner/repo, org:, or user: (queries without a scope qualifier match across all of GitHub and are usually not what you want). Other qualifiers: author:, committer:, author-name:, committer-name:, author-email:, committer-email:, author-date:, committer-date: (supports >, <, >=, <=, and YYYY-MM-DD..YYYY-MM-DD ranges), merge:true|false, hash:, tree:, parent:, is:public. Examples: repo:owner/repo fix panic; org:github author:defunkt committer-date:>=2024-01-01; "refactor cache" repo:o/r; hash:abc1234 repo:o/r. (string, required)
- sort: Sort by author or committer date (defaults to best match) (string, optional)
search_repositories - Search repositories
- Required OAuth Scopes: repo
- minimal_output: Return minimal repository information (default: true). When false, returns full GitHub API repository objects. (boolean, optional)
- order: Sort order (string, optional)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- query: Repository search query. Examples: 'machine learning in:name stars:>1000 language:python', 'topic:react', 'user:facebook'. Supports advanced search syntax for precise filtering. (string, required)
- sort: Sort repositories by field, defaults to best match (string, optional)

Secret Protection

get_secret_scanning_alert - Get secret scanning alert
- Required OAuth Scopes: security_events
- Accepted OAuth Scopes: repo, security_events
- alertNumber: The number of the alert. (number, required)
- owner: The owner of the repository. (string, required)
- repo: The name of the repository. (string, required)
list_secret_scanning_alerts - List secret scanning alerts
- Required OAuth Scopes: security_events
- Accepted OAuth Scopes: repo, security_events
- owner: The owner of the repository. (string, required)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- repo: The name of the repository. (string, required)
- resolution: Filter by resolution (string, optional)
- secret_type: A comma-separated list of secret types to return. All default secret patterns are returned. To return generic patterns, pass the token name(s) in the parameter. (string, optional)
- state: Filter by state (string, optional)

Security Advisories

get_global_security_advisory - Get a global security advisory
- Required OAuth Scopes: security_events
- Accepted OAuth Scopes: repo, security_events
- ghsaId: GitHub Security Advisory ID (format: GHSA-xxxx-xxxx-xxxx). (string, required)
list_global_security_advisories - List global security advisories
- Required OAuth Scopes: security_events
- Accepted OAuth Scopes: repo, security_events
- affects: Filter advisories by affected package or version (e.g. "package1,package2@1.0.0"). (string, optional)
- cveId: Filter by CVE ID. (string, optional)
- cwes: Filter by Common Weakness Enumeration IDs (e.g. ["79", "284", "22"]). (string[], optional)
- ecosystem: Filter by package ecosystem. (string, optional)
- ghsaId: Filter by GitHub Security Advisory ID (format: GHSA-xxxx-xxxx-xxxx). (string, optional)
- isWithdrawn: Whether to only return withdrawn advisories. (boolean, optional)
- modified: Filter by publish or update date or date range (ISO 8601 date or range). (string, optional)
- published: Filter by publish date or date range (ISO 8601 date or range). (string, optional)
- severity: Filter by severity. (string, optional)
- type: Advisory type. (string, optional)
- updated: Filter by update date or date range (ISO 8601 date or range). (string, optional)
list_org_repository_security_advisories - List org repository security advisories
- Required OAuth Scopes: security_events
- Accepted OAuth Scopes: repo, security_events
- direction: Sort direction. (string, optional)
- org: The organization login. (string, required)
- sort: Sort field. (string, optional)
- state: Filter by advisory state. (string, optional)
list_repository_security_advisories - List repository security advisories
- Required OAuth Scopes: security_events
- Accepted OAuth Scopes: repo, security_events
- direction: Sort direction. (string, optional)
- owner: The owner of the repository. (string, required)
- repo: The name of the repository. (string, required)
- sort: Sort field. (string, optional)
- state: Filter by advisory state. (string, optional)

Stargazers

list_starred_repositories - List starred repositories
- Required OAuth Scopes: repo
- direction: The direction to sort the results by. (string, optional)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- sort: How to sort the results. Can be either 'created' (when the repository was starred) or 'updated' (when the repository was last pushed to). (string, optional)
- username: Username to list starred repositories for. Defaults to the authenticated user. (string, optional)
star_repository - Star repository
- Required OAuth Scopes: repo
- owner: Repository owner (string, required)
- repo: Repository name (string, required)
unstar_repository - Unstar repository
- Required OAuth Scopes: repo
- owner: Repository owner (string, required)
- repo: Repository name (string, required)

Users

search_users - Search users
- Required OAuth Scopes: repo
- order: Sort order (string, optional)
- page: Page number for pagination (min 1) (number, optional)
- perPage: Results per page for pagination (min 1, max 100) (number, optional)
- query: User search query. Examples: 'john smith', 'location:seattle', 'followers:>100'. Search is automatically scoped to type:user. (string, required)
- sort: Sort users by number of followers or repositories, or when the person joined GitHub. (string, optional)

Additional Tools in Remote GitHub MCP Server

Copilot

create_pull_request_with_copilot - Perform task with GitHub Copilot coding agent
- owner: Repository owner. You can guess the owner, but confirm it with the user before proceeding. (string, required)
- repo: Repository name. You can guess the repository name, but confirm it with the user before proceeding. (string, required)
- problem_statement: Detailed description of the task to be performed (e.g., 'Implement a feature that does X', 'Fix bug Y', etc.) (string, required)
- title: Title for the pull request that will be created (string, required)
- base_ref: Git reference (e.g., branch) that the agent will start its work from. If not specified, defaults to the repository's default branch (string, optional)

Copilot Spaces

Authentication note
- Fine-grained PATs are not hidden by classic PAT scope filtering, so these tools may still appear even when the token cannot use them.
- For org-owned spaces, fine-grained PATs must be installed on the owning organization and include organization_copilot_spaces: read.
- If an org-owned space contains repository-backed resources, the token must also have access to every referenced repository or the space may be treated as not found.
get_copilot_space - Get Copilot Space
- owner: The owner of the space. (string, required)
- name: The name of the space. (string, required)
list_copilot_spaces - List Copilot Spaces

GitHub Support Docs Search

github_support_docs_search - Retrieve documentation relevant to answer GitHub product and support questions. Support topics include: GitHub Actions Workflows, Authentication, GitHub Support Inquiries, Pull Request Practices, Repository Maintenance, GitHub Pages, GitHub Packages, GitHub Discussions, Copilot Spaces
- query: Input from the user about the question they need answered. This is the latest raw unedited user message. You should ALWAYS leave the user message as it is, you should never modify it. (string, required)

Read-Only Mode

To run the server in read-only mode, you can use the --read-only flag. This will only offer read-only tools, preventing any modifications to repositories, issues, pull requests, etc.

./github-mcp-server --read-only

When using Docker, you can pass the read-only mode as an environment variable:

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
  -e GITHUB_READ_ONLY=1 \
  ghcr.io/github/github-mcp-server

Lockdown Mode

Lockdown mode limits the content that the server will surface from public repositories. When enabled, the server checks whether the author of each item has push access to the repository. Private repositories are unaffected, and collaborators keep full access to their own content.

./github-mcp-server --lockdown-mode

When running with Docker, set the corresponding environment variable:

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
  -e GITHUB_LOCKDOWN_MODE=1 \
  ghcr.io/github/github-mcp-server

The behavior of lockdown mode depends on the tool invoked.

Following tools will return an error when the author lacks the push access:

issue_read:get
pull_request_read:get

Following tools will filter out content from users lacking the push access:

issue_read:get_comments
issue_read:get_sub_issues
pull_request_read:get_comments
pull_request_read:get_review_comments
pull_request_read:get_reviews

i18n / Overriding Descriptions

The descriptions of the tools can be overridden by creating a github-mcp-server-config.json file in the same directory as the binary.

The file should contain a JSON object with the tool names as keys and the new descriptions as values. For example:

{
  "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "an alternative description",
  "TOOL_CREATE_BRANCH_DESCRIPTION": "Create a new branch in a GitHub repository"
}

You can create an export of the current translations by running the binary with the --export-translations flag.

This flag will preserve any translations/overrides you have made, while adding any new translations that have been added to the binary since the last time you exported.

./github-mcp-server --export-translations
cat github-mcp-server-config.json

You can also use ENV vars to override the descriptions. The environment variable names are the same as the keys in the JSON file, prefixed with GITHUB_MCP_ and all uppercase.

For example, to override the TOOL_ADD_ISSUE_COMMENT_DESCRIPTION tool, you can set the following environment variable:

export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description"

Overriding Server Name and Title

The same override mechanism can be used to customize the MCP server's name and title fields in the initialization response. This is useful when running multiple GitHub MCP Server instances (e.g., one for github.com and one for GitHub Enterprise Server) so that agents can distinguish between them.

Key	Environment Variable	Default
`SERVER_NAME`	`GITHUB_MCP_SERVER_NAME`	`github-mcp-server`
`SERVER_TITLE`	`GITHUB_MCP_SERVER_TITLE`	`GitHub MCP Server`

For example, to configure a server instance for GitHub Enterprise Server:

{
  "SERVER_NAME": "ghes-mcp-server",
  "SERVER_TITLE": "GHES MCP Server"
}

Or using environment variables:

export GITHUB_MCP_SERVER_NAME="ghes-mcp-server"
export GITHUB_MCP_SERVER_TITLE="GHES MCP Server"

Library Usage

The exported Go API of this module should currently be considered unstable, and subject to breaking changes. In the future, we may offer stability; please file an issue if there is a use case where this would be valuable.

Contributing

Contributions are welcome. Before opening a pull request, please read the contributing guide for setup, testing, linting, and documentation generation instructions.

Support

For help using the GitHub MCP Server, see the support guide. If you have found a bug or want to request a feature, please search existing issues before opening a new one.

Security

Please do not report security vulnerabilities through public issues. Follow the instructions in the security policy to report vulnerabilities responsibly.

License

This project is licensed under the terms of the MIT open source license. Please refer to MIT for the full terms.

infiniflow/ragflow

RAGFlow is a leading open-source Retrieval-Augmented Generation (RAG) engine that fuses cutting-edge RAG with Agent capabilities to create a superior context layer for LLMs

Cloud | Documentation | Roadmap | Discord

📕 Table of Contents

💡 What is RAGFlow?
🎮 Get Started
🔥 Latest Updates
🌟 Key Features
🔎 System Architecture
🎬 Self-Hosting
🔧 Configurations
🔧 Build a Docker Image
🔨 Launch Service from Source for Development
📚 Documentation
📜 Roadmap
🏄 Community
🙌 Contributing

💡 What is RAGFlow?

RAGFlow is a leading open-source Retrieval-Augmented Generation (RAG) engine that fuses cutting-edge RAG with Agent capabilities to create a superior context layer for LLMs. It offers a streamlined RAG workflow adaptable to enterprises of any scale. Powered by a converged context engine and pre-built agent templates, RAGFlow enables developers to transform complex data into high-fidelity, production-ready AI systems with exceptional efficiency and precision.

🎮 Get Started

Try our cloud service at https://cloud.ragflow.io.

🔥 Latest Updates

2026-06-15 Support multiple chat channels such as Feishu, Discord, Telegram, Line, etc.
2026-04-24 Supports DeepSeek v4.
2026-03-24 RAGFlow Skill on OpenClaw — Provides an official skill for accessing RAGFlow datasets via OpenClaw.
2025-12-26 Supports 'Memory' for AI agent.
2025-11-19 Supports Gemini 3 Pro.
2025-11-12 Supports data synchronization from Confluence, S3, Notion, Discord, Google Drive.
2025-10-23 Supports MinerU & Docling as document parsing methods.
2025-10-15 Supports orchestrable ingestion pipeline.
2025-08-08 Supports OpenAI's latest GPT-5 series models.
2025-08-01 Supports agentic workflow and MCP.
2025-05-23 Adds a Python/JavaScript code executor component to Agent.
2025-03-19 Supports using a multi-modal model to make sense of images within PDF or DOCX files.

🎉 Stay Tuned

⭐️ Star our repository to stay up-to-date with exciting new features and improvements! Get instant notifications for new releases! 🌟

🌟 Key Features

🍭 "Quality in, quality out"

Deep document understanding-based knowledge extraction from unstructured data with complicated formats.
Finds "needle in a data haystack" of literally unlimited tokens.

🍱 Template-based chunking

Intelligent and explainable.
Plenty of template options to choose from.

🌱 Grounded citations with reduced hallucinations

Visualization of text chunking to allow human intervention.
Quick view of the key references and traceable citations to support grounded answers.

🍔 Compatibility with heterogeneous data sources

Supports Word, Slides, Excel, TXT, images, scanned copies, structured data, web pages, and more.

🛀 Automated and effortless RAG workflow

Streamlined RAG orchestration catered to both personal and large businesses.
Configurable LLMs as well as embedding models.
Multiple recall paired with fused re-ranking.
Intuitive APIs for seamless integration with business.

🔎 System Architecture

🎬 Self-Hosting

📝 Prerequisites

CPU >= 4 cores
RAM >= 16 GB
Disk >= 50 GB
Docker >= 24.0.0 & Docker Compose >= v2.26.1
Python >= 3.13
gVisor: Required only if you intend to use the code executor (sandbox) feature of RAGFlow.

Tip

If you have not installed Docker on your local machine (Windows, Mac, or Linux), see Install Docker Engine.

🚀 Start up the server

Ensure vm.max_map_count >= 262144:
To check the value of vm.max_map_count:
```
sysctl vm.max_map_count
```
Reset vm.max_map_count to a value at least 262144 if it is not.
```
# In this case, we set it to 262144:
sudo sysctl -w vm.max_map_count=262144
```
This change will be reset after a system reboot. To ensure your change remains permanent, add or update the vm.max_map_count value in /etc/sysctl.conf accordingly:
```
vm.max_map_count=262144
```

Clone the repo:

git clone https://github.com/infiniflow/ragflow.git

Start up the server using the pre-built Docker images:

Caution

All Docker images are built for x86 platforms. We don't currently offer Docker images for ARM64. If you are on an ARM64 platform, follow this guide to build a Docker image compatible with your system.

The command below downloads the v0.26.4 edition of the RAGFlow Docker image. See the following table for descriptions of different RAGFlow editions. To download a RAGFlow edition different from v0.26.4, update the RAGFLOW_IMAGE variable accordingly in docker/.env before using docker compose to start the server.

   cd ragflow/docker

   git checkout v0.26.4
   # Optional: use a stable tag (see releases: https://github.com/infiniflow/ragflow/releases)
   # This step ensures the **entrypoint.sh** file in the code matches the Docker image version.

   # Use CPU for DeepDoc tasks:
   docker compose -f docker-compose.yml up -d

   # To use GPU to accelerate DeepDoc tasks:
   # sed -i '1i DEVICE=gpu' .env
   # docker compose -f docker-compose.yml up -d

Note: Prior to v0.22.0, we provided both images with embedding models and slim images without embedding models. Details as follows:

RAGFlow image tag	Image size (GB)	Has embedding models?	Stable?
v0.21.1	≈9	✔️	Stable release
v0.21.1-slim	≈2	❌	Stable release

Starting with v0.22.0, we ship only the slim edition and no longer append the -slim suffix to the image tag.

Check the server status after having the server up and running:

docker logs -f docker-ragflow-cpu-1

The following output confirms a successful launch of the system:


      ____   ___    ______ ______ __
     / __ \ /   |  / ____// ____// /____  _      __
    / /_/ // /| | / / __ / /_   / // __ \| | /| / /
   / _, _// ___ |/ /_/ // __/  / // /_/ /| |/ |/ /
  /_/ |_|/_/  |_|\____//_/    /_/ \____/ |__/|__/

 * Running on all addresses (0.0.0.0)

If you skip this confirmation step and directly log in to RAGFlow, your browser may prompt a network abnormal error because, at that moment, your RAGFlow may not be fully initialized.

In your web browser, enter the IP address of your server and log in to RAGFlow.

With the default settings, you only need to enter http://IP_OF_YOUR_MACHINE (sans port number) as the default HTTP serving port 80 can be omitted when using the default configurations.
In service_conf.yaml.template, select the desired LLM factory in user_default_llm and update the API_KEY field with the corresponding API key.

See llm_api_key_setup for more information.

The show is on!

🔧 Configurations

When it comes to system configurations, you will need to manage the following files:

.env: Keeps the fundamental setups for the system, such as SVR_HTTP_PORT, MYSQL_PASSWORD, and MINIO_PASSWORD.
service_conf.yaml.template: Configures the back-end services. The environment variables in this file will be automatically populated when the Docker container starts. Any environment variables set within the Docker container will be available for use, allowing you to customize service behavior based on the deployment environment.
docker-compose.yml: The system relies on docker-compose.yml to start up.

The ./docker/README file provides a detailed description of the environment settings and service configurations which can be used as ${ENV_VARS} in the service_conf.yaml.template file.

To update the default HTTP serving port (80), go to docker-compose.yml and change 80:80 to <YOUR_SERVING_PORT>:80.

Updates to the above configurations require a reboot of all containers to take effect:

docker compose -f docker-compose.yml up -d

Switch doc engine from Elasticsearch to Infinity

RAGFlow uses Elasticsearch by default for storing full text and vectors. To switch to Infinity, follow these steps:

Stop all running containers:

docker compose -f docker/docker-compose.yml down -v

Warning

-v will delete the docker container volumes, and the existing data will be cleared.

Set DOC_ENGINE in docker/.env to infinity.

Start the containers:

docker compose -f docker/docker-compose.yml up -d

Warning

Switching to Infinity on a Linux/arm64 machine is not yet officially supported.

🔧 Build a Docker Image

This image is approximately 2 GB in size and relies on external LLM and embedding services.

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/
docker build --platform linux/amd64 -f Dockerfile -t infiniflow/ragflow:nightly .

Or if you are behind a proxy, you can pass proxy arguments:

docker build --platform linux/amd64 \
  --build-arg http_proxy=http://YOUR_PROXY:PORT \
  --build-arg https_proxy=http://YOUR_PROXY:PORT \
  -f Dockerfile -t infiniflow/ragflow:nightly .

🔨 Launch Service from Source for Development

Important

After cloning the repository for the first time, run git config --local --unset core.hooksPath, uv tool install lefthook and lefthook install once from the repo root to enable local Git hooks.

Install uv, or skip this step if it is already installed:
```
pipx install uv
```

Clone the source code and install Python dependencies:

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/
uv sync --python 3.13 # install RAGFlow dependent python modules
uv run python3 ragflow_deps/download_deps.py
git config --local --unset core.hooksPath
uv tool install lefthook
lefthook install

Launch the dependent services (MinIO, Elasticsearch, Redis, and MySQL) using Docker Compose:
```
docker compose -f docker/docker-compose-base.yml up -d
```
Add the following line to /etc/hosts to resolve all hosts specified in docker/.env to 127.0.0.1:
```
127.0.0.1       es01 infinity mysql minio redis sandbox-executor-manager
```
If you cannot access HuggingFace, set the HF_ENDPOINT environment variable to use a mirror site:
```
export HF_ENDPOINT=https://hf-mirror.com
```

If your operating system does not have jemalloc, please install it as follows:

# Ubuntu
sudo apt-get install libjemalloc-dev
# CentOS
sudo yum install jemalloc
# OpenSUSE
sudo zypper install jemalloc
# macOS
brew install jemalloc

Launch backend service:

source .venv/bin/activate
export PYTHONPATH=$(pwd)
bash docker/launch_backend_service.sh

Install frontend dependencies:
```
cd web
npm install
```
Launch frontend service:
```
npm run dev
```
The following output confirms a successful launch of the system:
Stop RAGFlow front-end and back-end service after development is complete:
```
pkill -f "ragflow_server.py|task_executor.py"
```

📚 Documentation

📜 Roadmap

See the RAGFlow Roadmap 2026

🏄 Community

🙌 Contributing

RAGFlow flourishes via open-source collaboration. In this spirit, we embrace diverse contributions from the community. If you would like to be a part, review our Contribution Guidelines first.

podman-container-tools/podman

Podman: A tool for managing OCI containers and pods.

Podman: A tool for managing OCI containers and pods

Podman (the POD MANager) is a tool for managing containers and images, volumes mounted into those containers, and pods made from groups of containers. Podman runs containers on Linux, but can also be used on Mac and Windows systems using a Podman-managed virtual machine. Podman is based on libpod, a library for container lifecycle management that is also contained in this repository. The libpod library provides APIs for managing containers, pods, container images, and volumes.

Podman releases a new major or minor release 4 times a year, during the second week of February, May, August, and November. Patch releases are more frequent and may occur at any time to get bugfixes out to users. All releases are PGP signed. Public keys of members of the team approved to make releases are located here.

Only the most recent release receives upstream support. Exceptions are sometimes made after a major Podman release, in recognition of the fact that not all users and distributions will be able to quickly migrate to a breaking change release. After the release of Podman 6.0, the Podman maintainers have decided to extend upstream support of the v5.8 series of releases until the 2nd week of June in 2027, one year after the release of Podman 6.0. This support will only include CVE fixes and critical bugfixes.

Continuous Integration:

Overview and scope

At a high level, the scope of Podman and libpod is the following:

Support for multiple container image formats, including OCI and Docker images.
Full management of those images, including pulling from various sources (including trust and verification), creating (built via Containerfile or Dockerfile or committed from a container), and pushing to registries and other storage backends.
Full management of container lifecycle, including creation (both from an image and from an exploded root filesystem), running, checkpointing and restoring (via CRIU), and removal.
Full management of container networking, using Netavark.
Support for pods, groups of containers that share resources and are managed together.
Support for running containers and pods without root or other elevated privileges.
Resource isolation of containers and pods.
Support for a Docker-compatible CLI interface, which can both run containers locally and on remote systems.
No manager daemon, for improved security and lower resource utilization at idle.
Support for a REST API providing both a Docker-compatible interface and an improved interface exposing advanced Podman functionality.
Support for running on Windows and Mac via virtual machines run by podman machine.

Roadmap

The future of Podman feature development can be found in its roadmap.

Communications

If you think you've identified a security issue in the project, please DO NOT report the issue publicly via the GitHub issue tracker, mailing list, or IRC. Instead, send an email with as many details as possible to security@lists.podman.io. This is a private mailing list for the core maintainers.

For general questions and discussion, please use Podman's channels.

For discussions around issues/bugs and features, you can use the GitHub issues and PRs tracking system.

There is also a mailing list at lists.podman.io. You can subscribe by sending a message to podman-join@lists.podman.io with the subject subscribe.

Community Meetings

All Podman meetings are open to everyone, free to attend, and hosted via Zoom through the CNCF/Linux Foundation. The full calendar is available on the Podman Container Tools LFX Meetings page. Registering for a meeting sends you an invite for that meeting and all subsequent recurring instances.

Meeting	Schedule	Format
Podman Community Meeting and its agenda	First Tuesday of even-numbered months (Feb, Apr, Jun, Aug, Oct, Dec) at 11:00 a.m. Eastern (UTC-4 summer / UTC-5 winter)	~1 hour — demos, announcements, and community updates
Podman Monday Office Hours and its agenda	Every Monday at 10:00 a.m. Eastern (UTC-4 summer / UTC-5 winter)	30 min — technical discussions, open topics
Podman Thursday Office Hours and its agenda	Every Thursday at 11:00 a.m. Eastern (UTC-4 summer / UTC-5 winter)	30 min — technical discussions, open topics

Rootless

Podman can be easily run as a normal user, without requiring a setuid binary. When run without root, Podman containers use user namespaces to set root in the container to the user running Podman. Rootless Podman runs locked-down containers with no privileges that the user running the container does not have. Some of these restrictions can be lifted (via --privileged, for example), but rootless containers will never have more privileges than the user that launched them. If you run Podman as your user and mount in /etc/passwd from the host, you still won't be able to change it, since your user doesn't have permission to do so.

Almost all normal Podman functionality is available, though there are some shortcomings. Any recent Podman release should be able to run rootless without any additional configuration, though your operating system may require some additional configuration detailed in the install guide.

A little configuration by an administrator is required before rootless Podman can be used, the necessary setup is documented here.

Podman Desktop

Podman Desktop provides a local development environment for Podman and Kubernetes on Linux, Windows, and Mac machines. It is a full-featured desktop UI frontend for Podman which uses the podman machine backend on non-Linux operating systems to run containers. It supports full container lifecycle management (building, pulling, and pushing images, creating and managing containers, creating and managing pods, and working with Kubernetes YAML). The project develops on GitHub and contributions are welcome.

Out of scope

Specialized signing and pushing of images to various storage backends. See Skopeo for those tasks.
Support for the Kubernetes CRI interface for container management. The CRI-O daemon specializes in that.

OCI Projects Plans

Podman uses OCI projects and best of breed libraries for different aspects:

Runtime: We use the OCI runtime tools to generate OCI runtime configurations that can be used with any OCI-compliant runtime, like crun and runc.
Images: Image management uses the containers/image library.
Storage: Container and image storage is managed by containers/storage.
Networking: Networking support through use of Netavark and Aardvark. Rootless networking is handled via pasta.
Builds: Builds are supported via Buildah.
Conmon: Conmon is a tool for monitoring OCI runtimes, used by both Podman and CRI-O.
Seccomp: A unified Seccomp policy for Podman, Buildah, and CRI-O.

Podman Information for Developers

For blogs, release announcements and more, please checkout the podman.io website!

Installation notes Information on how to install Podman in your environment.

OCI Hooks Support Information on how Podman configures OCI Hooks to run when launching a container.

Podman API Documentation on the Podman REST API.

Podman Commands A list of the Podman commands with links to their man pages and in many cases videos showing the commands in use.

Podman Container Images Information on the Podman Container Images found on quay.io.

Podman Troubleshooting Guide A list of common issues and solutions for Podman.

Podman Usage Transfer Useful information for ops and dev transfer as it relates to infrastructure that utilizes Podman. This page includes tables showing Docker commands and their Podman equivalent commands.

Tutorials Tutorials on using Podman.

Remote Client A brief how-to on using the Podman remote client.

Basic Setup and Use of Podman in a Rootless environment A tutorial showing the setup and configuration necessary to run Rootless Podman.

Release Notes Release notes for recent Podman versions.

Contributing Information about contributing to this project.

Buildah and Podman relationship

Buildah and Podman are two complementary open-source projects that are available on most Linux platforms and both projects reside at GitHub.com with Buildah here and Podman here. Both, Buildah and Podman are command line tools that work on Open Container Initiative (OCI) images and containers. The two projects differentiate in their specialization.

Buildah specializes in building OCI images. Buildah's commands replicate all of the commands that are found in a Dockerfile. This allows building images with and without Dockerfiles while not requiring any root privileges. Buildah’s ultimate goal is to provide a lower-level coreutils interface to build images. The flexibility of building images without Dockerfiles allows for the integration of other scripting languages into the build process. Buildah follows a simple fork-exec model and does not run as a daemon but it is based on a comprehensive API in golang, which can be vendored into other tools.

Podman specializes in all of the commands and functions that help you to maintain and modify OCI images, such as pulling and tagging. It also allows you to create, run, and maintain those containers created from those images. For building container images via Dockerfiles, Podman uses Buildah's golang API and can be installed independently from Buildah.

A major difference between Podman and Buildah is their concept of a container. Podman allows users to create "traditional containers" where the intent of these containers is to be long lived. While Buildah containers are really just created to allow content to be added back to the container image. An easy way to think of it is the buildah run command emulates the RUN command in a Dockerfile while the podman run command emulates the docker run command in functionality. Because of this and their underlying storage differences, you can not see Podman containers from within Buildah or vice versa.

In short, Buildah is an efficient way to create OCI images while Podman allows you to manage and maintain those images and containers in a production environment using familiar container cli commands. For more details, see the Container Tools Guide.

Podman Hello

$ podman run quay.io/podman/hello
Trying to pull quay.io/podman/hello:latest...
Getting image source signatures
Copying blob a6b3126f3807 done
Copying config 25c667d086 done
Writing manifest to image destination
Storing signatures
!... Hello Podman World ...!

         .--"--.
       / -     - \
      / (O)   (O) \
   ~~~| -=(,Y,)=- |
    .---. /`  \   |~~
 ~/  o  o \~~~~.----. ~~
  | =(X)= |~  / (O (O) \
   ~~~~~~~  ~| =(Y_)=-  |
  ~~~~    ~~~|   U      |~~

Project:   https://github.com/containers/podman
Website:   https://podman.io
Documents: https://docs.podman.io
Twitter:   @Podman_io

fatedier/frp

A fast reverse proxy to help you expose a local server behind a NAT or firewall to the internet.

frp

README | 中文文档

Recall.ai - API for meeting recordings

If you're looking for a meeting recording API, consider checking out Recall.ai,

an API that records Zoom, Google Meet, Microsoft Teams, in-person meetings, and more.

The complete IDE crafted for professional Go developers

What is frp?

frp is a fast reverse proxy that allows you to expose a local server located behind a NAT or firewall to the Internet. It currently supports TCP and UDP, as well as HTTP and HTTPS protocols, enabling requests to be forwarded to internal services via domain name.

frp also offers a P2P connect mode.

Development Status

frp is currently under development. You can try the latest release version in the master branch, or use the dev branch to access the version currently in development.

We are currently working on version 2 and attempting to perform some code refactoring and improvements. However, please note that it will not be compatible with version 1.

We will transition from version 0 to version 1 at the appropriate time and will only accept bug fixes and improvements, rather than big feature requests.

About V2

The complexity and difficulty of the v2 version are much higher than anticipated. I can only work on its development during fragmented time periods, and the constant interruptions disrupt productivity significantly. Given this situation, we will continue to optimize and iterate on the current version until we have more free time to proceed with the major version overhaul.

The concept behind v2 is based on my years of experience and reflection in the cloud-native domain, particularly in K8s and ServiceMesh. Its core is a modernized four-layer and seven-layer proxy, similar to envoy. This proxy itself is highly scalable, not only capable of implementing the functionality of intranet penetration but also applicable to various other domains. Building upon this highly scalable core, we aim to implement all the capabilities of frp v1 while also addressing the functionalities that were previously unachievable or difficult to implement in an elegant manner. Furthermore, we will maintain efficient development and iteration capabilities.

In addition, I envision frp itself becoming a highly extensible system and platform, similar to how we can provide a range of extension capabilities based on K8s. In K8s, we can customize development according to enterprise needs, utilizing features such as CRD, controller mode, webhook, CSI, and CNI. In frp v1, we introduced the concept of server plugins, which implemented some basic extensibility. However, it relies on a simple HTTP protocol and requires users to start independent processes and manage them on their own. This approach is far from flexible and convenient, and real-world demands vary greatly. It is unrealistic to expect a non-profit open-source project maintained by a few individuals to meet everyone's needs.

Finally, we acknowledge that the current design of modules such as configuration management, permission verification, certificate management, and API management is not modern enough. While we may carry out some optimizations in the v1 version, ensuring compatibility remains a challenging issue that requires a considerable amount of effort to address.

We sincerely appreciate your support for frp.

Architecture

Example Usage

To begin, download the latest program for your operating system and architecture from the Release page.

Next, place the frps binary and server configuration file on Server A, which has a public IP address.

Finally, place the frpc binary and client configuration file on Server B, which is located on a LAN that cannot be directly accessed from the public internet.

Some antiviruses improperly mark frpc as malware and delete it. This is due to frp being a networking tool capable of creating reverse proxies. Antiviruses sometimes flag reverse proxies due to their ability to bypass firewall port restrictions. If you are using antivirus, then you may need to whitelist/exclude frpc in your antivirus settings to avoid accidental quarantine/deletion. See issue 3637 for more details.

Access your computer in a LAN network via SSH

Modify frps.toml on server A by setting the bindPort for frp clients to connect to:

# frps.toml
bindPort = 7000

Start frps on server A:

./frps -c ./frps.toml

Modify frpc.toml on server B and set the serverAddr field to the public IP address of your frps server:

# frpc.toml
serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = 6000

Note that the localPort (listened on the client) and remotePort (exposed on the server) are used for traffic going in and out of the frp system, while the serverPort is used for communication between frps and frpc.

Start frpc on server B:

./frpc -c ./frpc.toml

To access server B from another machine through server A via SSH (assuming the username is test), use the following command:

ssh -oPort=6000 test@x.x.x.x

Multiple SSH services sharing the same port

This example implements multiple SSH services exposed through the same port using a proxy of type tcpmux. Similarly, as long as the client supports the HTTP Connect proxy connection method, port reuse can be achieved in this way.

Deploy frps on a machine with a public IP and modify the frps.toml file. Here is a simplified configuration:

bindPort = 7000
tcpmuxHTTPConnectPort = 5002

Deploy frpc on the internal machine A with the following configuration:

serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "ssh1"
type = "tcpmux"
multiplexer = "httpconnect"
customDomains = ["machine-a.example.com"]
localIP = "127.0.0.1"
localPort = 22

Deploy another frpc on the internal machine B with the following configuration:

serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "ssh2"
type = "tcpmux"
multiplexer = "httpconnect"
customDomains = ["machine-b.example.com"]
localIP = "127.0.0.1"
localPort = 22

To access internal machine A using SSH ProxyCommand, assuming the username is "test":

ssh -o 'proxycommand socat - PROXY:x.x.x.x:%h:%p,proxyport=5002' test@machine-a.example.com

To access internal machine B, the only difference is the domain name, assuming the username is "test":

ssh -o 'proxycommand socat - PROXY:x.x.x.x:%h:%p,proxyport=5002' test@machine-b.example.com

Accessing Internal Web Services with Custom Domains in LAN

Sometimes we need to expose a local web service behind a NAT network to others for testing purposes with our own domain name.

Unfortunately, we cannot resolve a domain name to a local IP. However, we can use frp to expose an HTTP(S) service.

Modify frps.toml and set the HTTP port for vhost to 8080:

# frps.toml
bindPort = 7000
vhostHTTPPort = 8080

If you want to configure an https proxy, you need to set up the vhostHTTPSPort.

Start frps:

./frps -c ./frps.toml

Modify frpc.toml and set serverAddr to the IP address of the remote frps server. Specify the localPort of your web service:

# frpc.toml
serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "web"
type = "http"
localPort = 80
customDomains = ["www.example.com"]

Start frpc:

./frpc -c ./frpc.toml

Map the A record of www.example.com to either the public IP of the remote frps server or a CNAME record pointing to your original domain.
Visit your local web service using url http://www.example.com:8080.

Forward DNS query requests

Modify frps.toml:

# frps.toml
bindPort = 7000

Start frps:

./frps -c ./frps.toml

Modify frpc.toml and set serverAddr to the IP address of the remote frps server. Forward DNS query requests to the Google Public DNS server 8.8.8.8:53:

# frpc.toml
serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "dns"
type = "udp"
localIP = "8.8.8.8"
localPort = 53
remotePort = 6000

Start frpc:

./frpc -c ./frpc.toml

Test DNS resolution using the dig command:

dig @x.x.x.x -p 6000 www.google.com

Forward Unix Domain Socket

Expose a Unix domain socket (e.g. the Docker daemon socket) as TCP.

Configure frps as above.

Start frpc with the following configuration:

# frpc.toml
serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "unix_domain_socket"
type = "tcp"
remotePort = 6000
[proxies.plugin]
type = "unix_domain_socket"
unixPath = "/var/run/docker.sock"

Test the configuration by getting the docker version using curl:

curl http://x.x.x.x:6000/version

Expose a simple HTTP file server

Expose a simple HTTP file server to access files stored in the LAN from the public Internet.

Configure frps as described above, then:

Start frpc with the following configuration:

# frpc.toml
serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "test_static_file"
type = "tcp"
remotePort = 6000
[proxies.plugin]
type = "static_file"
localPath = "/tmp/files"
stripPrefix = "static"
httpUser = "abc"
httpPassword = "abc"

Visit http://x.x.x.x:6000/static/ from your browser and specify correct username and password to view files in /tmp/files on the frpc machine.

Enable HTTPS for a local HTTP(S) service

You may substitute https2https for the plugin, and point the localAddr to a HTTPS endpoint.

Start frpc with the following configuration:

# frpc.toml
serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "test_https2http"
type = "https"
customDomains = ["test.example.com"]

[proxies.plugin]
type = "https2http"
localAddr = "127.0.0.1:80"
crtPath = "./server.crt"
keyPath = "./server.key"
hostHeaderRewrite = "127.0.0.1"
requestHeaders.set.x-from-where = "frp"

Visit https://test.example.com.

Expose your service privately

To mitigate risks associated with exposing certain services directly to the public network, STCP (Secret TCP) mode requires a preshared key to be used for access to the service from other clients.

Configure frps same as above.

Start frpc on machine B with the following config. This example is for exposing the SSH service (port 22), and note the secretKey field for the preshared key, and that the remotePort field is removed here:

# frpc.toml
serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "secret_ssh"
type = "stcp"
secretKey = "abcdefg"
localIP = "127.0.0.1"
localPort = 22

Start another frpc (typically on another machine C) with the following config to access the SSH service with a security key (secretKey field):

# frpc.toml
serverAddr = "x.x.x.x"
serverPort = 7000

[[visitors]]
name = "secret_ssh_visitor"
type = "stcp"
serverName = "secret_ssh"
secretKey = "abcdefg"
bindAddr = "127.0.0.1"
bindPort = 6000

On machine C, connect to SSH on machine B, using this command:

ssh -oPort=6000 127.0.0.1

P2P Mode

xtcp is designed to transmit large amounts of data directly between clients. A frps server is still needed, as P2P here only refers to the actual data transmission.

Note that it may not work with all types of NAT devices. You might want to fallback to stcp if xtcp doesn't work.

Start frpc on machine B, and expose the SSH port. Note that the remotePort field is removed:

# frpc.toml
serverAddr = "x.x.x.x"
serverPort = 7000
# set up a new stun server if the default one is not available.
# natHoleStunServer = "xxx"

[[proxies]]
name = "p2p_ssh"
type = "xtcp"
secretKey = "abcdefg"
localIP = "127.0.0.1"
localPort = 22

Start another frpc (typically on another machine C) with the configuration to connect to SSH using P2P mode:

# frpc.toml
serverAddr = "x.x.x.x"
serverPort = 7000
# set up a new stun server if the default one is not available.
# natHoleStunServer = "xxx"

[[visitors]]
name = "p2p_ssh_visitor"
type = "xtcp"
serverName = "p2p_ssh"
secretKey = "abcdefg"
bindAddr = "127.0.0.1"
bindPort = 6000
# when automatic tunnel persistence is required, set it to true
keepTunnelOpen = false

On machine C, connect to SSH on machine B, using this command:

ssh -oPort=6000 127.0.0.1

Features

Configuration Files

Since v0.52.0, we support TOML, YAML, and JSON for configuration. Please note that INI is deprecated and will be removed in future releases. New features will only be available in TOML, YAML, or JSON. Users wanting these new features should switch their configuration format accordingly.

Read the full example configuration files to find out even more features not described here.

Examples use TOML format, but you can still use YAML or JSON.

These configuration files is for reference only. Please do not use this configuration directly to run the program as it may have various issues.

Full configuration file for frps (Server)

Full configuration file for frpc (Client)

Using Environment Variables

Environment variables can be referenced in the configuration file, using Go's standard format:

# frpc.toml
serverAddr = "{{ .Envs.FRP_SERVER_ADDR }}"
serverPort = 7000

[[proxies]]
name = "ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = {{ .Envs.FRP_SSH_REMOTE_PORT }}

With the config above, variables can be passed into frpc program like this:

export FRP_SERVER_ADDR=x.x.x.x
export FRP_SSH_REMOTE_PORT=6000
./frpc -c ./frpc.toml

frpc will render configuration file template using OS environment variables. Remember to prefix your reference with .Envs.

Split Configures Into Different Files

You can split multiple proxy configs into different files and include them in the main file.

# frpc.toml
serverAddr = "x.x.x.x"
serverPort = 7000
includes = ["./confd/*.toml"]

# ./confd/test.toml

[[proxies]]
name = "ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = 6000

Server Dashboard

Check frp's status and proxies' statistics information by Dashboard.

Configure a port for dashboard to enable this feature:

# The default value is 127.0.0.1. Change it to 0.0.0.0 when you want to access it from a public network.
webServer.addr = "0.0.0.0"
webServer.port = 7500
# dashboard's username and password are both optional
webServer.user = "admin"
webServer.password = "admin"

Then visit http://[serverAddr]:7500 to see the dashboard, with username and password both being admin.

Additionally, you can use HTTPS port by using your domains wildcard or normal SSL certificate:

webServer.port = 7500
# dashboard's username and password are both optional
webServer.user = "admin"
webServer.password = "admin"
webServer.tls.certFile = "server.crt"
webServer.tls.keyFile = "server.key"

Then visit https://[serverAddr]:7500 to see the dashboard in secure HTTPS connection, with username and password both being admin.

Client Admin UI

The Client Admin UI helps you check and manage frpc's configuration and proxies.

Configure an address for admin UI to enable this feature:

webServer.addr = "127.0.0.1"
webServer.port = 7400
webServer.user = "admin"
webServer.password = "admin"

Then visit http://127.0.0.1:7400 to see admin UI, with username and password both being admin.

Dynamic Proxy Management (Store)

You can dynamically create, update, and delete proxies and visitors at runtime through the Web UI or API, without restarting frpc.

To enable this feature, configure store.path to specify a file for persisting the configurations:

[store]
path = "./db.json"

Proxies and visitors managed through the Store are saved to disk and automatically restored on frpc restart. They work alongside proxies defined in the configuration file — Store entries take precedence when names conflict.

Monitor

When web server is enabled, frps will save monitor data in cache for 7 days. It will be cleared after process restart.

Prometheus is also supported.

Prometheus

Enable dashboard first, then configure enablePrometheus = true in frps.toml.

http://{dashboard_addr}/metrics will provide prometheus monitor data.

Authenticating the Client

There are 2 authentication methods to authenticate frpc with frps.

You can decide which one to use by configuring auth.method in frpc.toml and frps.toml, the default one is token.

Configuring auth.additionalScopes = ["HeartBeats"] will use the configured authentication method to add and validate authentication on every heartbeat between frpc and frps.

Configuring auth.additionalScopes = ["NewWorkConns"] will do the same for every new work connection between frpc and frps.

Token Authentication

When specifying auth.method = "token" in frpc.toml and frps.toml - token based authentication will be used.

Make sure to specify the same auth.token in frps.toml and frpc.toml for frpc to pass frps validation

Token Source

frp supports reading authentication tokens from external sources using the tokenSource configuration. Currently, file-based token source is supported.

File-based token source:

# frpc.toml
auth.method = "token"
auth.tokenSource.type = "file"
auth.tokenSource.file.path = "/path/to/token/file"

The token will be read from the specified file at startup. This is useful for scenarios where tokens are managed by external systems or need to be kept separate from configuration files for security reasons.

OIDC Authentication

When specifying auth.method = "oidc" in frpc.toml and frps.toml - OIDC based authentication will be used.

OIDC stands for OpenID Connect, and the flow used is called Client Credentials Grant.

To use this authentication type - configure frpc.toml and frps.toml as follows:

# frps.toml
auth.method = "oidc"
auth.oidc.issuer = "https://example-oidc-issuer.com/"
auth.oidc.audience = "https://oidc-audience.com/.default"

# frpc.toml
auth.method = "oidc"
auth.oidc.clientID = "98692467-37de-409a-9fac-bb2585826f18" # Replace with OIDC client ID
auth.oidc.clientSecret = "oidc_secret"
auth.oidc.audience = "https://oidc-audience.com/.default"
auth.oidc.tokenEndpointURL = "https://example-oidc-endpoint.com/oauth2/v2.0/token"

Encryption and Compression

The features are off by default. You can turn on encryption and/or compression:

# frpc.toml

[[proxies]]
name = "ssh"
type = "tcp"
localPort = 22
remotePort = 6000
transport.useEncryption = true
transport.useCompression = true

TLS

Since v0.50.0, the default value of transport.tls.enable and transport.tls.disableCustomTLSFirstByte has been changed to true, and tls is enabled by default.

For port multiplexing, frp sends a first byte 0x17 to dial a TLS connection. This only takes effect when you set transport.tls.disableCustomTLSFirstByte to false.

To enforce frps to only accept TLS connections - configure transport.tls.force = true in frps.toml. This is optional.

frpc TLS settings:

transport.tls.enable = true
transport.tls.certFile = "certificate.crt"
transport.tls.keyFile = "certificate.key"
transport.tls.trustedCaFile = "ca.crt"

frps TLS settings:

transport.tls.force = true
transport.tls.certFile = "certificate.crt"
transport.tls.keyFile = "certificate.key"
transport.tls.trustedCaFile = "ca.crt"

You will need a root CA cert and at least one SSL/TLS certificate. It can be self-signed or regular (such as Let's Encrypt or another SSL/TLS certificate provider).

If you using frp via IP address and not hostname, make sure to set the appropriate IP address in the Subject Alternative Name (SAN) area when generating SSL/TLS Certificates.

Given an example:

Prepare openssl config file. It exists at /etc/pki/tls/openssl.cnf in Linux System and /System/Library/OpenSSL/openssl.cnf in MacOS, and you can copy it to current path, like cp /etc/pki/tls/openssl.cnf ./my-openssl.cnf. If not, you can build it by yourself, like:

cat > my-openssl.cnf << EOF
[ ca ]
default_ca = CA_default
[ CA_default ]
x509_extensions = usr_cert
[ req ]
default_bits        = 2048
default_md          = sha256
default_keyfile     = privkey.pem
distinguished_name  = req_distinguished_name
attributes          = req_attributes
x509_extensions     = v3_ca
string_mask         = utf8only
[ req_distinguished_name ]
[ req_attributes ]
[ usr_cert ]
basicConstraints       = CA:FALSE
nsComment              = "OpenSSL Generated Certificate"
subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid,issuer
[ v3_ca ]
subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints       = CA:true
EOF

build ca certificates:

openssl genrsa -out ca.key 2048
openssl req -x509 -new -nodes -key ca.key -subj "/CN=example.ca.com" -days 5000 -out ca.crt

build frps certificates:

openssl genrsa -out server.key 2048

openssl req -new -sha256 -key server.key \
    -subj "/C=XX/ST=DEFAULT/L=DEFAULT/O=DEFAULT/CN=server.com" \
    -reqexts SAN \
    -config <(cat my-openssl.cnf <(printf "\n[SAN]\nsubjectAltName=DNS:localhost,IP:127.0.0.1,DNS:example.server.com")) \
    -out server.csr

openssl x509 -req -days 365 -sha256 \
	-in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
	-extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1,DNS:example.server.com") \
	-out server.crt

build frpc certificates：

openssl genrsa -out client.key 2048
openssl req -new -sha256 -key client.key \
    -subj "/C=XX/ST=DEFAULT/L=DEFAULT/O=DEFAULT/CN=client.com" \
    -reqexts SAN \
    -config <(cat my-openssl.cnf <(printf "\n[SAN]\nsubjectAltName=DNS:client.com,DNS:example.client.com")) \
    -out client.csr

openssl x509 -req -days 365 -sha256 \
    -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
	-extfile <(printf "subjectAltName=DNS:client.com,DNS:example.client.com") \
	-out client.crt

Hot-Reloading frpc configuration

The webServer fields are required for enabling HTTP API:

# frpc.toml
webServer.addr = "127.0.0.1"
webServer.port = 7400

Then run command frpc reload -c ./frpc.toml and wait for about 10 seconds to let frpc create or update or remove proxies.

Note that global client parameters won't be modified except 'start'.

start is a global allowlist evaluated after all sources are merged (config file/include/store). If start is non-empty, any proxy or visitor not listed there will not be started, including entries created via Store API.

start is kept mainly for compatibility and is generally not recommended for new configurations. Prefer per-proxy/per-visitor enabled, and keep start empty unless you explicitly want this global allowlist behavior.

You can run command frpc verify -c ./frpc.toml before reloading to check if there are config errors.

Get proxy status from client

Use frpc status -c ./frpc.toml to get status of all proxies. The webServer fields are required for enabling HTTP API.

Only allowing certain ports on the server

allowPorts in frps.toml is used to avoid abuse of ports:

# frps.toml
allowPorts = [
  { start = 2000, end = 3000 },
  { single = 3001 },
  { single = 3003 },
  { start = 4000, end = 50000 }
]

Port Reuse

vhostHTTPPort and vhostHTTPSPort in frps can use same port with bindPort. frps will detect the connection's protocol and handle it correspondingly.

What you need to pay attention to is that if you want to configure vhostHTTPSPort and bindPort to the same port, you need to first set transport.tls.disableCustomTLSFirstByte to false.

We would like to try to allow multiple proxies bind a same remote port with different protocols in the future.

Bandwidth Limit

For Each Proxy

# frpc.toml

[[proxies]]
name = "ssh"
type = "tcp"
localPort = 22
remotePort = 6000
transport.bandwidthLimit = "1MB"

Set transport.bandwidthLimit in each proxy's configure to enable this feature. Supported units are MB and KB.

Set transport.bandwidthLimitMode to client or server to limit bandwidth on the client or server side. Default is client.

TCP Stream Multiplexing

frp supports tcp stream multiplexing since v0.10.0 like HTTP2 Multiplexing, in which case all logic connections to the same frpc are multiplexed into the same TCP connection.

You can disable this feature by modify frps.toml and frpc.toml:

# frps.toml and frpc.toml, must be same
transport.tcpMux = false

Support KCP Protocol

KCP is a fast and reliable protocol that can achieve the transmission effect of a reduction of the average latency by 30% to 40% and reduction of the maximum delay by a factor of three, at the cost of 10% to 20% more bandwidth wasted than TCP.

KCP mode uses UDP as the underlying transport. Using KCP in frp:

Enable KCP in frps:

# frps.toml
bindPort = 7000
# Specify a UDP port for KCP.
kcpBindPort = 7000

The kcpBindPort number can be the same number as bindPort, since bindPort field specifies a TCP port.

Configure frpc.toml to use KCP to connect to frps:

# frpc.toml
serverAddr = "x.x.x.x"
# Same as the 'kcpBindPort' in frps.toml
serverPort = 7000
transport.protocol = "kcp"

Support QUIC Protocol

QUIC is a new multiplexed transport built on top of UDP.

Using QUIC in frp:

Enable QUIC in frps:

# frps.toml
bindPort = 7000
# Specify a UDP port for QUIC.
quicBindPort = 7000

The quicBindPort number can be the same number as bindPort, since bindPort field specifies a TCP port.

Configure frpc.toml to use QUIC to connect to frps:

# frpc.toml
serverAddr = "x.x.x.x"
# Same as the 'quicBindPort' in frps.toml
serverPort = 7000
transport.protocol = "quic"

Connection Pooling

By default, frps creates a new frpc connection to the backend service upon a user request. With connection pooling, frps keeps a certain number of pre-established connections, reducing the time needed to establish a connection.

This feature is suitable for a large number of short connections.

Configure the limit of pool count each proxy can use in frps.toml:

# frps.toml
transport.maxPoolCount = 5

Enable and specify the number of connection pool:

# frpc.toml
transport.poolCount = 1

Load balancing

Load balancing is supported by group.

This feature is only available for types tcp, http, tcpmux now.

# frpc.toml

[[proxies]]
name = "test1"
type = "tcp"
localPort = 8080
remotePort = 80
loadBalancer.group = "web"
loadBalancer.groupKey = "123"

[[proxies]]
name = "test2"
type = "tcp"
localPort = 8081
remotePort = 80
loadBalancer.group = "web"
loadBalancer.groupKey = "123"

loadBalancer.groupKey is used for authentication.

Connections to port 80 will be dispatched to proxies in the same group randomly.

For type tcp, remotePort in the same group should be the same.

For type http, customDomains, subdomain, locations should be the same.

Service Health Check

Health check feature can help you achieve high availability with load balancing.

Add healthCheck.type = "tcp" or healthCheck.type = "http" to enable health check.

With health check type tcp, the service port will be pinged (TCPing):

# frpc.toml

[[proxies]]
name = "test1"
type = "tcp"
localPort = 22
remotePort = 6000
# Enable TCP health check
healthCheck.type = "tcp"
# TCPing timeout seconds
healthCheck.timeoutSeconds = 3
# If health check failed 3 times in a row, the proxy will be removed from frps
healthCheck.maxFailed = 3
# A health check every 10 seconds
healthCheck.intervalSeconds = 10

With health check type http, an HTTP request will be sent to the service and an HTTP 2xx OK response is expected:

# frpc.toml

[[proxies]]
name = "web"
type = "http"
localIP = "127.0.0.1"
localPort = 80
customDomains = ["test.example.com"]
# Enable HTTP health check
healthCheck.type = "http"
# frpc will send a GET request to '/status'
# and expect an HTTP 2xx OK response
healthCheck.path = "/status"
healthCheck.timeoutSeconds = 3
healthCheck.maxFailed = 3
healthCheck.intervalSeconds = 10

Rewriting the HTTP Host Header

By default frp does not modify the tunneled HTTP requests at all as it's a byte-for-byte copy.

However, speaking of web servers and HTTP requests, your web server might rely on the Host HTTP header to determine the website to be accessed. frp can rewrite the Host header when forwarding the HTTP requests, with the hostHeaderRewrite field:

# frpc.toml

[[proxies]]
name = "web"
type = "http"
localPort = 80
customDomains = ["test.example.com"]
hostHeaderRewrite = "dev.example.com"

The HTTP request will have the Host header rewritten to Host: dev.example.com when it reaches the actual web server, although the request from the browser probably has Host: test.example.com.

Setting other HTTP Headers

Similar to Host, You can override other HTTP request and response headers with proxy type http.

# frpc.toml

[[proxies]]
name = "web"
type = "http"
localPort = 80
customDomains = ["test.example.com"]
hostHeaderRewrite = "dev.example.com"
requestHeaders.set.x-from-where = "frp"
responseHeaders.set.foo = "bar"

In this example, it will set header x-from-where: frp in the HTTP request and foo: bar in the HTTP response.

Get Real IP

HTTP X-Forwarded-For

This feature is for http proxies or proxies with the https2http and https2https plugins enabled.

You can get user's real IP from HTTP request headers X-Forwarded-For.

Proxy Protocol

frp supports Proxy Protocol to send user's real IP to local services.

Here is an example for https service:

# frpc.toml

[[proxies]]
name = "web"
type = "https"
localPort = 443
customDomains = ["test.example.com"]

# now v1 and v2 are supported
transport.proxyProtocolVersion = "v2"

You can enable Proxy Protocol support in nginx to expose user's real IP in HTTP header X-Real-IP, and then read X-Real-IP header in your web service for the real IP.

Require HTTP Basic Auth (Password) for Web Services

Anyone who can guess your tunnel URL can access your local web server unless you protect it with a password.

This enforces HTTP Basic Auth on all requests with the username and password specified in frpc's configure file.

It can only be enabled when proxy type is http.

# frpc.toml

[[proxies]]
name = "web"
type = "http"
localPort = 80
customDomains = ["test.example.com"]
httpUser = "abc"
httpPassword = "abc"

Visit http://test.example.com in the browser and now you are prompted to enter the username and password.

Custom Subdomain Names

It is convenient to use subdomain configure for http and https types when many people share one frps server.

# frps.toml
subDomainHost = "frps.com"

Resolve *.frps.com to the frps server's IP. This is usually called a Wildcard DNS record.

# frpc.toml

[[proxies]]
name = "web"
type = "http"
localPort = 80
subdomain = "test"

Now you can visit your web service on test.frps.com.

Note that if subdomainHost is not empty, customDomains should not be the subdomain of subdomainHost.

URL Routing

frp supports forwarding HTTP requests to different backend web services by url routing.

locations specifies the prefix of URL used for routing. frps first searches for the most specific prefix location given by literal strings regardless of the listed order.

# frpc.toml

[[proxies]]
name = "web01"
type = "http"
localPort = 80
customDomains = ["web.example.com"]
locations = ["/"]

[[proxies]]
name = "web02"
type = "http"
localPort = 81
customDomains = ["web.example.com"]
locations = ["/news", "/about"]

HTTP requests with URL prefix /news or /about will be forwarded to web02 and other requests to web01.

TCP Port Multiplexing

frp supports receiving TCP sockets directed to different proxies on a single port on frps, similar to vhostHTTPPort and vhostHTTPSPort.

The only supported TCP port multiplexing method available at the moment is httpconnect - HTTP CONNECT tunnel.

When setting tcpmuxHTTPConnectPort to anything other than 0 in frps, frps will listen on this port for HTTP CONNECT requests.

The host of the HTTP CONNECT request will be used to match the proxy in frps. Proxy hosts can be configured in frpc by configuring customDomains and / or subdomain under tcpmux proxies, when multiplexer = "httpconnect".

For example:

# frps.toml
bindPort = 7000
tcpmuxHTTPConnectPort = 1337

# frpc.toml
serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "proxy1"
type = "tcpmux"
multiplexer = "httpconnect"
customDomains = ["test1"]
localPort = 80

[[proxies]]
name = "proxy2"
type = "tcpmux"
multiplexer = "httpconnect"
customDomains = ["test2"]
localPort = 8080

In the above configuration - frps can be contacted on port 1337 with a HTTP CONNECT header such as:

CONNECT test1 HTTP/1.1\r\n\r\n

and the connection will be routed to proxy1.

Connecting to frps via PROXY

frpc can connect to frps through proxy if you set OS environment variable HTTP_PROXY, or if transport.proxyURL is set in frpc.toml file.

It only works when protocol is tcp.

# frpc.toml
serverAddr = "x.x.x.x"
serverPort = 7000
transport.proxyURL = "http://user:pwd@192.168.1.128:8080"

Port range mapping

Added in v0.56.0

We can use the range syntax of Go template combined with the built-in parseNumberRangePair function to achieve port range mapping.

The following example, when run, will create 8 proxies named test-6000, test-6001 ... test-6007, each mapping the remote port to the local port.

{{- range $_, $v := parseNumberRangePair "6000-6006,6007" "6000-6006,6007" }}
[[proxies]]
name = "tcp-{{ $v.First }}"
type = "tcp"
localPort = {{ $v.First }}
remotePort = {{ $v.Second }}
{{- end }}

Client Plugins

frpc only forwards requests to local TCP or UDP ports by default.

Plugins are used for providing rich features. There are built-in plugins such as unix_domain_socket, http_proxy, socks5, static_file, http2https, https2http, https2https and you can see example usage.

Using plugin http_proxy:

# frpc.toml

[[proxies]]
name = "http_proxy"
type = "tcp"
remotePort = 6000
[proxies.plugin]
type = "http_proxy"
httpUser = "abc"
httpPassword = "abc"

httpUser and httpPassword are configuration parameters used in http_proxy plugin.

Server Manage Plugins

Read the document.

Find more plugins in gofrp/plugin.

SSH Tunnel Gateway

added in v0.53.0

frp supports listening to an SSH port on the frps side and achieves TCP protocol proxying through the SSH -R protocol, without relying on frpc.

# frps.toml
sshTunnelGateway.bindPort = 2200

When running ./frps -c frps.toml, a private key file named .autogen_ssh_key will be automatically created in the current working directory. This generated private key file will be used by the SSH server in frps.

Executing the command

ssh -R :80:127.0.0.1:8080 v0@{frp address} -p 2200 tcp --proxy_name "test-tcp" --remote_port 9090

sets up a proxy on frps that forwards the local 8080 service to the port 9090.

frp (via SSH) (Ctrl+C to quit)

User:
ProxyName: test-tcp
Type: tcp
RemoteAddress: :9090

This is equivalent to:

frpc tcp --proxy_name "test-tcp" --local_ip 127.0.0.1 --local_port 8080 --remote_port 9090

Please refer to this document for more information.

Virtual Network (VirtualNet)

Alpha feature added in v0.62.0

The VirtualNet feature enables frp to create and manage virtual network connections between clients and visitors through a TUN interface. This allows for IP-level routing between machines, extending frp beyond simple port forwarding to support full network connectivity.

For detailed information about configuration and usage, please refer to the VirtualNet documentation.

Feature Gates

frp supports feature gates to enable or disable experimental features. This allows users to try out new features before they're considered stable.

Available Feature Gates

Name	Stage	Default	Description
VirtualNet	ALPHA	false	Virtual network capabilities for frp

Enabling Feature Gates

To enable an experimental feature, add the feature gate to your configuration:

featureGates = { VirtualNet = true }

Feature Lifecycle

Features typically go through three stages:

ALPHA: Disabled by default, may be unstable
BETA: May be enabled by default, more stable but still evolving
GA (Generally Available): Enabled by default, ready for production use

Related Projects

gofrp/plugin - A repository for frp plugins that contains a variety of plugins implemented based on the frp extension mechanism, meeting the customization needs of different scenarios.
gofrp/tiny-frpc - A lightweight version of the frp client (around 3.5MB at minimum) implemented using the ssh protocol, supporting some of the most commonly used features, suitable for devices with limited resources.

Contributing

Interested in getting involved? We would like to help you!

Take a look at our issues list and consider sending a Pull Request to dev branch.
If you want to add a new feature, please create an issue first to describe the new feature, as well as the implementation approach. Once a proposal is accepted, create an implementation of the new features and submit it as a pull request.
Sorry for my poor English. Improvements for this document are welcome, even some typo fixes.
If you have great ideas, send an email to fatedier@gmail.com.

Note: We prefer you to give your advise in issues, so others with a same question can search it quickly and we don't need to answer them repeatedly.

Donation

If frp helps you a lot, you can support us by:

GitHub Sponsors

Support us by Github Sponsors.

You can have your company's logo placed on README file of this project.

PayPal

Donate money by PayPal to my account fatedier@gmail.com.

ollama/ollama

Get up and running with Kimi-K2.6, GLM-5.2, MiniMax, DeepSeek, gpt-oss, Qwen, Gemma and other models.

Ollama

Start building with open models.

Download

macOS

curl -fsSL https://ollama.com/install.sh | sh

or download manually

Windows

irm https://ollama.com/install.ps1 | iex

or download manually

Linux

curl -fsSL https://ollama.com/install.sh | sh

Manual install instructions

Docker

The official Ollama Docker image ollama/ollama is available on Docker Hub.

Libraries

Community

Get started

ollama

You'll be prompted to run a model or connect Ollama to your existing agents or applications such as Claude Code, OpenClaw, OpenCode , Codex, Copilot, and more.

Coding

To launch a specific integration:

ollama launch claude

Supported integrations include Claude Code, Codex, Copilot CLI, DeepSeek Harness, Droid, and OpenCode.

AI assistant

Use OpenClaw to turn Ollama into a personal AI assistant across WhatsApp, Telegram, Slack, Discord, and more:

ollama launch openclaw

Chat with a model

Run and chat with Gemma 4:

ollama run gemma4

See ollama.com/library for the full list.

See the quickstart guide for more details.

REST API

Ollama has a REST API for running and managing models.

curl http://localhost:11434/api/chat -d '{
  "model": "gemma4",
  "messages": [{
    "role": "user",
    "content": "Why is the sky blue?"
  }],
  "stream": false
}'

See the API documentation for all endpoints.

Python

pip install ollama

from ollama import chat

response = chat(model='gemma4', messages=[
  {
    'role': 'user',
    'content': 'Why is the sky blue?',
  },
])
print(response.message.content)

JavaScript

npm i ollama

import ollama from "ollama";

const response = await ollama.chat({
  model: "gemma4",
  messages: [{ role: "user", content: "Why is the sky blue?" }],
});
console.log(response.message.content);

Supported backends

llama.cpp project founded by Georgi Gerganov.

Documentation

Community Integrations

Want to add your project? Open a pull request.

Chat Interfaces

Web

Open WebUI - Extensible, self-hosted AI interface
Onyx - Connected AI workspace
LibreChat - Enhanced ChatGPT clone with multi-provider support
Lobe Chat - Modern chat framework with plugin ecosystem (docs)
NextChat - Cross-platform ChatGPT UI (docs)
Perplexica - AI-powered search engine, open-source Perplexity alternative
big-AGI - AI suite for professionals
Lollms WebUI - Multi-model web interface
ChatOllama - Chatbot with knowledge bases
Bionic GPT - On-premise AI platform
Chatbot UI - ChatGPT-style web interface
Hollama - Minimal web interface
Chatbox - Desktop and web AI client
chat - Chat web app for teams
Ollama RAG Chatbot - Chat with multiple PDFs using RAG
Tkinter-based client - Python desktop client

Desktop

Dify.AI - LLM app development platform
AnythingLLM - All-in-one AI app for Mac, Windows, and Linux
Maid - Cross-platform mobile and desktop client
Witsy - AI desktop app for Mac, Windows, and Linux
Cherry Studio - Multi-provider desktop client
Ollama App - Multi-platform client for desktop and mobile
PyGPT - AI desktop assistant for Linux, Windows, and Mac
Alpaca - GTK4 client for Linux and macOS
SwiftChat - Cross-platform including iOS, Android, and Apple Vision Pro
Enchanted - Native macOS and iOS client
RWKV-Runner - Multi-model desktop runner
Ollama Grid Search - Evaluate and compare models
macai - macOS client for Ollama and ChatGPT
AI Studio - Multi-provider desktop IDE
Reins - Parameter tuning and reasoning model support
ConfiChat - Privacy-focused with optional encryption
LLocal.in - Electron desktop client
MindMac - AI chat client for Mac
Msty - Multi-model desktop client
BoltAI for Mac - AI chat client for Mac
IntelliBar - AI-powered assistant for macOS
Kerlig AI - AI writing assistant for macOS
Hillnote - Markdown-first AI workspace
Perfect Memory AI - Productivity AI personalized by screen and meeting history

Mobile

Ollama Android Chat - One-click Ollama on Android

SwiftChat, Enchanted, Maid, Ollama App, Reins, and ConfiChat listed above also support mobile platforms.

Code Editors & Development

Cline - VS Code extension for multi-file/whole-repo coding
Continue - Open-source AI code assistant for any IDE
Void - Open source AI code editor, Cursor alternative
Copilot for Obsidian - AI assistant for Obsidian
twinny - Copilot and Copilot chat alternative
gptel Emacs client - LLM client for Emacs
Ollama Copilot - Use Ollama as GitHub Copilot
Obsidian Local GPT - Local AI for Obsidian
Ellama Emacs client - LLM tool for Emacs
orbiton - Config-free text editor with Ollama tab completion
AI ST Completion - Sublime Text 4 AI assistant
VT Code - Rust-based terminal coding agent with Tree-sitter
QodeAssist - AI coding assistant for Qt Creator
AI Toolkit for VS Code - Microsoft-official VS Code extension
Open Interpreter - Natural language interface for computers

Libraries & SDKs

LiteLLM - Unified API for 100+ LLM providers
Semantic Kernel - Microsoft AI orchestration SDK
LangChain4j - Java LangChain (example)
LangChainGo - Go LangChain (example)
Spring AI - Spring framework AI support (docs)
LangChain and LangChain.js with example
Ollama for Ruby - Ruby LLM library
any-llm - Unified LLM interface by Mozilla
OllamaSharp for .NET - .NET SDK
LangChainRust - Rust LangChain (example)
Agents-Flex for Java - Java agent framework (example)
Elixir LangChain - Elixir LangChain
Ollama-rs for Rust - Rust SDK
LangChain for .NET - .NET LangChain (example)
chromem-go - Go vector database with Ollama embeddings (example)
LangChainDart - Dart LangChain
LlmTornado - Unified C# interface for multiple inference APIs
Ollama4j for Java - Java SDK
Ollama for Laravel - Laravel integration
Ollama for Swift - Swift SDK
LlamaIndex and LlamaIndexTS - Data framework for LLM apps
Haystack - AI pipeline framework
Firebase Genkit - Google AI framework
Ollama-hpp for C++ - C++ SDK
PromptingTools.jl - Julia LLM toolkit (example)
Ollama for R - rollama - R SDK
Portkey - AI gateway
Testcontainers - Container-based testing
LLPhant - PHP AI framework

Frameworks & Agents

AutoGPT - Autonomous AI agent platform
crewAI - Multi-agent orchestration framework
Strands Agents - Model-driven agent building by AWS
Cheshire Cat - AI assistant framework
any-agent - Unified agent framework interface by Mozilla
Stakpak - Open source DevOps agent
Hexabot - Conversational AI builder
Neuro SAN - Multi-agent orchestration (docs)

RAG & Knowledge Bases

RAGFlow - RAG engine based on deep document understanding
R2R - Open-source RAG engine
MaxKB - Ready-to-use RAG chatbot
Minima - On-premises or fully local RAG
Chipper - AI interface with Haystack RAG
ARGO - RAG and deep research on Mac/Windows/Linux
Archyve - RAG-enabling document library
Casibase - AI knowledge base with RAG and SSO
BrainSoup - Native client with RAG and multi-agent automation

Bots & Messaging

LangBot - Multi-platform messaging bots with agents and RAG
AstrBot - Multi-platform chatbot with RAG and plugins
Discord-Ollama Chat Bot - TypeScript Discord bot
Ollama Telegram Bot - Telegram bot
LLM Telegram Bot - Telegram bot for roleplay

Terminal & CLI

aichat - All-in-one LLM CLI with Shell Assistant, RAG, and AI tools
oterm - Terminal client for Ollama
gollama - Go-based model manager for Ollama
tlm - Local shell copilot
tenere - TUI for LLMs
ParLlama - TUI for Ollama
llm-ollama - Plugin for Datasette's LLM CLI
ShellOracle - Shell command suggestions
LLM-X - Progressive web app for LLMs
cmdh - Natural language to shell commands
VT - Minimal multimodal AI chat app

Productivity & Apps

AppFlowy - AI collaborative workspace, self-hostable Notion alternative
Screenpipe - 24/7 screen and mic recording with AI-powered search
Vibe - Transcribe and analyze meetings
Page Assist - Chrome extension for AI-powered browsing
NativeMind - Private, on-device browser AI assistant
Ollama Fortress - Security proxy for Ollama
1Panel - Web-based Linux server management
Writeopia - Text editor with Ollama integration
QA-Pilot - GitHub code repository understanding
Raycast extension - Ollama in Raycast
Painting Droid - Painting app with AI integrations
Serene Pub - AI roleplaying app
Mayan EDMS - Document management with Ollama workflows
TagSpaces - File management with AI tagging

Observability & Monitoring

Opik - Debug, evaluate, and monitor LLM applications
OpenLIT - OpenTelemetry-native monitoring for Ollama and GPUs
Lunary - LLM observability with analytics and PII masking
Langfuse - Open source LLM observability
HoneyHive - AI observability and evaluation for agents
MLflow Tracing - Open source LLM observability

Database & Embeddings

pgai - PostgreSQL as a vector database (guide)
MindsDB - Connect Ollama with 200+ data platforms
chromem-go - Embeddable vector database for Go (example)
Kangaroo - AI-powered SQL client

Infrastructure & Deployment

Cloud

Google Cloud
Fly.io
Koyeb
Harbor - Containerized LLM toolkit with Ollama as default backend

Package Managers

helm/helm

The Kubernetes Package Manager

Helm

Helm is a tool for managing Charts. Charts are packages of pre-configured Kubernetes resources.

Use Helm to:

Find and use popular software packaged as Helm Charts to run in Kubernetes
Share your own applications as Helm Charts
Create reproducible builds of your Kubernetes applications
Intelligently manage your Kubernetes manifest files
Manage releases of Helm packages

Helm in a Handbasket

Helm is a tool that streamlines installing and managing Kubernetes applications. Think of it like apt/yum/homebrew for Kubernetes.

Helm renders your templates and communicates with the Kubernetes API
Helm runs on your laptop, CI/CD, or wherever you want it to run.
Charts are Helm packages that contain at least two things:
- A description of the package (Chart.yaml)
- One or more templates, which contain Kubernetes manifest files
Charts can be stored on disk, or fetched from remote chart repositories (like Debian or RedHat packages)

Helm Development and Stable Versions

Helm v4 is the current stable release, developed on the main branch. Helm v3 is in support mode on the dev-v3 branch: bug fixes until July 8th 2026, security fixes until November 11th 2026.

Install

Binary downloads of the Helm client can be found on the Releases page.

Unpack the helm binary and add it to your PATH and you are good to go!

If you want to use a package manager:

Homebrew users can use brew install helm.
Chocolatey users can use choco install kubernetes-helm.
Winget users can use winget install Helm.Helm.
Scoop users can use scoop install helm.
Snapcraft users can use snap install helm --classic.
Flox users can use flox install kubernetes-helm.
Mise-en-place users can use mise use -g helm@latest

To rapidly get Helm up and running, start with the Quick Start Guide.

See the installation guide for more options, including installing pre-releases.

Docs

Get started with the Quick Start guide or plunge into the complete documentation.

Roadmap

The Helm roadmap uses GitHub milestones to track the progress of the project.

Helm v4 development happens on the main branch. Helm v3 is in support mode on the dev-v3 branch and receives only bug and security fixes.

Community, discussion, contribution, and support

You can reach the Helm community and developers via the following channels:

Kubernetes Slack:
Mailing List:
- Helm Mailing List
Developer Call: Thursdays at 9:30-10:00 Pacific (meeting details)

Contribution

If you're interested in contributing, please refer to the Contributing Guide before submitting a pull request.

Code of conduct

Participation in the Helm community is governed by the Code of Conduct.

m1k1o/neko

A self hosted virtual browser that runs in docker and uses WebRTC.

n.eko

Welcome to Neko, a self-hosted virtual browser that runs in Docker and uses WebRTC technology. Neko is a powerful tool that allows you to run a fully-functional browser in a virtual environment, giving you the ability to access the internet securely and privately from anywhere. With Neko, you can browse the web, run applications, and perform other tasks just as you would on a regular browser, all within a secure and isolated environment. Whether you are a developer looking to test web applications, a privacy-conscious user seeking a secure browsing experience, or simply someone who wants to take advantage of the convenience and flexibility of a virtual browser, Neko is the perfect solution.

In addition to its security and privacy features, Neko offers the ability for multiple users to access it simultaneously. This makes it an ideal solution for teams or organizations that need to share access to a browser, as well as for individuals who want to use multiple devices to access the same virtual environment. With Neko, you can easily and securely share access to a browser with others, without having to worry about maintaining separate configurations or settings. Whether you need to collaborate on a project, access shared resources, or simply want to share access to a browser with friends or family, Neko makes it easy to do so.

Neko is also a great tool for hosting watch parties and interactive presentations. With its virtual browser capabilities, Neko allows you to host watch parties and presentations that are accessible from anywhere, without the need for in-person gatherings. This makes it easy to stay connected with friends and colleagues, even when you are unable to meet in person. With Neko, you can easily host a watch party or give an interactive presentation, whether it's for leisure or work. Simply invite your guests to join the virtual environment, and you can share the screen and interact with them in real-time.

About

This app uses WebRTC to stream a desktop inside of a docker container, original author made this because rabb.it went under and his internet could not handle streaming and discord kept crashing when his friend attempted to. He just wanted to watch anime with his friends ლ(ಠ益ಠლ) so he started digging throughout the internet and found a few kinda clones, but none of them had the virtual browser, then he found Turtus and he was able to figure out the rest.

Then I found this project and started to dig into it. I really liked the idea of having collaborative browser browsing together with multiple people, so I created a fork. Initially, I wanted to merge my changes to the upstream repository, but the original author did not have time for this project anymore and it got eventually archived.

Use-cases and comparison

Neko started as a virtual browser that is streamed using WebRTC to multiple users.

It is not only limited to a browser; it can run anything that runs on linux (e.g. VLC). Browser only happens to be the most popular and widely used use-case.
In fact, it is not limited to a single program either; you can install a full desktop environment (e.g. XFCE, KDE).
Speaking of limits, it does not need to run in a container; you could install neko on your host, connect to your X server and control your whole VM.
Theoretically it is not limited to only X server, anything that can be controlled and scraped periodically for images could be used instead.
- Like implementing RDP or VNC protocol, where neko would only act as WebRTC relay server. This is currently only future.

Primary use case is connecting with multiple people, leveraging real time synchronization and interactivity:

Watch party - watching video content together with multiple people and reacting to it (chat, emotes) - open source alternative to giggl.app or hyperbeam.
Interactive presentation - not only screen sharing, but others can control the screen.
Collaborative tool - brainstorming ideas, cobrowsing, code debugging together.
Support/Teaching - interactively guiding people in controlled environment.
Embed anything - embed virtual browser in your web app - open source alternative to hyperbeam API.
- open any third-party website or application, synchronize audio and video flawlessly among multiple participants.
- request rooms using API with neko-rooms.
Neko inside VR Chat - watch remote browser together with friends in VR.

Other use cases that benefit from single-user:

Personal workspace - streaming containerized apps and desktops to end-users - similar to kasm.
Persistent browser - own browser with persistent cookies available anywhere - similar to mightyapp.
- no state is left on the host browser after terminating the connection.
- sensitive data like cookies are not transferred - only video is shared.
Throwaway browser - a better solution for planning secret parties and buying birthday gifts off the internet.
- use Tor Browser and VPN for additional anonymity.
- mitigates risk of OS fingerprinting and browser vulnerabilities by running in container.
Session broadcasting - broadcast room content using RTMP (to e.g. twitch or youtube...).
Session recording - broadcast RTMP can be saved to a file using e.g. nginx-rtmp
- have clean environment when recording tutorials.
- no need to hide bookmarks or use incognito mode.
Jump host - access your internal applications securely without the need for VPN.
Automated browser - you can install playwright or puppeteer and automate tasks while being able to actively intercept them.

Compared to clientless remote desktop gateway (e.g. Apache Guacamole or websockify with noVNC), installed with remote desktop server along with desired program (e.g. linuxserver/firefox) provides neko additionally:

Smooth video because it uses WebRTC and not images sent over WebSockets.
Built in audio support, what is not part of Apache Guacamole or noVNC.
Multi-participant control, what is not natively supported by Apache Guacamole or noVNC.

Supported browsers

... see all available images

Other applications

... others in m1k1o/neko-apps

Why neko?

I like cats 🐱 (Neko is the Japanese word for cat), I'm a weeb/nerd.

But why the cat butt? Because cats are assholes, but you love them anyways.

Multiple rooms

For neko room management software, visit neko-rooms.

It also offers Zero-knowledge installation (with HTTPS).

Documentation

Full documentation is available at neko.m1k1o.net. Key sections include:

How to Contribute

Contributions are welcome! Check the Contributing Guide for details.

Support

If you find Neko useful, consider supporting the project via GitHub Sponsors.

	Krill AI provides fast, stable API access to GPT, Claude, Gemini, and leading Chinese models, with enterprise customization, invoicing, 7×16 support, and optimized WebSocket connections for faster first-token latency. Register through the exclusive link and use code “grok2api” for 23% off your first Codex package.
	DEEIX-Chat is an open-source, self-hostable AI Chat platform for individuals, teams, and enterprises that need stable, long-term, unified access to multiple models. It brings models, conversations, files, tool calling, and administration together in one deployable and extensible system. Click here to start deploying.
	Right Code is an enterprise-grade AI Agent distribution platform that primarily provides stable access services for Claude Code, Codex, Gemini, and other models. It supports invoicing and dedicated one-to-one assistance for enterprises and teams. Thanks to Right Code for providing token support. Click here to register and get started.
	FennoAI provides enterprise-grade OpenAI/Anthropic-compatible APIs for Codex, Claude Code, and OpenCode, processing hundreds of billions of tokens daily with global business settlement and invoicing. Through the Grok2API exclusive offer, USD 1.99 unlocks USD 50 in Coding Plan credits, plus referral commissions up to 20%.
	Qiniu Cloud AI, Qiniu Cloud’s (02567.HK) enterprise MaaS platform, offers protocol-compatible access to 150+ global models for text, image, audio, video, and files, serving 1.69+ million users. Grok2API registrations through the exclusive link receive 12 million free enterprise tokens or 3 million developer tokens.