Provide private credentials to the current session¶

Use the private credential entry to supply a database password, repository Token, or SSH private key. Ordinary shell commands in the current session can use them; they are not submitted to the model as chat messages.

obscli¶

Enter /credentials in chat. The menu offers only Write and Delete and automatically binds to the session's single Agent. With Write, fill in Key and Value in the same private form. Tab switches fields; Enter submits. Text is the default and Value is always hidden. Writing an existing name asks for overwrite confirmation.

While waiting for the service response, press Ctrl+C or Esc twice to cancel the wait. Input and pasted text during the wait are discarded and do not enter chat drafts, logs, or caches. Canceling a write already sent does not undo the server operation; check the result before retrying.

Use the same form for files: Ctrl+T switches to file and clears Value. Enter an @ path in Value. Absolute, ~/, and relative paths are supported. Arrow keys select, Tab completes, and Shift+Tab returns to Key. Completion includes hidden files within the current directory prefix without recursive searching. Confirm the selected path and size before upload. obscli does not convert pasted text into a file.

There is no credential list or refresh in the form. Ask the Agent in ordinary chat to list credential names and types; values are not returned. Delete requires the exact name and confirmation. On failure, input stays in the form for manual retry or Edit key and value. Canceling, closing, or succeeding clears it. Built-in TUI menus, prompts, and errors use English; user content and model output remain unchanged.

Add git-rg Tokens¶

For read-only tasks, prefer a low-permission GITRG_TOKEN; provide GITRG_WRITE_TOKEN to create Draft PR/MRs. From git-rg v0.6.0, a write Token with both reading and publication permissions can handle the whole editing workflow. With both Tokens, reads prefer the read Token. In v0.5.0, private-repository reads and dry-run still require a separate read Token.

Create GitHub Tokens through Fine-grained personal access tokens. In GitLab, open Settings > Access tokens in the target project to create a project access token.

Add GitHub Workflows: Read and write only when the change plan actually modifies .github/workflows/. GitLab write_repository covers Git repository access and cannot replace the REST API api scope needed for commits and MRs. Branch protections, organization policies, or self-managed instance policies may still reject operations. Prefer allowing a dedicated identity to create unprotected source branches instead of raising its role to Maintainer or Owner.

Use the shortest practical expiry and limit access to the one repository or project needed. GitHub classic PAT repo and unscoped GitLab personal access tokens grant broader access; use them only when platform versions or organization policies prevent repository-scoped Tokens. If GitLab project access tokens are unavailable, prefer a dedicated bot account belonging only to the target project, with a personal access token using the same scopes and minimum role. Do not reuse an everyday account with access to multiple projects.

For a two-Token configuration in the current obscli chat:

1. Enter /credentials and select Write.
2. Set Key to GITRG_TOKEN, paste the read-only Token into Value, and press Enter.
3. Enter /credentials again and select Write.
4. Set Key to GITRG_WRITE_TOKEN, paste the separate write Token into Value, and press Enter.
5. Ask the Agent to list credential names and types, and confirm both names exist. Do not ask it to show values.

For single-write-Token editing supported from v0.6.0, add only GITRG_WRITE_TOKEN; read-only tasks need only GITRG_TOKEN. Agent read commands use --auth env and clear GITHUB_TOKEN, GH_TOKEN, and GITLAB_TOKEN in their subprocess. With those provider Tokens removed, reads select GITRG_TOKEN before GITRG_WRITE_TOKEN. Rejected Tokens do not trigger identity-switch retries.

dry-run does not change remote data but may read using a write Token. For anonymous access to public repositories, clear both git-rg Tokens and all three provider Tokens in the command subprocess. Omitting GITRG_TOKEN alone does not guarantee anonymity. Each publication still needs explicit user authorization and --enable-write; merely supplying a write Token does not authorize publication. Never put Tokens in chat, repository URLs, change plans, command arguments, or repository files. Submit credentials again after closing the session, restarting the Agent, or disconnecting.

These standalone commands remain available for automation and compatibility. IDs and names are examples; never place secret values on the command line. Text values are entered through hidden input. File contents are stored privately on the Agent; the variable contains their local path. list returns only names and types.

obscli session credential put --workspace-uuid WS --session-uuid SESSION --agent-uuid AGENT
obscli session credential put --workspace-uuid WS --session-uuid SESSION --agent-uuid AGENT --name GITRG_TOKEN
obscli session credential put --workspace-uuid WS --session-uuid SESSION --agent-uuid AGENT --name GITRG_WRITE_TOKEN
obscli session credential put --workspace-uuid WS --session-uuid SESSION --agent-uuid AGENT --name SSH_KEY_FILE --file ./id_ed25519
obscli session credential list --workspace-uuid WS --session-uuid SESSION --agent-uuid AGENT
obscli session credential delete --workspace-uuid WS --session-uuid SESSION --agent-uuid AGENT --name GITRG_TOKEN

