devctl
One terminal for your local stack.
Start services, follow logs, trace requests, and inject cloud auth — from a keyboard-first TUI, the CLI, or an AI agent over MCP.
Contents
- Why devctl
- Features
- Quick start
- Install
- Set up your repo
- Architecture
- Documentation
- Security model
- Project status
Why devctl
A multi-service repo usually means five terminals, a forgotten .env, and a proxy nobody remembers how to start. devctl reads .devctl/ and runs the whole environment as one session — and nothing in the app knows your services by name. You add YAML, not code.
What sets it apart:
- Runs your real services, not images.
npm,uv,pythonstart as native host processes — fast reloads, a debugger you can attach directly, no Dockerfile — with Docker/Podman services opt-in when a dependency needs them. - Handles the cloud auth you'd otherwise hand-roll. A loopback proxy mints and injects Google / IAP tokens on both HTTP and gRPC, so local code reaches IAP-protected backends with no token logic of its own. Tokens never touch the logs.
- Structured logs and traces, built in. Every log is an OpenTelemetry-shaped record; an opt-in OTLP receiver and per-request tracing let you follow a request across services — and let an agent debug it.
- One session, four ways in. The TUI, the CLI, an MCP endpoint for your agent, and an opt-in loopback web console all drive the same supervisor — not four tools that each half-know the state.
Features
Google Cloud is optional. The demo platform starts locally without it and includes one opt-in route for testing service-account impersonation and IAP token minting.
Quick start
Node.js 18 or later. The npm package installs its own Bun runtime; no gcloud is needed for the local demo.
git clone https://github.com/amr-m-abdelgawad/devctl.git
cd devctl/examples/demo-platform
npx @amr-m-abdelgawad/devctl@latest
In the TUI: enter starts a profile · n / x start or stop a row · l logs · ? help · q quit.
Profiles: minimal · backend · full (includes the React console on localhost:18003) · data (opt-in Docker/PostgreSQL).
Install
Node.js is the only prerequisite — devctl bundles an official Bun runtime inside its npm package. For regular use, install it globally:
npm install --global @amr-m-abdelgawad/devctl
devctl version
Or run it without installing:
npx @amr-m-abdelgawad/devctl@latest
Unsigned standalone binaries and the repository's Homebrew formula remain available as alternative installation paths. Verify their published SHA-256 checksums; Apple and Microsoft do not identify those optional binaries as a verified publisher. Source installation still requires Bun. See Installation.
gcloud is needed only if a service or route uses user identity, impersonation, or IAP.
Set up your repo
cd your-repo
devctl setup
devctl doctor
devctl
setupwrites.devctl/config.yaml(or use the TUI setup screen).doctornames what is missing — ports, tools, ADC, container runtimes.- Empty dashboard:
enterstarts the first profile (alphabetically). - Leave the TUI and keep working:
devctl start --profile backendthendevctl attach. The daemon already outlivesstart;--detachis deprecated and does nothing.
TUI prefs live in ~/.devctl/tui.json or DEVCTL_TUI_CONFIG. Built on OpenTUI.
Architecture
flowchart LR
TUI --> Supervisor
CLI --> Supervisor
MCP["MCP · 127.0.0.1"] --> Supervisor
Web["Web · 127.0.0.1"] --> Supervisor
Supervisor --> Runtime["Host processes + containers"]
Supervisor --> Proxy
Supervisor --> Logs["Logs + traces"]
The supervisor owns host processes, optional Docker/Podman containers, the proxy, the log and trace buffers, and ~/.devctl/state/<repo>/. The TUI is a client. Agents talk HTTP to the same process — a stdio child of the TUI would die on quit. MCP and the web console are off by default. See how it fits together.
Documentation
The full documentation site is also published as a GitHub Wiki. Changing this repository (not YAML in some other repo): contributor internals.
Security model
- No hard-coded services, ports, profiles, or service accounts.
- User identity and service identity are never silently swapped.
- Tokens stay out of the TUI, logs, traces, and MCP output.
- Proxy, token endpoint, OTLP receiver, MCP, and the web console bind
127.0.0.1only; MCP, OTLP, and the web console are off by default. - Local services run with zero Google Cloud.
See Security for the full model.
Project status
devctl is pre-1.0 and under active development. A large portion of the codebase is AI-generated ("vibe-coded") rather than hand-written, so treat it as a work in progress. Reaching v1.0.0 will mean the codebase has been personally reviewed, tested, and validated, and the project is considered stable for general use. The roadmap lists what comes first, and which features are still experimental: those may change without a deprecation period until someone outside the original stack relies on them. If devctl doesn't fit your stack, tell us where it broke.
Use at your own risk. devctl is provided as-is, without warranty. It starts the processes in your configuration, reads the environment and secrets you point it at, and can mint cloud tokens or decrypt a SOPS file on your machine. You are responsible for that configuration, those credentials, and the commands it runs. See Security and the MIT license.
Issues and contributions are welcome — see Contributing.
MIT © 2026 Amr MOUSA · Contributing · Security policy