rentctl

A dev server should never outlive the work that needed it.

rentctl rents dev environments to your AI coding sessions. Every environment is a lease: it dies when the session ends, when the lease expires, or when you say so — whichever comes first. Cleanup is owned by code, not by an agent remembering to clean up.

Ships as both a CLI (rent) and an MCP server, so an agent can start and stop environments through tools instead of shelling out to a raw npm run dev it will forget about.

Why

An AI coding session starts a dev server. Then the session ends — crashes, is closed, or just moves on — and the server keeps running. By Friday there are six of them, three are on ports you've forgotten, and one is quietly serving stale code that makes a bug look unreproducible.

Telling the agent to clean up doesn't fix this, because the failure mode is the agent not doing what it was told. rentctl makes the cleanup structural: the environment has an expiry, and something other than the agent enforces it.

Install

uv tool install rentctl        # or: pipx install rentctl, or: pip install rentctl

Requires Python 3.12+. macOS and Linux. There is no Windows support and no Windows claim — POSIX sessions are the safety-critical mechanism here, and they have no tested Windows equivalent yet.

Upgrading from 1.0.x? Drain first. Run rent down --all in each project before you upgrade, then restart your agent sessions so their MCP servers load the new version. Skipping it is safe but degraded: a 1.0.x environment keeps working under 1.1 — rent up renews it, and rent down and rent sweep stop it by its whole session — but a 1.0.x watchdog still running from before the upgrade enforces its expiry with the old code, which can miss a child that outlived its shell.

First run

A framework-free server, so nothing but Python is involved. In a scratch repo:

mkdir hello && cd hello && git init -q
cat > rentctl.toml <<'EOF'
[project]
name = "hello"
runner = "process"

[profiles.default]
cmd = 'python3 -m http.server --bind 127.0.0.1 "$PORT"'
cwd = "."
port_env = "PORT"
EOF
rent init

init shows you exactly what it will run and waits for an explicit yes:

Enroll project 'hello' (runner: process)
  source:     /home/you/hello
  port block: 6200-6209

rentctl will run these commands on your behalf:
  [default]
    command: python3 -m http.server --bind 127.0.0.1 "$PORT"
    in:      /home/you/hello
    port via $PORT

Approve and enroll? [y/N] y

Your block will differ — blocks are drawn from 5100 upward, lowest free first. Then:

$ rent up hello
{
  "ok": true,
  "project": "hello",
  …
  "url": "http://localhost:6200",
  "port": 6200,
  …
  "lease_expires": "2026-09-28T15:50:21.327166-05:00",
  "already_running": false,
  "state": "running",
  "supervisor_pid": 24202,
  …
  "readiness": "answered"
}

$ rent ls                      # one row: hello, port 6200, "state": "running", "healthy": true
$ curl -sI http://localhost:6200/
HTTP/1.0 200 OK

$ rent down --all --cwd . --reason session-end    # what the SessionEnd hook runs
{
  "ok": true,
  …
  "downed": [ { "project": "hello", …, "port": 6200, "was_running": true,
                "stopped": null, "pending": true, "state": "stopping",
                "detail": "supervisor 24202 is completing cleanup; rent ls shows the outcome" } ]
}

$ curl -sI http://localhost:6200/ || echo gone
gone

(Output trimmed where marked ….) That last step is the whole product: in an enrolled Claude Code or Gemini CLI session you never type rent down — the session ending does. The hook doesn't wait for the server to die; it asks, and the environment's supervisor finishes the job (see How cleanup actually happens). rent down hello, typed by hand, waits and answers "stopped": true. rent events --summary afterwards shows the teardown and which cleanup layer did it.

If something doesn't behave, see Troubleshooting.

Enroll a project

A project describes itself in a rentctl.toml at its repo root (a devctl.toml left over from before the rename is still read, so nothing needs renaming to keep working):

[project]
name = "myapp"          # lowercase, no separators — it is used as a filename
runner = "process"

[profiles.default]
cmd = 'npm run dev -- --port "$PORT" --strictPort'
cwd = "frontend"        # repo-relative, never absolute
port_env = "PORT"       # rentctl sets this in the child's environment