Use --stdin to read text from a safe input source. Bytes, including trailing newlines, are preserved. Do not put secret literals in commands or arguments: they may enter shell history.

One-shot task import¶

obscli run --import-credential /secure/credentials.json imports credentials before sending the task. Example JSON and invocation:

{
  "kv": {"DB_PASSWORD": "your-password", "GITRG_TOKEN": "your-read-token", "GITRG_WRITE_TOKEN": "your-write-token"},
  "files": {"SSH_KEY_FILE": "./id_ed25519"}
}

obscli run --agent-uuid "$AGENT" \
  --import-credential /secure/credentials.json \
  --prompt '使用 DB_PASSWORD 和 SSH_KEY_FILE 执行任务'

Only JSON is supported. Either kv or files may be omitted. Relative file paths resolve against the JSON directory; $VARIABLE and ~ are not expanded and shell code is not executed. Names must be unique across both sections; values must be nonempty strings and files must be readable regular files. The JSON file is limited to 8 MiB, with at most 64 names, 256 KiB per item, and 8 MiB of decoded credentials in total.

The client validates all input, creates an empty session, uploads credentials, and waits for every confirmation before sending the prompt. An upload failure or unconfirmed result prevents the task from starting and is not retried automatically. The client attempts to close the session and reports cleanup failures. Original JSON and local files are kept; manage them yourself, preferably with 0600 permissions. Only the import path appears in the command line; credential contents do not enter chat, the model, or application logs.

Uploading does not start a task automatically. After confirmation, describe the intended use in ordinary chat and ask to continue. The next normal model call receives only names and types and uses ordinary shell syntax:

PGPASSWORD="$DB_PASSWORD" psql -h db.example.com -U readonly
git-rg --auth env -F 'timeout' github:OWNER/REPO
ssh -i "$SSH_KEY_FILE" deploy@host

Lifetime and permissions¶

• Writing the same name replaces its value for future commands. Already-running commands may retain the old value.
• Users allowed to send messages in the session can manage its credentials. The session binds to one Agent; other sessions do not inherit credentials.
• Text lives in Agent memory. File directories use mode 0700, files use 0600, and both belong to the Agent account. File credentials require Unix permission semantics: Windows Agents reject them, but Windows clients can upload to Unix Agents.
• Closing the session or restarting the Agent revokes credentials. Files left by an abnormal exit are cleaned on the next startup; old values are not restored.
• Disconnecting the Agent from Beak also revokes credentials. Resubmit after reconnecting; reopening a session does not recover them.
• Each session allows at most 64 names and 256 KiB per item. Cumulative submissions are limited to 8 MiB. Deletion does not reset the counter. Redaction fragments are no longer created.
• Offline Agents fail immediately without queueing. A confirmation timeout means the result is unknown: inspect the name list or resubmit the same name instead of assuming nothing was saved.
• When a command carrying credentials returns, background child processes in its process group are cleaned up. Do not use this mechanism to start long-running services.

Ordinary commands receive session variables and file paths. Existing shell approval rules still apply. Credentials printed by tools enter history, logs, traces, and the model as original content without string replacement. File deletion does not protect against disk forensics, snapshots, or backups. The same OS account and administrators are outside the file-permission isolation boundary.

Credentials are injected only into command subprocesses of their owning session, without changing the Agent's global environment. Other sessions do not inherit them automatically, but sessions on the same Agent usually share an OS account. An unrestricted shell in another session may read files owned by that account; process-environment access depends on OS permissions. Session scoping does not replace separate accounts, containers, or OS sandboxes.

Web entry¶

The Web entry requires a matching frontend version and deployment acceptance. Updating only Beak and the Agent does not provide it automatically.

In the current session, select the credentials entry. The dialog offers write, replace, and delete, without a list, refresh, or Agent selector. A new task first creates an empty session without invoking the model, and later messages reuse it.

Text input is hidden. Files can be uploaded or created from pasted multiline content, preserving whitespace and newlines. Overwrites and deletions require confirmation. Failed input stays only in the current form's memory for manual retry; closing, switching sessions, or succeeding clears it. Users do not need to write structured data.

Beak forwards credentials briefly in memory. Deployments must avoid capturing these request bodies in reverse proxies, APM, or Redis command debugging. Use HTTPS/WSS in production.