Home

devctl wiki

devctl is a configuration-driven local development orchestrator. It starts and stops services, resolves environment, optional Google identity, an auth-aware proxy, health checks, and centralized logs — from a keyboard-first TUI, a CLI, an optional MCP server for coding agents, or an opt-in loopback web console.

The running product is TypeScript on Bun with an OpenTUI interface. There is no Go binary.

Start here

Page	What you get
How it fits together	Supervisor, TUI, CLI, MCP, and what lives on disk
Installation	npm, release binaries, source install, optional gcloud
Quick start	First session: setup → doctor → TUI
Onboard your repository	Inventory, configure, validate, and verify your own stack
Examples & recipes	Frontend, workers, containers, proxy, and tracing workflows
Developer setup	Day-to-day loop without admin privileges
Demo platform	Local invoicing example (no Google Cloud; opt-in Docker data profile)
Agent skills	Onboard a repo, or debug a service devctl is already running

Using it

Page	Side
Web console	Browser controls, dependency graph, logs, traces, LLM, traffic, doctor, identity
TUI	Screens, keys, slash commands, themes, settings
CLI	Commands, flags, exit codes, attach vs start
MCP	Localhost Streamable HTTP for Claude, Cursor, Codex, Kilo
Logs	Buffer, filters, export, history
LLM inspector	LiteLLM spend logs and proxy-capture sources in MCP, web, TUI, CLI
Proxy	Auth-aware reverse proxy, expose, and optional body inspect
Telemetry	OTLP receiver, traces, and the opt-in loopback web console
Doctor	Environment and Google diagnostics
Troubleshooting	Symptom → fix

Configuration

Page	Side
Configuration	Discovery, merge, validation, JSON Schema, reload
Services	Commands, ports, health, restart, dependencies
Profiles	Named sets, session recovery
Environment	Source order, ${…} refs, secrets
Custom HTTP APIs	Named outbound recipes, token cache, local expose
Plugins	SDK contract, extension points, generic OIDC provider

Identity and proxy

Page	Side
Authentication	ADC, project source, devctl auth
Impersonation	Service-account tokens without keys
IAP	Audience, user vs SA identity tokens
Proxy	Loopback routes, token endpoint, recipe expose, body inspect
Admin setup	IAM and APIs administrators own
Security	Redaction, bind rules, credential files

Contribute to this repository

These pages are not the operator manual. They map the TypeScript tree for people changing devctl itself.

Page	Side
Internals (contributor guide)	How to read the repo, every layer, RPC, adding features
Contributing	Source loop, tests, and where to edit docs

Reference

Page	Side
Building from source	app/ layout, tests, TUI config file
Architecture	Layers, composition roots, import rules
Platform bets	Remote/multi-repo/k8s/OIDC/signing — design separately
npm publishing	Maintainer bootstrap, trusted publishing, and release trust
Changelog	Notable changes, newest first
License	MIT
Security policy	How to report a vulnerability

Configuration never hard-codes service names, ports, or service accounts. Those belong in .devctl/.