:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
"""Pure data layer for tools.yaml: schema, parsing, persistence, and the
generated artifacts (compose override + user Dockerfile). No docker calls,
no interactive prompts, no side effects at import. Shares the catalog/user-file
YAML format with MCP servers via sandbox_addons; adds the tool-specific schema
and apply logic.
"""
from __future__ import annotations
from dataclasses import dataclass, field
from pathlib import Path
import yaml
import sandbox_addons
from sandbox_addons import REGISTRY_DIR, AddonError
TOOLS_FILE = REGISTRY_DIR / "tools.yaml"
TOOL_AUTH_COMPOSE_FILE = REGISTRY_DIR / "docker-compose.tool-auth.yml"
USER_DOCKERFILE = REGISTRY_DIR / "Dockerfile.user"
SANDBOX_DOCKERFILE = Path(__file__).resolve().parent.parent / "Dockerfile.sandbox"
# In-sandbox $HOME. Must stay in sync with SANDBOX_HOME in
# bin/sandbox-entrypoint.py; this is what ~ resolves to inside the container.
SANDBOX_HOME_IN_CONTAINER = "/home/sandbox"
def expand_sandbox_path(raw: str) -> str:
"""Expand ~ / ~/foo to the sandbox $HOME path. Everything else passes through."""
if raw == "~":
return SANDBOX_HOME_IN_CONTAINER
if raw.startswith("~/"):
return f"{SANDBOX_HOME_IN_CONTAINER}/{raw[2:]}"
return raw
@dataclass
class ToolCopy:
# Stored exactly as written in tools.yaml. ~ expands per side at copy time:
# host via Path.expanduser(), container via expand_sandbox_path().
source: str
target: str
@dataclass
class Tool:
name: str
install: str | None = None
copy: list[ToolCopy] = field(default_factory=list)
# Catalog-only metadata. None in user tools.yaml; populated when loaded
# from bin/sandbox-tools.yaml. save_user_tools never persists it.
description: str | None = None
def parse_tool_copy(entry: object, *, source_label: str) -> ToolCopy:
"""Short form (one string used for both sides) or long form ({source, target})."""
if isinstance(entry, str):
return ToolCopy(source=entry, target=entry)
if isinstance(entry, dict):
return ToolCopy(source=str(entry["source"]), target=str(entry["target"]))
raise AddonError(f"{source_label}: invalid copy entry {entry!r} (expected string or mapping).")
def _parse_entry(raw: dict) -> Tool:
# name presence/uniqueness is validated by sandbox_addons.load_named_entries.
name = raw["name"]
# Migration guard: 'mounts' was renamed to 'copy' in a recent commit.
if "mounts" in raw:
raise AddonError(
f"tool {name!r} uses 'mounts:' which was renamed to 'copy:'. "
"Edit the YAML key (the field semantics are unchanged)."
)
copy = [parse_tool_copy(c, source_label=f"tool {name!r} copy[{i}]") for i, c in enumerate(raw.get("copy") or [])]
return Tool(name=name, install=raw.get("install"), copy=copy, description=raw.get("description") or None)
def load_user_tools() -> list[Tool]:
return sandbox_addons.load_entries(TOOLS_FILE, "tools", _parse_entry)
def load_catalog(catalog_file: Path) -> dict[str, Tool]:
# Catalog Tool instances have `description` set; user tools.yaml does not.
return sandbox_addons.load_catalog(catalog_file, "tools", _parse_entry)
def resolved_tools(catalog_file: Path) -> list[tuple[str, str]]:
"""Return (name, description) for the user's selected tools.
Descriptions come from the catalog, since the user tools.yaml doesn't store
them; tools added ad hoc (not in the catalog) get an empty description.
bin/sandbox uses this to list installed tools in the sandbox CLAUDE.md.
"""
catalog = load_catalog(catalog_file)
return [(t.name, (catalog[t.name].description if t.name in catalog else None) or "") for t in load_user_tools()]
def _format_copy(c: ToolCopy) -> str | dict[str, str]:
return c.source if c.source == c.target else {"source": c.source, "target": c.target}
def save_user_tools(tools: list[Tool]) -> None:
entries: list[dict] = []
for t in tools:
entry: dict = {"name": t.name}
if t.install is not None:
entry["install"] = t.install if t.install.endswith("\n") else t.install + "\n"
if t.copy:
entry["copy"] = [_format_copy(c) for c in t.copy]
entries.append(entry)
sandbox_addons.save_named_entries(TOOLS_FILE, "tools", entries)
def write_user_dockerfile(tools: list[Tool], *, out: Path = USER_DOCKERFILE) -> Path:
# Inlines the base Dockerfile and appends a RUN block per tool. Docker's
# BuildKit layer cache shares the base content across users by content,
# so there is no separate base-image tag to manage.
#
# Creates the sandbox user at build time with home = SANDBOX_HOME_IN_CONTAINER
# (the same path the entrypoint uses at runtime) so `npm install -g` etc. and
# ~ resolve consistently. The entrypoint's create_sandbox_user is idempotent:
# it skips when this build-time user already exists.
home = SANDBOX_HOME_IN_CONTAINER
parts = [
SANDBOX_DOCKERFILE.read_text().rstrip(),
"\n\n# --- Personal tool layers (generated from ~/.posthog-sandboxes/tools.yaml) ---\n",
"ARG SANDBOX_UID\nARG SANDBOX_GID\n\n",
"RUN groupadd -g ${SANDBOX_GID} sandbox 2>/dev/null || true \\\n",
f" && useradd -u ${{SANDBOX_UID}} -g ${{SANDBOX_GID}} -d {home} -m -s /bin/bash sandbox\n\n",
"USER sandbox\n",
f"ENV NPM_CONFIG_PREFIX={home}/.npm-global\n",
f"ENV PATH={home}/.npm-global/bin:{home}/.local/bin:${{PATH}}\n",
f"RUN mkdir -p {home}/.npm-global/bin {home}/.local/bin\n\n",
]
for t in tools:
snippet = (t.install or "").strip()
if not snippet:
continue
parts.append(f"# Tool: {t.name}\n")
parts.append("RUN <<'__POSTHOG_SANDBOX_EOF__'\nset -e\n")
parts.append(snippet + "\n")
parts.append("__POSTHOG_SANDBOX_EOF__\n\n")
parts.append("USER root\n")
out.parent.mkdir(parents=True, exist_ok=True)
out.write_text("".join(parts))
return out
def write_user_image_compose(*, dockerfile: Path) -> Path:
# Override that points `build.dockerfile` at the per-user Dockerfile
# generated from tools.yaml. Rewritten before every `docker compose`
# call; tools.yaml is the source of truth so there's no cache to
# invalidate.
TOOL_AUTH_COMPOSE_FILE.parent.mkdir(parents=True, exist_ok=True)
with open(TOOL_AUTH_COMPOSE_FILE, "w") as f:
yaml.safe_dump(
{"services": {"app": {"build": {"dockerfile": str(dockerfile)}}}},
f,
sort_keys=False,
)
return TOOL_AUTH_COMPOSE_FILE