Rook Environment and Secrets
Profiles contain references and operational descriptions. Secret values remain on the machine running Rook and are never included in project synchronization.
Manage Local Values
Verifiedrook env list
rook env set '{"API_KEY":"sk-...","BASE_URL":"https://staging.example.com"}'
rook env show API_KEY
rook env rm API_KEY
| Command | Behavior |
|---|---|
env list | Lists configured names with masked values. It is the default subcommand. |
env set | Stores one or more key-value pairs from a JSON object. |
env show | Prints one value in full; take care with terminals and logs. |
env rm | Removes the local value. |
Values are stored below the global Rook home, outside the repository, and scoped to the workspace’s absolute path. Shell-exported values override stored values. A generated hook reads process.env.API_KEY; its profile lists the variable name and purpose.
Profile Declaration
Verifiedenv:
- variable: API_KEY
purpose: read-only token for the staging support API
- variable: BASE_URL
purpose: environment to test
The purpose field should state the authority behind the value. A variable name alone does not tell a reviewer whether the credential can only read status or can move money.
Before spending a run, Rook checks that every value declared by the profile is available. This prevents a large suite from failing after many paid invocations because a single token was never configured.
Global and Workspace State
| Path | Contains |
|---|---|
~/.testmuai/rook/ | Credentials, environment values, terminal history, logs, installed versions, and machine-specific session state. The directory uses mode 0700. |
<repo>/.testmuai/rook/ | Projects, agents, features, scenarios, profiles, hook scripts, runs, and evidence intended to be reviewable and committable. |
Shared Authentication
Stored OAuth authentication is shared by processes using the same Rook home, profile, and environment:
- several terminals share one sign-in;
- logout in one terminal is observed by the others;
- login restores access for all of them;
- token renewal is serialized so concurrent terminals converge on the same refreshed token;
- an interrupted run is saved where it stopped and is not automatically resumed after login.
For unattended use, inject LT_USERNAME and LT_ACCESS_KEY through your secret manager. Rook uses this pair ahead of stored OAuth credentials. A different ROOK_HOME does not isolate credentials already exported in the shell.
Public packages use ROOK_ENV=prod for the service behind the hosted Web UI. Set the service environment before authentication and project operations. This does not change the endpoint your target-agent hook calls.
Isolate Rook State
Set ROOK_HOME when a process should not share credentials or local values:
export ROOK_HOME="$RUNNER_TEMP/rook"
rook auth status
Common reasons include:
- a CI job with its own account;
- separate staging and production identities;
- a temporary test environment;
- troubleshooting without changing the primary workstation state.
Hook Variables Are Supplied by Rook
Variables such as ROOK_HOOK, ROOK_RUN_ID, ROOK_SCENARIO_ID, ROOK_SESSION, ROOK_TURN, ROOK_CONVERSATION, ROOK_STATE_DIR, ROOK_WORKSPACE, ROOK_PROJECT, and ROOK_AGENT are runtime context for hook scripts. Rook's values take precedence; setting them manually does not substitute for running the hook in a real lifecycle.
Secret Handling Checklist
- Keep values out of profile YAML and source control.
- Give profiles the least-privileged credentials needed for the scenarios.
- Do not use
env showin shared terminals or CI logs. - Keep
.testmuai/rook/.gitignoreentries intact for credentials and machine-only state. - Review MCP commands and headers before approval.
- Use a dedicated
ROOK_HOMEfor unattended automation.
UI Access and Evidence Privacy
The local UI (rook ui --local) reads workspace evidence on loopback without a hosted browser login. The hosted Web UI (rook ui) requires browser access to the chosen environment and project; its sign-in is separate from CLI credentials. ROOK_ENV selects the hosted environment, not a different target-agent endpoint or a remote data source for the local viewer.
Requests, responses, and artifacts in either UI can contain sensitive target data even when profile YAML contains only variable references. Review evidence before upload or sharing; never expose the local server as a public report. See both UI access paths.
Local UI: Identify the Hook to Inspect
Open the agent's profiles panel to identify its invocation script. Use the CLI to inspect the profile's required variable names and manage their values. There is no local UI secret editor; this screenshot identifies the profile, not its stored credentials.
Hosted Web UI: Review Environment Requirements
Open Summary → Profiles → View Full Spec. Profile YAML records environment requirements, not the secret store. This sample has env: [] because its local test endpoint needs no token; it is not an example of configuring authenticated access.
Chat with Us