FAQ

Frequently asked questions

Short answers, each drawn from the README and the docs. For anything not covered here, see the usage guide.

Which servers can it reach?

Any host with an SSH server and a POSIX login shell. Each profile is one host:port and one login, by key or password; the console’s container can reach only the profiles’ hosts. Bastions (ProxyJump) are out of scope. SSH host profiles.

Which AI agents does it work with?

Any MCP client, run confined (in a container, as lea runs agents): the console refuses an agent that does not report running confined, unless a non-production profile sets unconfined = true. lockssh init wires Claude Code, Codex, Cursor and Gemini CLI. An agent talks to the console through the MCP server (lockssh mcp, five tools) or the lockssh CLI; every client command takes --json.

Which commands run without asking me?

Only those an allow rule of the policy you approved matches, such as systemctl status * or df -h. Anything else is refused, or, on a profile with exec = true, waits for your decision on a ticket and then runs once. What runs, what waits.

Can the agent approve its own commands, or widen the rules?

No. Tickets are decided in lox run, outside the agent, and signed by the hub. An agent that edits .lockssh/config.toml loosens nothing until you approve the change in the console; lockssh_request_change only queues it for you.

Can the agent slip a second command into the arguments?

No. The agent sends an argv, and the console quotes every argument: ;, |, &&, $(...) and backquotes reach the program as plain text. Globs in allow rules never match an option you did not write or a .. segment. No shell, no climbing, no options.

Is every allow rule safe?

No. A rule allows a program with arguments; it cannot know what the program does with them. find -exec, awk, sh -c, sudo, editors and pagers turn a glob into a shell. Allow them only with literal arguments; the policy review warns on such a rule.

What exactly does the agent see?

The exit status (or the signal, or timed_out), stdout and stderr capped and masked, the truncation flags, the duration and the count of masked values by kind. Never the key, the password or the clear output, unless you switched clear output on and decided its ticket.

What is masked, and what is not?

Cards, emails, IBANs, public IP addresses and phone numbers become keyed pseudonyms, stable for one console run; secrets become ⟦secret⟧. Person names, postal addresses and free text are not: prefer commands whose output you know. What is not masked.

How are host keys checked?

A key the console has never seen is shown in its terminal and trusted only on your answer (on production, the last 8 characters of its fingerprint, typed). With a known_hosts file in the profile, an unknown key is refused. A changed key is always refused, and no ticket can trust one.

Can it copy files, forward ports or open a shell?

No. lockssh opens one session per command, with no PTY, no stdin, no port, agent or X11 forwarding and no subsystem, so no scp or sftp. To read files in a gated way, lockfile answers questions about them over SFTP.

What about long-running commands like tail -f?

Out of scope. Output is masked whole when the command ends, and each command is killed after request_timeout (30 seconds by default, 10 minutes at most).

What changes on a production profile?

A command outside the allow list always waits for a human, a root login is refused, and a new host key is trusted only with its fingerprint typed. Production profiles.

What is logged?

Every request, refusal, decision and run, in an append-only, hash-chained audit log in the console account, with the command masked. The output is never logged.

Can I install it today?

v0.3.0 is released, and its launcher installs with install.sh. The console runs under lox run only, which takes lockhub’s lox v0.12.0 or later. It installs with Homebrew too: brew install davidgodefroid/tap/lockfamily installs it with lox. Where things stand.

How does it relate to the other Locks?

They are siblings in the Lock Family, built on the same idea and the same Go core, lockkit. Each runs its own console in its own account.

locksql covers SQL databases, lockmq RabbitMQ, lockfile files, lockhttp outbound HTTP(S) and locklog logs. One hub, lockhub, approves for all of them.