devctl

Appearance

THE LOCAL DEVELOPMENT ORCHESTRATOR

More building.
Less tab juggling.

Your services, logs, and local stack. One terminal to start, inspect, and keep everything moving.

npm install --global @amr-m-abdelgawad/devctl

Node.js 18+ · macOS, Linux & Windows Requirements ↗

Get started Explore on GitHub

No account. Your machine. Try the demo

ONE TERMINAL. THE WHOLE PICTURE.
INTERACTIVE PLAYGROUND
devctldemo-platformminimal3/6 runningBROWSER DEMO
services
3/6click to start / stop
selnamestate
logs · recent activity
demo sessionservice actions appear here
14:50:15invoices-apiINFOhealthhealth HEALTHY 200
14:50:16telemetryWARNstdoutGET /invoices/{id} -> 401
14:50:17telemetryWARNstdoutPOST /invoices -> 429
14:50:17telemetryWARNstdoutrate limit exceeded for client
14:50:17identityINFOstdoutINFO identity 127.0.0.1 "GET /health HTTP/1.1" 200 -
14:50:17identityINFOhealthhealth HEALTHY 200
14:50:18identityINFOstdoutINFO identity heartbeat active_sessions=0
14:50:18telemetryINFOstdoutGET /invoices/{id} -> 200
14:50:19telemetryINFOstdoutPOST /invoices -> 200
14:50:19telemetryDEBUGstdoutqueue depth sample
14:50:19invoices-apiINFOstdoutINFO invoices-api 127.0.0.1 "GET /health HTTP/1.1" 200
14:50:20invoices-apiINFOstdoutINFO invoices-api heartbeat jobs=372 queued=372
14:50:21telemetryINFOstdoutGET /invoices -> 200
dashboardDEMOProfile minimallocal browser simulation

Try starting invoices-worker, then explore its logs.

Your running stack, in one view.

Click a service to start or stop it. Watch the running count and combined logs respond.

Less switching. More context.TUI / CLI / MCPOne shared session

WORK YOUR WAY

One stack. Your kind of control.

Stay hands-on, script the routine,
or let your agent take the next step.

Terminal

A home for your stack.

Start services, follow logs, and check health in a keyboard-first terminal interface.

Explore the TUI Command line

Make it a command.

Bring the same controls to scripts and CI. Run tasks, inspect config, and keep moving.

Meet the CLI AI agents

Give AI the context.

Connect your agent over MCP to inspect and operate the same local session. Enabled when you choose.

Connect with MCP

FROM STARTUP TO SOLVED

One session.
The whole investigation.

A typical debugging workflow
using the included demo platform.

STEP 01 / 04

Bring up only what you need.

In the demo platform, the backend profile groups identity, the API, its worker, and telemetry. Start them together, then attach to the same session.

devctl start --profile backend

Next: devctl attach

Read the guide

FIND YOUR FOCUS

The right services.
For the task at hand.

Group services into named profiles.
Start the part of your stack you need.

Explore profiles

DEMO PLATFORM / EXAMPLE PROFILE

devctl start --profile minimal

Start with the essentials: identity, the invoices API, and telemetry.

Your repo, your names. Profiles are defined in your config.

FROM REPO TO RUNNING

Small setup.
Clear head.

Start with Node.js. The npm package includes its own Bun runtime. Google Cloud is optional.

Installation guide
INSTALL ONCE. USE IN ANY REPO.
npm install --global @amr-m-abdelgawad/devctl

Then, from the repo you want to run:

  1. 01
    devctl setup

    Describe your services in a single config.

  2. 02
    devctl doctor

    See what’s missing before you start.

  3. 03
    devctl

    Open your dashboard. Press enter to start a profile.

YOUR REPO, DESCRIBED

A little config.
A working picture.

A minimal example adapted from the demo.
Run it from examples/demo-platform with Python 3.

.devctl/config.yaml YAML
version: 1
project:
  name: demo-platform
services:
  identity:
    command: [python3, main.py]
    working_dir: identity
    ports:
      http: 18001
    health:
      type: http
      url: http://127.0.0.1:18001/health
