Ai Keeper/Guides/Security, operations, and recovery
← All workflows
Collection 12 · Keep it trustworthy

Security, operations, and recovery

Diagnose failures, inspect traffic and logs, watch resource pressure, manage sessions and usage, back up state, secure secrets, review audits, and customize operator controls.

14 workflowsBeginner-first

Find one workflow

Filter this collection by name, outcome, provider, engine, channel, mode, or command.

14 shown
Workflow 01

Run diagnostics and Doctor

Get a structured readiness report before changing configuration.

Beginner5–10 minResult · Every failure has a specific next action✓ Source-audited workflow
System Health showing Doctor controls and the passed, warning, failed, and skipped diagnostic totals.
Read warnings and failures before exporting a report or changing dependencies.
Before you start
  • Ai Keeper is open.

  1. Open System > Health and run Diagnostics, then Doctor when available.

  2. Start with red blocking items, then amber warnings. Expand each item to read its affected feature and remediation.

  3. Use the provided navigation/fix action to reach Engines, Connection, Storage, Secrets, or the affected instance.

  4. After fixing one root cause, rerun the focused check before moving to the next.

You are done when
Blocking checks are green or intentionally acknowledged, and you can name the remaining warnings and their impact.
If something looks wrong
Fixing symptoms randomlyUse the diagnostic's destination and evidence. Changing unrelated engine flags can create a second problem.
Workflow 02

Trace a failed or slow request

Find the exact proxy request, route, transforms, latency, and response instead of guessing.

Intermediate5–15 minResult · Failure is localized to client, proxy, route, or model✓ Source-audited workflow
System Requests showing three successful API calls with endpoint, port, status, latency, token, and model details.
The populated traffic log makes latency and route differences visible before you select a row for deeper inspection.
Before you start
  • A reproducible request and approximate time/model.

  1. Reproduce once, then immediately open System > Requests > Traffic.

  2. Filter by time, model, status, or endpoint and select the request.

  3. Open Inspector to review public model, chosen target, status, timing, request shape, transforms, and safe headers.

  4. Correlate its timestamp/request ID with Runtime or App logs.

  5. Fix the narrow cause and repeat the exact request once.

You are done when
The repeated request succeeds or produces a more specific controlled error, and you can identify which layer owns it.
If something looks wrong
Secrets in copied logsRedact credentials and private payloads before sharing diagnostics.
429 assumed to be model failureInspect rate-limit, concurrency, queue, and failover evidence first.
Workflow 03

Read runtime, app, and crash logs

Use the right log section and correlate one incident without drowning in unrelated history.

Intermediate5–15 minResult · The relevant error and surrounding events are identified✓ Source-audited workflow
System Logs showing Runtime Logs, Crash Logs, and the instance or app-log selector.
Choose the failing instance or App Log before searching; an empty view means no matching events are loaded.
Before you start
  • The approximate incident time and affected feature.

  1. Open System > Logs and choose Runtime for engine output, App for application events, or Crash for terminated processes.

  2. Filter around the incident time, model/instance, or category.

  3. Read several events before and after the first error. The final line is often only a consequence.

  4. Use request ID, process ID, instance ID, or timestamp to correlate with Requests/Monitor.

  5. Export only the focused evidence if support needs it.

You are done when
You have a short evidence chain from initiating action to first causal error to user-visible result.
If something looks wrong
Only last error copiedInclude enough preceding context to show what command/model/request was active.
Crash log from an old buildConfirm timestamp and app version before treating it as current.
Workflow 04

Find and safely end a heavy process

Use Monitor to see app/process-family memory and CPU before terminating anything.

Beginner3–10 minResult · Pressure drops and the intended process stops✓ Source-audited workflow
Current Monitor hub filtered to the Ai Keeper process family with memory history and child-process details.
Filter before acting, select the exact app family or child process, and inspect the history and current resource use before ending anything.
Before you start
  • A machine under pressure or a process you intend to stop.

  1. Open Monitor and sort/scan by memory or CPU.

  2. Expand the process family to confirm child process, model/engine identity, and ownership.

  3. Prefer stopping a managed model from Runtime > Instances. Use Monitor's safe termination when the normal control cannot respond.

  4. Confirm the exact process and choose the safe end action. Avoid force termination unless ordinary termination fails.

  5. Wait for memory/CPU and instance state to refresh.

You are done when
The intended process disappears, pressure falls, and unrelated app processes remain healthy.
If something looks wrong
Killed an external processMonitor can show non-Ai Keeper families. Confirm ownership and target before ending anything.
Instance still says runningRefresh/Diagnose the instance; external termination can leave state stale until readiness checks reconcile.
Workflow 05

Review token, request, and cost usage

Find which models, providers, or workflows consume the most capacity.