Then, from the repo:

rent init

init shows you the exact command it will run, asks you to approve it, claims a block of ports for the project, registers the MCP server, installs the cleanup hooks (unless the Claude Code plugin already supplies them), and adds a short rule to CLAUDE.md / GEMINI.md telling agents to start servers through rentctl rather than by hand. Nobody else has to edit anything.

There is no port field. Ports are drawn when a server starts, not written down in a tracked file — so two checkouts of the same repo get different ports instead of fighting, and a config file can't hand out a number the allocator never heard of. Each project owns a contiguous block of 10 ports.

Use

rent up myapp              # start (or renew) — prints the URL and the port
rent down myapp            # stop it; waits up to 15 s (--wait SECONDS, --wait 0 = don't wait)
rent down --all --cwd .    # stop everything leased to this directory
rent ls                    # every environment on this machine, with its state
rent sweep                 # reconcile: stop what's expired or dead
rent events --summary      # what happened, and which cleanup layer did it
rent sync                  # re-approve a changed rentctl.toml
rent doctor                # are the shims, registry and hooks actually working?
rent report-kill myapp --note "…"   # "you killed something I was using"

report-kill exists because rentctl cannot tell, on its own, whether a teardown was unwanted — a kill you asked for and a kill you regret look identical from the inside. The report lands in the same append-only log as everything else and is matched to the teardown it disputes, so an unwanted kill becomes a fact on the record rather than an anecdote.

Leases default to 120 minutes and are capped at 480. rent up on a live lease renews it rather than starting a second server.

Which clients get automatic cleanup

"Expiry and sweep only" still guarantees the server dies — just at the end of its lease (120 minutes by default), not when you close the window.

Plugin-only installs need the CLI too. The plugin (Claude Code or Codex) calls the rent and rent-mcp you installed with uv tool install rentctl; it does not bundle them, and it deliberately does not fetch its own copy — a second, different rentctl acting on the same leases is worse than none. Without rent on PATH, session-end cleanup is off: every session then starts with a warning saying so and naming the install command. Install the package first, then run rent doctor, which reports whether each project's hooks come from the plugin, from settings.local.json, or from both.

From the MCP Registry, a client runs uvx rentctl@<version>: the rentctl executable is the MCP server, the same as rent-mcp (typed in a terminal it waits for a client on stdin). That gives you the tools with expiry-and-sweep cleanup only — the hooks come from the plugin or rent init. rent --version says which version you are running.

How cleanup actually happens

Every environment has its own supervisor: a small rentctl process that starts your command inside a POSIX session it owns and stays until that whole session — the command, its children, and anything they spawned — has been checked and found empty. The lease is written before the command starts, so there is no moment when something is running that rentctl has no record of.

Every stop, whatever asked for it, is the same: SIGTERM to every process in the session, SIGTERM to anything forked while it shuts down, SIGKILL to each process still there after 10 s, then a final scan. A child that ignores SIGTERM, or that outlived the shell that launched it, is stopped with the rest.

Four independent layers decide when, so no single failure leaves an orphan:

1. You ask — rent down.
2. The session ends — a SessionEnd hook releases that session's claim on everything leased to that directory. The server stops if no other session still holds a claim.
3. The lease expires — the supervisor starts the stop within about a second of the lease running out, even if the session died without running its hook.
4. The next sweep — rent sweep (which the hooks also run at session start) and rent ls clean up what the first three missed, including an environment whose supervisor was killed.

What rent down tells you is what the lease says, in one of three shapes:

• "stopped": true — the session was scanned empty and the lease removed.
• "stopped": false, "state": "cleanup_incomplete", "survivors": [...] — something could not be stopped (a child that switched user with sudo, say). The lease is kept, so the survivors stay named and the port stays out of the draw; the supervisor keeps retrying (5 s, 15 s, 60 s, then every minute), rent down retries at once, and rent up refuses with CLEANUP_INCOMPLETE until it clears.
• "stopped": null, "pending": true — the stop was accepted and is still running; rent ls shows how it ended. This is "ok": true: the supervisor finishes regardless.

