• Why devctl
• Features
• Quick start
• Install
• Set up your repo
• Architecture
• Documentation
• Security model
• Project status

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, python start 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.

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.

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).

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.

cd your-repo
devctl setup
devctl doctor
devctl

1. setup writes .devctl/config.yaml (or use the TUI setup screen).
2. doctor names what is missing — ports, tools, ADC, container runtimes.
3. Empty dashboard: enter starts the first profile (alphabetically).
4. Leave the TUI and keep working: devctl start --profile backend then devctl attach. The daemon already outlives start; --detach is deprecated and does nothing.

TUI prefs live in ~/.devctl/tui.json or DEVCTL_TUI_CONFIG. Built on OpenTUI.

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.

The full documentation site is also published as a GitHub Wiki. Changing this repository (not YAML in some other repo): contributor internals.

• 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.1 only; MCP, OTLP, and the web console are off by default.
• Local services run with zero Google Cloud.

See Security for the full model.

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.

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.