profiles:
  minimal:
    services: [identity]
  1. Keep your start command.

    Run the existing Python service in its own directory. No application rewrite.

  2. Describe readiness.

    Give the HTTP port a name and check the service’s /health endpoint.

  3. Choose a working set.

    The minimal profile here contains just identity. Add services as your repo grows.

THIS CONFIG STARTSidentity HTTP · 18001devctl start --profile minimal
Explore the config reference

WHERE IT FITS

Keep the tools.
Connect the workflow.

Your existing tools keep their place. devctl brings the running session together.

01

Docker Compose

Explore Compose

FOR YOUR CONTAINERS

Define multi-container applications, networks, and volumes.

WITH DEVCTL

Bring host processes and configured containers into one local session, with profiles and health checks.

Compose files aren’t imported automatically.
02

Task runners

Explore Task

FOR THE REPEATABLE

Build, format, and generate code with commands you already trust.

WITH DEVCTL

Keep those commands. Give long-running services and named tasks a shared place to run.

03

Terminal tabs

Your everyday workspace

FOR DIRECT CONTROL

Open a shell, run a command, and work directly with a process.

WITH DEVCTL

See service state and logs together. Your CLI, TUI, and optional agent connection share one supervisor.

THOUGHTFUL BY DEFAULT

Your machine.
Your ground rules.

One supervisor keeps processes, containers, the proxy, and logs in sync across every control surface.

See how it fits together
01

Configuration, not custom code.

Define services, profiles, health gates, and hooks in YAML.

02

Authentication, handled locally.

An auth-aware proxy injects Google / IAP tokens. Tokens stay out of logs.

03

Diagnostics without surprises.

Doctor reports missing tools and setup issues. It never auto-enables anything.

A DIFFERENT PERSPECTIVE

Same session.
Room to see more.

Follow services, requests, and traces in an optional local console. The same supervisor, with a wider view.

Explore the web console
devctl web console showing service health, profile controls, proxy requests, and recent errors
THE LOCAL CONSOLEOpt-in · Loopback only · One shared session

Your session, expanded. Services, traces, and logs together.

Local by default. Start it when you need it with devctl web start; the token rides in the URL fragment.

FOLLOW THE CONNECTIONS

More context.
Fewer blind spots.

01 / TOPOLOGY

See what depends on what.

Open /topology to inspect startup waves, health, and dependencies. Select a service to see its connections.

Explore the TUI
02 / REQUEST TRACING

Follow a request across services.

Inspect spans and correlated logs when your services emit trace data. Connect proxy requests to the evidence behind them.

Explore tracing
03 / YOUR AGENT

Ask a better-informed question.

“Why is invoices-api failing?” Enable MCP and connect your agent to inspect get_status, recent_errors, and get_logs. You control which tools are available.

Connect an agent

TAKE A LOOK AROUND

Meet your practice stack.

A console, an API, identity, and a worker. Explore the included demo platform before configuring your own repo.

Explore the demo

JUST SHIPPED

0.25.0 is out.

28 Sep 2026

Read the changelog
0.25.0

What’s new.

${identity.user} and ${user.identity} in service env and Helm YAML resolve to the developer email shown on the TUI identity screen.

A FEW GOOD QUESTIONS

Before you
press enter.

A little context for your first session.

Do I need Docker or Google Cloud?

Neither is required for local host processes. Use Docker or Podman when your configuration includes containers. Google Cloud tools are optional and only needed for the Google authentication features you choose to use. See installation requirements

Do I have to change my application code?

Describe how your services run in .devctl/config.yaml: their commands, working directories, environment, and health checks. devctl works with that configuration. Explore configuration

Can I use the CLI and TUI together?

Yes. The TUI, CLI, and MCP connect to the same per-repo supervisor. Start a profile from the CLI and attach to its session with devctl attach. See how sessions work

Does my agent get access automatically?

No. MCP is off by default. When enabled, it listens on the local loopback interface. You choose when to connect your agent and can disable individual tools. Read the MCP guide

Can I try it without a global install?

Yes. Run npx @amr-m-abdelgawad/devctl@latest from your repo. Node.js is required; the npm package includes its own Bun runtime. Follow the quick start

LESS FRICTION. MORE FORWARD.

Get your stack together.

Start your first session

Free and open source · MIT licensed · Use at your own risk

Released under the MIT License. Use at your own risk.

Copyright © 2026 Amr MOUSA · Security