rent down waits up to 15 s for the first two (--wait SECONDS; --wait 0 returns at once). The MCP tool env_down takes the same wait as wait_s — 15 s by default, 60 s at most.

Session end returns fast; cleanup finishes in the background. Claude Code gives a plugin's SessionEnd hook about 1.5 s. So the hook's rent down --all --reason session-end doesn't wait: it records a stop for every lease that no other session still holds, wakes each supervisor, and returns pending. The supervisors don't need the session to finish. A lease with no living supervisor is handed to a detached recovery process rather than stopped halfway.

A crashed session is cleaned up by layers 3 and 4, not 2. If the session dies without firing its hook, its server keeps running until the lease expires — up to the full lease length. Shorter leases (rent up myapp --lease-minutes 30) shorten that window. A sweep does not stop a live, unexpired lease; it cannot tell a crashed session from one that is still working.

If a supervisor is killed, recovery waits for the next command. The server keeps serving. The next rent ls, sweep, up or down notices, marks the lease unsupervised, and records supervisor_lost; it is not killed early. At its expiry the next of those commands stops it, and rent down stops it now. Nothing notices at the moment the supervisor dies, because nothing else is running to notice.

There is no daemon. There is one supervisor per live environment, and it exits once its environment is verified gone. State lives on disk and the OS process table is the source of truth, so there is no background service to babysit, and nothing to resurrect after a reboot.

What supervision covers, per platform

macOS. Every process that stays in the environment's session is found and stopped: orphans of a launch shell that exited, processes that ignore SIGTERM, processes that move into their own process group, children forked during shutdown. A process that calls setsid() — which is what daemonizing (double-fork plus setsid) does — leaves the session and is outside supervision. rentctl never signals it; if it holds the lease's port, the teardown reports it. When a command daemonizes during startup — its own session empties while a process outside it answers the port — rent up fails with UNSUPERVISABLE instead of reporting a start it cannot own. Run such servers in the foreground.

Linux. Each supervisor also makes itself a child subreaper (prctl(PR_SET_CHILD_SUBREAPER), no privileges needed), so orphaned descendants are reparented to it instead of to init. Every descendant of your command is captured, including a daemon that double-forks and calls setsid(). Signals to single processes go through a pidfd where the kernel has them. What still escapes is work that is not your command's descendant — handed to another manager such as systemd-run, a container runtime, an already-running tmux server, or at/cron — and the orphaned children of a process placed in another PID namespace with setns(2) (which needs CAP_SYS_ADMIN over that namespace): they go to that namespace's init. The capture also ends if the supervisor itself is killed. Where the subreaper is refused (some restricted containers), Linux gets the macOS guarantee.

rent doctor reports which one is in effect: supervision: session or supervision: session+subreaper. Neither is a sandbox — a command that sets out to escape supervision can.

Several sessions in one checkout share one server

A lease belongs to a (project, directory) pair, so two agent sessions in the same checkout share one server and one port. Each session that runs rent up holds its own expiring claim on it, and the lease lasts as long as its latest claim. A session's up renews only its own claim. rent ls and the up result list the claims, and shared_with names the other sessions.

When a session ends, its SessionEnd hook releases that session's claim. The server stops only when no other session still holds one. A session that never leased the server changes nothing when it ends. The MCP tool env_down also releases by default: it answers "stopped": false with held_by while others hold the server, and force: true stops it for everyone. rent down typed by a person always stops, and lists any other sessions' claims it overrode in overrode_claims.

This depends on knowing which session is asking. Claude Code hooks send the session id on stdin, and rentctl also reads DEVCTL_SESSION_ID, CLAUDE_CODE_SESSION_ID and GEMINI_SESSION_ID. rent doctor says which one it found. A caller with none of them is unknown, and every unknown caller shares one claim. A release can never remove another session's claim, so an unidentified session end leaves the server running until it expires. It never stops a server another session is using.

Separate git worktrees still give each session its own server, port and lease.

Where rentctl has to run: somewhere it can see processes

