devctl CLI: native terminal attach and shell completion
Attach to a session's terminal: `devctl remote-terminal`
devctl remote-terminal <session> (alias devctl attach-native) puts your terminal straight into the
session's tmux inside its container. The usual devctl session attach goes through the Core terminal
relay; this command runs the tmux client yourself, with docker exec, over SSH when the Host is
remote:
# Remote Host (the Host ID is its SSH alias)
ssh -t build-host 'docker exec -it -u 20123:19999 devctl-example-main tmux -S /var/lib/devctl/session/homes/<id>/tmux/tmux-20123/default attach -t <id>'
# Local Docker Desktop Host
docker exec -it -u 20123:19999 devctl-example-main tmux -S /var/lib/devctl/session/homes/<id>/tmux/tmux-20123/default attach -t <id>
<session> can be a session ID, a session name or display name, or project/name. A name that
matches more than one session is refused, and the error lists the project/name (id) forms to use
instead.
| Option | Effect |
|---|---|
| (none) | Check that the Host is reachable, then run the command so you land in the terminal |
--print |
Print the command instead of running it |
--read-only |
Attach with tmux attach -r |
--json |
Print the structured target: Host, connection, container, UID, GID, socket, tmux target |
--ssh TARGET |
Reach the Host through another SSH alias or user@address instead of its Host ID |
--local |
Run docker exec on this machine (use this when the Host is this machine's Docker) |
--list |
List the sessions you can attach to (project/name, status, ID) |
Detach with the session's tmux detach key: Ctrl+] in managed sessions, or Ctrl+b d.
Where the target comes from
Nothing in the command is guessed by the CLI:
- Core resolves the reference among the sessions you can reach. The command is issued only to the
session's owner, the canonical operator, or a user with a control share. A view share
gets a read-only attach (
-r). Everyone else gets "Session not found". - Core asks the session's Host for the location. The Host takes the session's HOME from its
authoritative runtime key: the session UUID for new sessions, and the original name for legacy
ones. It then looks inside the running container for the tmux socket under that HOME that answers
for the exact tmux session. It returns the socket only when exactly one socket answers and the
socket's owner is the UID the session's process runs as. Task-container (Control Room pool)
sessions have their own per-slot UID; the Host reports it the same way. The
docker execuser is that UID with the shared session group (19999). - Every request is recorded in the audit log as
session.terminal-command, both issued and refused ones, with the access level and mode.
The command still needs your own SSH access to the Host, and permission to run docker there, or a
local Docker Desktop for the local-docker Host. Core's check decides who receives the command and
puts it on the audit record. It is not a sandbox: anyone who can already run docker exec on a Host
can reach every container there. --read-only and view shares therefore only make the tmux client
read-only.
Errors and next steps
| Message | Next step |
|---|---|
Session … is exited; start it first |
devctl session resume-id <id>, or thaw a frozen session |
not reachable over SSH as "<alias>" |
Make ssh <alias> work without a password prompt (add a Host <alias> entry to ~/.ssh/config), or pass --ssh |
Docker there cannot see the … container |
Check that the SSH user can run docker ps on the Host, and that the session is still running |
Local Docker cannot see … |
Start Docker Desktop, or pass --ssh <alias> if the Host is remote |
cannot report session terminals yet |
Upgrade the Host agent: devctl install-host <alias> --upgrade |
tmux server is not running |
The container runs but the session's tmux is gone: resume the session |
This session runs directly on its Host |
Host-mode sessions have no container; use devctl session attach-id <id> |
The reachability check is ssh -o BatchMode=yes -o ConnectTimeout=8 <host> docker inspect …. Run
it yourself with --print if you need to debug the connection.
MCP
get_session_terminal_command is an entry of the shared operation registry
(packages/contracts/src/operation-tool-definitions.ts), so the operator MCP server and Control
Room sessions get the same typed tool, paired with devctl remote-terminal. It takes session and
an optional readOnly, and calls POST /v1/session-terminal-command with the same authorization
and audit as the CLI. The structured result has sessionId, hostId, connection, sshTarget,
container (containerId, containerName, uid, gid, socket, target, taskSlot),
access, readOnly, and the default command and argv. The tool never runs the command.
--ssh and --local are CLI-only, because they depend on the operator's own machine. When a
Host ID is not a usable SSH alias, sshTarget is null and command is the docker exec part to
run on that Host.
Shell completion: `devctl completion bash|zsh|fish`
devctl completion <shell> prints a completion script. The command tree (commands, subcommands,
aliases and flags) is generated from the CLI's command registry (apps/cli/src/command-registry.ts)
together with the commands derived from the shared operation registry under the roots that the
devctl wrapper routes.
A test fails when the registry misses a command that the CLI or the devctl wrapper dispatches.
While you type, the script calls the hidden devctl __complete <words…> for live values: sessions
(project/name; IDs once you type an ID prefix), Projects, Hosts (after --ssh and --host) and
accounts. That call:
- asks Core's
GET /v1/completion-candidates, which returns only the sessions, Projects, Hosts and accounts you can reach, with a 1.5 s deadline; - caches the names (no tokens, no session content) for 15 s in a private temporary file;
- never starts or updates the stack.
When Core or the stack is unreachable, __complete returns only static values, or nothing at all.
The script then falls back to the static tree embedded in it.
zsh (macOS)
The installer does not change shell startup files, so add completion yourself:
mkdir -p ~/.zsh/completions
devctl completion zsh > ~/.zsh/completions/_devctl
In ~/.zshrc, before any existing compinit line:
fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit
Open a new shell, or run exec zsh. If you call devctl from the checkout as ./devctl, zsh matches
the completion by the command's base name. You can also put the checkout's devctl on your PATH
(for example ln -s "$PWD/devctl" /usr/local/bin/devctl).
bash
mkdir -p ~/.local/share/bash-completion/completions
devctl completion bash > ~/.local/share/bash-completion/completions/devctl
# or, in ~/.bashrc:
source <(devctl completion bash)
fish
devctl completion fish > ~/.config/fish/completions/devctl.fish
Regenerate the script after upgrading devctl, so that new commands appear.