Beginner5–10 minResult · One actionable usage finding✓ Source-audited workflow
System Usage and Cost Dashboard showing request, token, budget, provider, model, and recent-request sections.
Set a budget only after confirming which providers and models contribute to the totals.
Before you start
  • Enough recorded activity for a meaningful range.

  1. Open System > Usage and choose a relevant time range.

  2. Compare request count, input/output tokens, runtime activity, and provider cost where available.

  3. Filter by model/provider/workflow and identify one clear outlier.

  4. Trace the outlier to an automation, long context, retry loop, or user workload before changing limits.

  5. Apply one correction and review the next comparable period.

You are done when
You can name the top consumer and the evidence-backed reason, plus one targeted correction.
If something looks wrong
Local tokens treated as cloud costLocal models use compute and energy but do not have provider per-token billing; interpret cost fields by route.
Short time rangeAvoid policy changes based on one unusual request.
Workflow 06

Archive and restore a session

Move old conversation/execution history out of active views without deleting it.

Beginner3–5 minResult · Session leaves active list and can be restored✓ Source-audited workflow
System Sessions showing the default session, Session Archives, queue mode, routing overrides, tags, and metadata.
Select the exact session and use Session Archives to confirm that archive or restore completed.
Before you start
  • A session no longer needed in active work.

  1. Open System > Sessions and locate the session by title, type, or date.

  2. Open it and confirm it is the intended record.

  3. Choose Archive. Switch to the Archives view and locate it again.

  4. Use Restore as a test, then archive it again if desired.

You are done when
The session moves between active and archived views without losing its content.
If something looks wrong
Need permanent deletionArchive is reversible and safer. Use deletion only when you truly intend to remove the record.
Workflow 07

Create and test a backup

Snapshot app state, sessions, knowledge, and configurations, then prove the file can be inspected/restored through the guarded flow.

Intermediate10–30 minResult · A current backup is validated✓ Source-audited workflow
System Advanced Backup showing a completed safe backup, its file count and size, restore controls, and Backup History.
The concise completion message and recorded history confirm the backup without exposing its temporary capture path.
Before you start
  • A trusted destination with enough space.
  • Understanding of whether secrets are included or referenced.

  1. Open System > Advanced > Backup and review included categories and encryption options.

  2. Create a snapshot to a clearly dated file on a different disk or protected backup location.

  3. Wait for completion and inspect the app's manifest/summary rather than assuming the file is valid because it exists.

  4. Use the restore preview/validation action to see what would change. Do not overwrite current state for a casual test.

  5. Record the backup date and keep at least one older known-good copy.

You are done when
The app validates the backup and restore preview lists the expected categories with no corruption warning.
If something looks wrong
Backup stored beside live dataA disk failure could remove both. Keep a protected copy on separate media/location.
Restoring blindlyPreview exact scope and make a fresh backup before applying a restore.
Workflow 08

Store and rotate a secret

Keep provider keys, bot tokens, and connector credentials out of prompts and plain configuration.

Beginner5–10 minResult · A reference works before and after rotation✓ Source-audited workflow
System Advanced Secrets showing the encrypted local secret store and Add Secret action.
Add credentials here instead of placing them in prompts, screenshots, or plain configuration files.
Before you start
  • A credential from its official provider.
  • A dependent provider/connector to test.

  1. Open System > Advanced > Secrets and create an entry with a clear service/purpose name.

  2. Paste the value only into the protected secret field and save. Use its reference in the provider, webhook, MCP, or channel configuration.

  3. Run a harmless connectivity test.

  4. Generate a replacement at the provider, update the stored secret, test again, then revoke the old value.

  5. Review Audit Trail for the rotation event without expecting the secret value to appear.

You are done when
The dependent integration works with the new value, the old value is revoked, and logs/audits do not reveal either secret.
If something looks wrong
Secret was pasted into ChatAssume it may persist in history: revoke/rotate it, delete affected content where appropriate, and use the Secrets store next time.
Workflow 09

Run a security posture audit

Check listeners, authentication, allowlists, secret hygiene, and default-deny gaps after configuration changes.

Intermediate10–20 minResult · High-risk findings are fixed or explicitly accepted✓ Source-audited workflow
System Advanced Security Audit showing the configured capture profile’s score, check summary, and detailed findings.
Run the audit after meaningful configuration changes, then review every warning before exposing a service beyond the Mac.
Before you start
  • Especially useful after enabling Remote Access, channels, MCP, plugins, or automation.

  1. Open System > Advanced > Security Audit and run a fresh scan.

  2. Address exposed unauthenticated ports, weak/default keys, overly broad tool access, missing allowlists, and secret hygiene first.

  3. Use each finding's destination link and correct the exact configuration.

  4. Rerun the audit and document any accepted residual warning with owner and reason.

You are done when
No unexplained critical/high finding remains, and accepted warnings have a deliberate rationale.
If something looks wrong
Turning off the checkThat hides evidence; fix the configuration or explicitly document the justified exception.
Workflow 10

Review the Audit Trail after a tool action

Trace who/what invoked a tool, the approval decision, target, result, and related session.