Supervision works by reading the process table: every process in a workload's session is found by its session id, and a stop is only reported as verified once that session is provably empty. So rentctl must run where it can list processes and read their session ids.

• Works: the MCP server launched by your agent host (Claude Code, for example), and rent typed in an ordinary terminal.
• Does not work: rent invoked from inside an agent's command sandbox that blocks process inspection. Codex's macOS sandbox is one (Operation not permitted (originated from sysctl())).

Where inspection is denied, rent up refuses with UNSUPPORTED_ENVIRONMENT and starts nothing. If inspection is lost after a server started, rentctl treats ownership as unknown: it keeps the lease, signals nothing, and never reports cleanup as verified. The record shows cleanup_incomplete with identity_ambiguous until a later attempt can see the session again. Denied inspection never reads as "no processes". The fix is to run rentctl from the host side, not to grant the sandbox wider privileges.

It won't kill things it doesn't own

Every lease records its supervisor's PID and start time, and the supervisor's PID is the environment's session id (a lease from 1.0.x uses its server's instead). A process is the environment's only if it is in that session (or, on Linux, descends from the supervisor), and each one's identity is re-checked immediately before it is signalled. If the session's PID has been recycled onto some unrelated process, nothing under it can be proved ours: the lease is kept, marked identity_ambiguous, and nothing is signalled — a stale lease can't get your database killed.

A listener inside an enrolled project's port block with no lease behind it is a squatter. What happens to it depends on the machine's enforcement mode:

• advisory (the default, and the only mode any command sets) — rent up routes around it, and rent ls / rent sweep report it. It is never signalled.
• strict — rent sweep sends each squatter SIGTERM, and reports what it killed. Since the session-start hook runs rent sweep, under strict that happens at every session start. Strict is set by the enforcement field in rentctl's machine-local registry; nothing turns it on for you. See Development machines only before you do.

When it genuinely cannot tell whether a port is in use — no usable probe on the host — it says so, rather than reporting the port as free. "No squatters found" means something looked.

What it can see is limited to what you can see. The port probe (lsof, or psutil on Linux) runs as your user, and an unprivileged probe can miss sockets owned by other users. So "free" means free as far as this user can see. A real collision still surfaces: the server's own bind() fails, and rent up reports the failed start (with the log tail) instead of writing a lease.

Security: what you are trusting

Read this part. rentctl runs a command out of a config file in your repo.

That is arbitrary code execution, and no tool can make it not be. If you can run npm run dev, you can run anything. What rentctl guarantees is narrower and more useful: it adds no silent path to it.

• The command from rentctl.toml is shown to you and approved once, explicitly, at rent init.
• On approval it is copied into rentctl's own registry along with a hash of the execution-determining fields: runner, cmd, cwd and port_env.
• If the repo's rentctl.toml later changes any of them, the next start stops (CMD_CHANGED) and shows you a diff of approved-versus-current. It does not run the new command. You re-approve with rent sync or you don't.

The hash deliberately covers only the fields that determine execution, not the whole file — hashing everything trains you to click through re-approvals for comment edits, which defeats the point.

Approval pins the command, not the code it runs. npm run dev is the same string whatever package.json says dev means. An edit to a package.json script, a Makefile, or the application code itself changes what actually executes without tripping CMD_CHANGED. The pin stops a changed rentctl.toml from quietly running something new; it is not a review of the repo. Treat pulling someone else's branch the way you already would before running its dev server by hand.

Consequences worth being explicit about:

• git pull cannot change the approved command. It can change the file, and it can change the code that command runs; it cannot change which command rentctl runs.
• A repo cannot walk rentctl out of its own directory. cwd is repo-relative and rejected if it is absolute, contains .., or symlinks outside the repo. Project names are filename-safe or refused.
• Non-interactive enrollment is explicit. CI passes --trust-repo, which is recorded as trust-on-first-use rather than being the quiet default.
• rentctl only manages what you enrolled. Test-framework servers (pytest fixtures, Playwright's webServer) own their own lifecycle and use ephemeral ports; rentctl never touches them.

To report a vulnerability, see SECURITY.md.

Development machines only

Install this on machines where dev servers are meant to be disposable. Not on a host running anything you would mind losing.

A default install is safe: enforcement is advisory, and rentctl only scans the port blocks of projects you enrolled. Nothing else on the machine is examined and nothing unenrolled is ever signalled.

But rentctl's whole job is killing processes that outlive a session, and strict enforcement exists to make that unavoidable. A tool built to reap servers you forgot about is the wrong tool to arm on a host serving traffic — there, the servers outliving their session are supposed to. Keep it on development machines.

Troubleshooting

Agent-client problems (missing tools, hooks, approval, cleanup that did not happen): docs/troubleshooting.md. Which clients and surfaces were tested, and how: docs/integrations.md.

• rent doctor checks that the rent shim runs, the registry loads, and each enrolled project's hooks are wired, and says which supervision level this host gets and where it found this session's id (session-identity). If rent itself is missing, the same check runs as python3 -m rentctl.doctor.
• Server logs are in ~/.local/state/devctl/logs/<project>-<timestamp>.log (under $XDG_STATE_HOME if set). A failed rent up includes the log's tail in its output.
• What happened, and why: rent events lists every start and teardown with the layer that did it; the raw log is ~/.local/state/devctl/events.jsonl. A teardown's down event says whether the stop was verified and whether it needed SIGKILL ("escalated": true). stop_requested means a stop was asked for (for example by the session-end hook) and is not itself a teardown. Neither is claim_released: a session let go of a server that others still hold.
• rent ls shows each lease's state and whether its supervisor is alive:
  • stopping or "pending": true — a stop is under way; look again in a few seconds.
  • unsupervised — its supervisor died. The server is still yours and still serving; it is stopped at expiry by the next ls/sweep/up/down, or now by rent down. rent up will not renew it. (A lease started by 1.0.x also reads unsupervised, with "legacy": true; rent up does renew that one.)
  • cleanup_incomplete with survivors — those PIDs would not die. Find out why (a different user? stuck in the kernel?) before reusing the port; rent down retries.
• UNSUPERVISABLE from rent up — the command daemonized, so its server left the session rentctl supervises. Run it in the foreground. The stray server is left alone; stop it yourself.
• The supervisor notes what it did in the server's log, on lines prefixed [rentctl supervisor <pid>].
• The registry of enrolled projects and approved commands is ~/.config/devctl/registry.json. It is rentctl's own record — change it with rent init / rent sync, not by hand.

(The directories say devctl, the project's former name. That is deliberate — renaming them would orphan every live lease.)

Known gaps

Stated plainly, because a tool making safety claims should be honest about its edges:

• The approval pin covers the command, not the code — see Security.
• Sessions in one checkout share one server — see above. A session that rentctl cannot identify releases nothing when it ends, so its server lives until the lease expires.
• Crash cleanup waits for expiry — a session that dies without its hook leaves its server up until the lease runs out.
• Recovery waits for the next command — if a supervisor is killed, nothing acts until the next rent ls/sweep/up/down.
• Daemonizing commands are not supervised on macOS, and on Linux work handed to another process manager is not — see What supervision covers.
• Only Claude Code, Codex (with its hooks trusted) and Gemini CLI get session-end hooks. Other clients get expiry and sweep. Cloud agent sessions (claude.ai/code cloud, Codex Cloud) are not supported: they cannot reach your machine's processes.
• runner = "compose" is designed but not implemented. Asking for it fails with a clear error rather than doing nothing.
• The only environment beyond the port is port_env. Anything else a server needs has to ride inside cmd today.
• Windows: see Install. Not supported, not claimed.

Contributing

See CONTRIBUTING.md.

A note on the comments in the source

The source cites its own design decisions — ADR-0008, WI-0040, spec §10. Those refer to this project's design log, which is kept privately; the reasoning around each citation is written out where it is cited, so nothing is missing if you can't follow the pointer.

License

Apache License 2.0 — see LICENSE and NOTICE.

Copyright 2026 Michael Drake.