README
¶
pilot
Dev Environment as Code. AI-native. Terminal-first.
Most deployment friction isn't technical. It's the gap between what you told your AI agent, what Docker actually built, and what landed on your VPS — silently broken.
pilot closes that gap. One file — pilot.yaml — is the single source of truth for your entire infrastructure. pilot reads it to run your app locally, your AI agent reads it to generate optimized infra files, and pilot executes the same contract in production. Zero drift, by design.
Install
macOS / Linux — one-liner via the install script:
curl -fsSL https://raw.githubusercontent.com/mouhamedsylla/pilot/main/install.sh | sh
Go toolchain — if you already have Go installed:
go install github.com/mouhamedsylla/pilot@latest
Quick start
pilot init # scaffold pilot.yaml + .mcp.json
pilot up # run locally (docker compose)
pilot push # build + push image
pilot deploy # SSH → sync → migrate → deploy → healthcheck
Claude Code and Cursor pick up .mcp.json automatically — your agent can run any of these commands without leaving the chat.
bob — the pilot agent
bob is pilot's dedicated AI agent. Instead of a chat window, it's a terminal-first REPL that talks directly to pilot via MCP.
pip install bob
bob # start the REPL
╭────────────────────────────────────────────────────────╮
│ ╭─╮╭─╮ │
│ ╰─╯╰─╯ bob v0.1 │
│ █ ▘▝ █ claude-3-5-sonnet · my-api · prod │
│ │
│ Décris ce que tu veux faire · Ctrl+D · Ctrl+C │
╰────────────────────────────────────────────────────────╯
bob knows your pilot.yaml, generates missing infra files, manages your env variables without leaking secrets, and deploys — all from a single prompt. Supports Anthropic, OpenAI, DeepSeek and Ollama models.
→ github.com/mouhamedsylla/bob
pilot.yaml
One file expresses intention — pilot infers execution.
apiVersion: pilot/v1
project:
name: my-api
stack: go
services:
app: { type: app, port: 8080 }
db: { type: postgres, version: "16" }
cache: { type: redis }
environments:
dev: { runtime: compose, env_file: .env.dev }
prod: { runtime: compose, target: vps-prod, env_file: .env.prod }
targets:
vps-prod: { type: vps, host: 1.2.3.4, user: deploy, key: ~/.ssh/id_pilot }
registry:
provider: ghcr
image: ghcr.io/mouhamedsylla/my-api
→ Full schema and options in docs/pilot-yaml.md
Documentation
| Topic | Link |
|---|---|
| Commands reference | docs/commands.md |
| pilot.yaml schema | docs/pilot-yaml.md |
| Resilience model (TypeA/B/C/D) | docs/resilience.md |
| MCP server & tools | docs/mcp-server.md |
| Architecture | docs/architecture.md |
MIT — built by Mouhamed SYLLA
One file. From local to production, always in sync.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package assets is reserved for future static asset embedding.
|
Package assets is reserved for future static asset embedding. |
|
internal
|
|
|
adapters/composer
Package composer generates docker-compose files and Dockerfiles from the service definitions in pilot.yaml.
|
Package composer generates docker-compose files and Dockerfiles from the service definitions in pilot.yaml. |
|
adapters/registry/imgbuild
Package imgbuild wraps docker build / buildx build for all registry adapters.
|
Package imgbuild wraps docker build / buildx build for all registry adapters. |
|
adapters/secrets/aws_sm
Package aws_sm implements SecretManager backed by AWS Secrets Manager.
|
Package aws_sm implements SecretManager backed by AWS Secrets Manager. |
|
adapters/secrets/gcp_sm
Package gcp_sm implements SecretManager backed by GCP Secret Manager.
|
Package gcp_sm implements SecretManager backed by GCP Secret Manager. |
|
app/deploy
Package deploy implements the pilot deploy use case.
|
Package deploy implements the pilot deploy use case. |
|
app/diagnose
Package diagnose implements the "pilot diagnose" snapshot.
|
Package diagnose implements the "pilot diagnose" snapshot. |
|
app/envdiff
Package envdiff compares two pilot environments and reports their divergences.
|
Package envdiff compares two pilot environments and reports their divergences. |
|
app/logs
Package logs implements the pilot logs use case.
|
Package logs implements the pilot logs use case. |
|
app/planview
Package planview implements the "pilot plan" use case.
|
Package planview implements the "pilot plan" use case. |
|
app/preflight
infra.go provides the real (system-touching) implementations of the preflight ports.
|
infra.go provides the real (system-touching) implementations of the preflight ports. |
|
app/push
Package push implements the pilot push use case.
|
Package push implements the pilot push use case. |
|
app/resume
Package resume implements the TypeC suspension/resume mechanism.
|
Package resume implements the TypeC suspension/resume mechanism. |
|
app/rollback
Package rollback implements the pilot rollback use case.
|
Package rollback implements the pilot rollback use case. |
|
app/runtime
Package runtime is the wiring layer: it reads pilot.yaml and constructs the correct domain port implementations.
|
Package runtime is the wiring layer: it reads pilot.yaml and constructs the correct domain port implementations. |
|
app/status
Package status implements the pilot status use case.
|
Package status implements the pilot status use case. |
|
app/sync
Package sync implements the pilot sync use case.
|
Package sync implements the pilot sync use case. |
|
app/up
Package up implements the pilot up / pilot down use cases.
|
Package up implements the pilot up / pilot down use cases. |
|
domain
Package domain defines the ports that the domain requires from the outside world.
|
Package domain defines the ports that the domain requires from the outside world. |
|
domain/errors
Package errors defines the four-type error taxonomy for pilot.
|
Package errors defines the four-type error taxonomy for pilot. |
|
domain/lock
Package lock manages pilot.lock — the validated, committed snapshot of what pilot will do on the next operation.
|
Package lock manages pilot.lock — the validated, committed snapshot of what pilot will do on the next operation. |
|
domain/plan
Package plan defines the execution plan and compensation logic for pilot operations.
|
Package plan defines the execution plan and compensation logic for pilot operations. |
|
domain/state
Package state manages the pilot runtime state machine and its persistence in .pilot/state.json.
|
Package state manages the pilot runtime state machine and its persistence in .pilot/state.json. |
|
env
Package env manages the active pilot environment.
|
Package env manages the active pilot environment. |
|
gitutil
Package gitutil provides small helpers for interacting with the local git repo.
|
Package gitutil provides small helpers for interacting with the local git repo. |
|
mcp/context
Package context collects the full project context.
|
Package context collects the full project context. |
|
meta
Package meta manages the .pilot/ metadata directory.
|
Package meta manages the .pilot/ metadata directory. |
|
scaffold
Package scaffold implements pilot init — project initialization.
|
Package scaffold implements pilot init — project initialization. |
|
scaffold/analyze
Package analyze inspects an existing project to infer which services it uses and how they are hosted (container vs managed external service).
|
Package analyze inspects an existing project to infer which services it uses and how they are hosted (container vs managed external service). |
|
scaffold/catalog
Package catalog defines every service type that pilot knows about.
|
Package catalog defines every service type that pilot knows about. |
|
version
Package version holds the build-time version string injected via ldflags.
|
Package version holds the build-time version string injected via ldflags. |
|
pkg
|
|
|
tools
|
|
|
img2term
command
tools/img2term converts a PNG image to ANSI half-block terminal art.
|
tools/img2term converts a PNG image to ANSI half-block terminal art. |
Click to show internal directories.
Click to hide internal directories.