Beginner5–10 minResult · The action is fully attributable✓ Source-audited workflow
System Advanced Audit Trail showing representative knowledge, automation, and backup events with the selected event’s details.
Select an entry to verify when it happened, what feature and target it affected, which files changed, and the recorded metadata.
Before you start
  • A recent chat, agent, channel, exec, or automation action.

  1. Open System > Advanced > Audit Trail.

  2. Filter by time, tool/action type, agent/session, channel, or approval state.

  3. Open the event and review caller identity, arguments summary, approval, target, result, and correlation IDs.

  4. Follow correlation to Requests/Logs/Session when deeper evidence is needed.

  5. Export only the filtered events required for review.

You are done when
You can answer who initiated the action, what was approved, what target changed, and whether it succeeded.
If something looks wrong
Audit lacks raw secretThat is intentional. Auditability should not require logging credential values.
Workflow 11

Test the Content Scanner

Check a harmless known test string/file and verify the scanner's policy before relying on it in automation.

Advanced10–20 minResult · Scanner allows safe input and flags the test case✓ Source-audited workflow
System Advanced Content Scanner showing the scanner’s text input, analysis controls, and classification surface.
Start with disposable text so you can verify classification and redaction boundaries before scanning sensitive material.
Before you start
  • A non-sensitive benign sample and a documented harmless scanner test case.

  1. Open System > Advanced > Content Scanner and review enabled policies/actions.

  2. Scan the benign sample and confirm it passes.

  3. Scan the documented harmless test case and confirm the expected warning/block/quarantine behavior.

  4. Inspect the audit record and tune only the policy that produced an incorrect result.

  5. Repeat both samples after the change.

You are done when
The safe sample still passes and the test case still triggers the intended policy with an audit record.
If something looks wrong
Using real malware or secretsDo not. Use documented safe test strings/files and isolated non-production data.
Workflow 12

Change the app language

Switch localization and confirm main windows, sheets, and formatted ports/numbers remain correct.

Beginner3–5 minResult · The chosen language applies consistently✓ Source-audited workflow
System Advanced Language showing English selected and the complete list of available localized interfaces.
Change the language here, then revisit the main hubs to confirm that labels and formatting update consistently.
Before you start
  • Ai Keeper supports the selected language.

  1. Open System > Advanced > Language and choose the language.

  2. Apply/restart if requested.

  3. Open the sidebar, a settings page, Chat's model picker, and an agent sheet.

  4. Check that labels are translated consistently and port numbers are not shown with thousands separators.

You are done when
Primary hubs and modal sheets use the chosen app language, and technical identifiers/ports remain correctly formatted.
If something looks wrong
One technical term stays EnglishSome proper names/protocols are intentionally untranslated; report actual UI leakage with the exact screen.
Workflow 13

Create Tool Groups, Templates, and Personality

Centralize reusable capability bundles and prompt context without duplicating them in every agent.

Advanced15–30 minResult · One agent inherits each reusable component✓ Source-audited workflow
System Advanced Operator showing Tool Groups, Templates, Content Scanner, Exec Sessions, and Personality.
Build reusable operator context here instead of duplicating the same tools and prompts in every agent.
Before you start
  • At least one repeated tool set or prompt/persona requirement.

  1. Open System > Advanced > Tool Groups and create a narrowly named group from reviewed tools.

  2. Open Templates and create a compact reusable bootstrap/context template with a clear scope.

  3. Open Personality and write durable voice/tone guidance only; keep task instructions in agents/skills/templates.

  4. Assign the group/template/personality to one test agent and preview its assembled prompt/tool list.

  5. Run a test, then remove any duplicated context.

You are done when
The agent receives the intended tools and prompt components once, and changing a shared component has a visible reviewed effect.
If something looks wrong
Tool Group too broadSplit by trust/purpose and preserve approvals.
Personality contains secrets or task dataPersonality is durable context, not a vault or project notebook.
Workflow 14

Create and close an Exec Session

Use a persistent shell/REPL handle with a bounded lifetime and strict command policy.

Advanced10–20 minResult · Session persists state, then closes cleanly✓ Source-audited workflow
System Advanced Exec Sessions showing the default security mode, New Session control, and a clear first-use empty state.
Create an isolated session only when needed, choose its security mode deliberately, and close the exact shell handle when the task finishes.
Before you start
  • A task that truly benefits from persistent command state.
  • Approved executable and working directory within policy.

  1. Open System > Advanced > Exec Sessions and create a session with an explicit executable, safe working directory, and lifetime.

  2. Keep the exec allowlist and PTY restrictions unchanged. Do not use the session to bypass normal tool policy.

  3. Run a harmless command that creates only in-session state, then a second command that proves the same session retained it.

  4. Review its audit entries and attach it only to the intended agent/workflow.

  5. Close the session and confirm its process ends.

You are done when
State persists across the two commands, every command is audited, and the process disappears after close/expiry.
If something looks wrong
Need an unrestricted terminalUse Terminal yourself. Exec Sessions remain policy-controlled model tools, not a way to relax the allowlist.
Stale sessionSet short lifetimes and close sessions when the job ends.

Keep going

← Remote access and distributed usePrevious collectionReference & FAQ →Commands, providers, and troubleshooting