Deployment
Relevant source files
The following files were used as context for generating this wiki page:
Deployment within the pi-mono project encompasses several distinct processes, from publishing the suite of packages to npm, to running specific applications like the mom Slack bot in a Docker container or managing GPU deployments with the pods CLI. The monorepo uses a lockstep versioning system, ensuring all packages are released together with consistent version numbers.
This document outlines the different deployment and execution models for the various components of the project, including the monorepo-wide release process and the specific setup for individual packages like mom, pods, and proxy.
Monorepo Release Process
The entire monorepo follows a strict, lockstep versioning and publishing process. All packages must always have the same version number. The process is managed through a combination of npm scripts and a custom version synchronization script.
Sources: README.md:52-92, package.json:10-18, scripts/sync-versions.js, AGENTS.md:46-68
Versioning
Version bumps are handled by dedicated npm scripts, which ensure all package.json files across the workspaces are updated consistently.
| Command | Description |
|---|---|
npm run version:patch | Bumps the patch version (e.g., 0.7.5 -> 0.7.6) for bug fixes. |
npm run version:minor | Bumps the minor version (e.g., 0.7.5 -> 0.8.0) for new features. |
npm run version:major | Bumps the major version (e.g., 0.7.5 -> 1.0.0) for breaking changes. |
Sources: package.json:15-17, README.md:55-59, AGENTS.md:50-53
These scripts first update the version in all package workspaces and then execute scripts/sync-versions.js to update all inter-package dependency versions to match the new lockstep version.
Sources: package.json:15-17, scripts/sync-versions.js:4-6
Publishing Flow
The release process involves several manual and scripted steps to ensure a consistent and well-documented release.
The following diagram illustrates the complete release workflow.
- Update Changelog: New entries are added under the
## [Unreleased]section in the relevantCHANGELOG.mdfile.
Sources: AGENTS.md:42-45, README.md:64-67 - Bump Version: Run one of the
npm run version:*commands.
Sources: README.md:70-73 - Finalize Changelog: The
[Unreleased]heading is renamed to the new version number with the current date (e.g.,## [0.12.12] - 2025-12-05). Released version sections are immutable.
Sources: AGENTS.md:55-56, README.md:76-80 - Commit and Tag: The changes are committed, and a git tag corresponding to the new version is created and pushed.
Sources: AGENTS.md:59-64, README.md:83-88 - Publish: The
npm run publishcommand is executed, which builds all packages and publishes them to npm.
Sources: package.json:19, README.md:91 - Prepare for Next Cycle: A new, empty
## [Unreleased]section is added to the top of the changelog.
Sources: AGENTS.md:67-68, README.md:94-97
Component-Specific Deployment
Different packages within the monorepo have their own deployment and execution models.
mom (Slack Bot)
The mom package is a Slack bot designed to be run in a Docker container for isolation and security. It can also be run directly on the host, but this is not recommended.
Sources: packages/mom/README.md:1-4, packages/mom/README.md:63-71
Docker Deployment (Recommended)
The recommended deployment method uses a standard alpine:latest Docker image as a sandbox. The host's data directory is mounted into the container at /workspace.
- Create Docker Sandbox: A long-running Alpine container is started to serve as the execution environment.
docker run -d \ --name mom-sandbox \ -v $(pwd)/data:/workspace \ alpine:latest \ tail -f /dev/null - Run
mom: ThemomCLI is executed with the--sandboxflag pointing to the created container.mom --sandbox=docker:mom-sandbox ./data
Sources: packages/mom/README.md:40-49
The agent's working directory inside the container is /workspace, which corresponds to the ./data directory on the host. This ensures that conversation history, generated files, and custom "skills" are persisted on the host machine.
Sources: packages/mom/README.md:85-99, packages/mom/src/agent.ts:213-214
Environment Variables
mom requires several environment variables for its operation, primarily for Slack and AI provider authentication.
| Variable | Description |
|---|---|
MOM_SLACK_APP_TOKEN | Slack app-level token (starts with xapp-...). |
MOM_SLACK_BOT_TOKEN | Slack bot token (starts with xoxb-...). |
ANTHROPIC_API_KEY | Anthropic API key. |
ANTHROPIC_OAUTH_TOKEN | Alternative Anthropic OAuth token. |
Sources: packages/mom/README.md:53-58
pods (GPU Pod Manager)
The pods package provides a command-line interface for managing vLLM (Very Large Language Model) deployments on GPU pods. Its functionality is not detailed in the provided files, but its existence as a deployment management tool is clear from its description.
Sources: README.md:14
proxy (CORS Proxy)
The proxy package is a simple CORS proxy server. It is executed via its CLI and is intended for browser-based LLM API calls. The provided source files do not contain detailed deployment instructions beyond its CLI invocation.
Sources: README.md:13
coding-agent (CLI Tool)
The coding-agent is an interactive CLI tool. While not "deployed" in a server sense, it has a self-management capability for its own dependencies, such as fd and ripgrep.
Tool Self-Installation
On startup, the coding-agent ensures that required command-line tools like fd and rg are available. If they are not found in the system PATH, it automatically downloads and installs them into a local tools directory (~/.config/pi-coding-agent/tools).
This diagram shows the logic for ensuring a tool is available.
This self-provisioning mechanism simplifies the initial setup for the end-user, as they do not need to manually install these dependencies.
Sources: packages/coding-agent/src/tools-manager.ts:161-182
Execution
The agent is run directly via its entry point. The main function parses command-line arguments to configure the session, including the model, system prompt, and operational mode (interactive, single-shot, or RPC).
Sources: packages/coding-agent/src/main.ts:592-596
Summary
Deployment in pi-mono is multifaceted, reflecting the diverse nature of its packages. The core of the project's deployment strategy is the robust, lockstep release process for publishing all packages to npm. For runtime, mom utilizes Docker for a secure, sandboxed environment, while other tools like coding-agent feature self-contained dependency management, and pods and proxy exist as specialized CLI tools for their respective deployment tasks. This structure provides both a unified release cycle and flexible, component-specific deployment patterns.