Frequently asked questions
Short answers, each drawn from the README and the docs. For anything not covered here, see the usage guide.
Where can the files be?
In an S3 bucket (or an S3-compatible server), on an SFTP server, or in a local directory of the console’s machine. Each profile names one source, and keys outside its prefix are refused. Source profiles.
Which operating systems?
The console needs Linux, since Landlock and seccomp sandbox the plugins. The agent side (CLI and MCP server) also runs on macOS. Binaries are built for amd64 and arm64. Requirements.
Which AI agents does it work with?
Claude Code, Codex, Cursor and Gemini CLI, wired by lockfile init. An agent talks to the console through the MCP server (lockfile mcp, seven tools) or through the lockfile CLI from a shell; every command takes --json.
What exactly does the agent see?
Per plugin: 1, 0, or no answer (result: null with plugin_error). Around that, only items from closed lists: random handles and plan ids, plugin metadata from signed manifests, profile names, approval outcomes, refusal codes and the console state. Never the file’s bytes, size, type, hash, name or a listing. The exhaustive list.
How does the agent know which file to ask about?
It must be given the exact key, by you or by a ticket. There is no listing and no stat: key names and sizes are file information.
Is “no answer” the same as 0?
No. plugin_error means the plugin failed on the file (a crash, a timeout, a wrong output) and gave no answer. Treat it as unknown. The precise cause is in the audit, which only the console account reads.
Can the agent approve its own plans, or turn approval off?
No. Approval comes only from the console’s terminal, in a separate account and session; no socket method approves, installs a plugin or loosens the policy. Auto mode switches only from the console’s keyboard, never on production and never for unofficial plugins.
Can a plugin answer any question, like “is the amount above 10 000”?
The official marketplace refuses such questions at review: questions are about format, structure, integrity or rendering, never about what the content means or says, and plugins take no parameters. An unofficial marketplace may not apply the same review, which is why its plugins are flagged in red and never auto-approved. Plugins.
Could many questions add up to reading the file?
Each answer is one bit, and max_plugins_per_handle (16 by default) caps the answers about one fetched file. Every approval screen states how many answers the plan reveals, so you see the total before you approve.
Can the agent learn something from how long a plugin takes?
Results leave the console only at the next multiple of answer_quantum (5 s by default) after the run started. A plan that takes longer than one quantum still shows that it took longer.
Where does the file go, and for how long?
Into a random 0700 workspace in the console account, deleted on lockfile release, after handle_ttl (30 minutes by default), on console exit, and swept at start. Deletion is an unlink, not a secure erase.
What is logged?
The audit log, in the console account only, records each fetch (key, size, sha256, cause of a failure) and each plugin’s precise outcome, with the stderr byte count. Never file bytes. Read it with lockfile audit.
Can I write my own plugin?
Yes: a plugin reads the file from fd 3 and writes 1 or 0. Submit it to the official marketplace, or publish your own marketplace signed by your CI identity. Write a plugin.
What does v0.2 not do yet?
The plugin sandbox is not yet complete: v0.2.1 denies SysV IPC and message queues and requires /proc mounted with hidepid=invisible (details). There is no onboarding wizard (setup), no macOS console, and no public-key trust roots for unofficial marketplaces (keyless signers only). These are on the roadmap, not in the release.
How does it relate to locksql and lockmq?
They are siblings built on the same idea and the same framework, lockkit: locksql for databases, lockmq for message queues, lockfile for files. Each runs its own console in its own account.