OneSidekick Documentation

OneSidekick is an AI-powered desktop terminal assistant that helps you work faster and smarter in your command line. It combines an intelligent chat interface, an integrated terminal, and a rich set of productivity tools into a single desktop application.

Who is it for?

• Security professionals who need to triage incidents, run scans, and investigate logs.
• System administrators who manage infrastructure, troubleshoot services, and automate tasks.
• Data analysts who transform and pipeline data through the terminal.
• Students and learners who want a patient assistant that explains commands along the way.

System Requirements

• Windows 10/11, macOS 12+, or Linux (Ubuntu 22.04+, Fedora 38+)
• 4 GB RAM minimum (8 GB recommended)
• 200 MB of free disk space
• Active internet connection for AI features

Installation

1. 1Visit onesidekick.io and click Download Beta or Start Free.
2. 2Create an account using your email address or sign up through OAuth.
3. 3Download the installer for your operating system from the Dashboard.
4. 4Run the installer and follow the on-screen prompts.
5. 5Launch OneSidekick. You will see a login screen on first launch.

Signing In

The desktop app offers two sign-in methods:

• OAuth (recommended) - Click "Sign in with OneSidekick" to open your browser and complete login securely.
• Email and password - Enter the credentials you used during sign-up.

The OneSidekick interface uses a three-column layout. Each column is resizable by dragging the dividers between them.

• Chat Panel (left) - Your AI conversation area. Ask questions, request commands, or use slash commands to trigger special features.
• Center Panel (middle) - A collapsible icon strip of tabbed tools. Click an icon to toggle a tab open or closed. The full set is: Skills, Chats (Conversations), Envs (Environments), Auto (Automations), Creds (Credentials), Apps, History, Snips, Files, Tree (File Explorer), Git (Source Control), and Clips (Clipboard). A T-Map (Token Map) tab also appears while Secure Mode is on. Environments, Automations, Apps, Files, and Credentials can each be hidden from the strip in Settings.
• Terminal Panel (right) - Hosts your terminal sessions (up to four, with split-pane layouts) plus tabs for Micro Apps, Diagrams, the Code Editor, security scan results, and web previews. The tab bar includes a grid Tab Overview button to see and jump between everything that is open.

Title Bar

The title bar at the top of the window shows the OneSidekick logo on the left. When Local AI is active, a green Local Mode badge appears next to the title. On the right are a theme (light/dark) toggle, an agent notification bell (see AI Agent), and a user menu. The user menu includes:

• Your name, email, and subscription tier
• Quick access to Settings
• Manage Account link (opens browser)
• Sign Out button

The chat panel is where you interact with the AI assistant. Type a message, and the AI will respond with helpful guidance, commands, or code. Responses stream in real time so you can start reading before the answer finishes.

Sending Messages

1. 1Click the text input at the bottom of the chat panel.
2. 2Type your question, request, or command.
3. 3Press Enter to send. Use Shift + Enter for a new line.

Slash Commands

Type / in the chat input to open an autocomplete menu of slash commands. Keep typing to filter it, use the Up / Down arrows to move, and press Tab or Enter to insert the command (Esc closes the menu). The available commands are:

Chat Input Controls

The toolbar at the bottom of the chat input holds a few extra controls:

• Slash menu (+) - Opens the same command menu as typing /.
• Secure Mode (shield) - Toggles DataVeil anonymization for outgoing messages. The shield turns green when active (see Security & Privacy).
• Attachments - Terminal selections, file contents, snips, and screenshots can be attached to a message; they appear as removable pills above the input (see Screenshots & Attachments).

Conversations

Each chat thread is saved as a conversation. You can manage conversations from the Conversations tab in the center panel:

• Click New Chat in the chat header to start a fresh conversation.
• Conversations are automatically titled based on your first message.
• Click any conversation in the list to reload its messages.
• Delete a conversation by clicking the trash icon next to it.

Markdown and Code in Responses

AI responses support rich formatting including headings, bold text, lists, code blocks with syntax highlighting, and math equations rendered with KaTeX. Code blocks come with built-in action buttons (see the Code Blocks section below).

The AI Agent is an autonomous mode that completes a whole task for you. Instead of answering with text, it works in a loop -- reading files, searching the codebase, and running commands -- and pauses for your approval before it changes anything. Start it by typing /agent followed by a task, for example /agent add a health-check endpoint and a test for it.

What the Agent Can Do

The agent has a fixed set of tools. Read-only tools run automatically; anything that changes your machine pauses for approval.

Approving Changes

Whenever the agent wants to write a file, edit a file, or run a command, it stops and shows an approval prompt in the chat:

• Review the action -- the prompt shows the tool, its arguments, and a risk level before you decide.
• See edits as a diff -- file changes are shown as a colored diff of exactly what is added and removed.
• Accept or reject per hunk -- each change is split into hunks with its own checkbox. The Apply button updates to show what you kept (for example Apply 2 hunks); only the hunks you accept are written.
• Reject -- declining tells the agent you said no, and it adjusts or asks how to proceed.

Live Progress & Stopping

As the agent works, each tool call appears as a step in the chat with a status icon (running, done, rejected, or error) and its output. You can stop the run at any time with the Stop button in the chat input; the agent finishes the current step and then halts.

Agent Monitoring & Notifications

OneSidekick also watches for command-line coding agents (such as Claude Code and Codex) running inside your terminal, so you know when they need you even if you have switched windows.

• Notification bell -- the bell in the title bar opens a center that lists active agent sessions and their status, with a badge for sessions that are waiting on you.
• Tab status dots -- a terminal tab shows a pulsing blue dot while its agent is working and an amber dot when it needs input.
• Desktop alerts -- you get a native OS notification when an agent needs input, finishes, fails, or looks stuck, and an in-app toast when the window is focused.
• One-click setup -- the notification center offers an Enable Claude Code & Codex alerts button that installs the needed hooks for you.
• Preferences -- a master notifications toggle and a stuck-detection idle threshold (default 120 seconds; set to 0 to disable) live in the same panel.

The terminal panel on the right gives you a fully functional shell directly inside OneSidekick. You can run commands, view output, and interact with your system without leaving the app.

Managing Sessions

• The terminal starts with one session. You can open up to four sessions at a time.
• Click the + button on the tab bar to add a new session.
• Click a tab to switch between sessions. Each tab shows a colored dot: green for active, red for exited.
• Click the X button on a tab to close (kill) that session.

Split Layouts & Tab Overview

With more than one session open you can view several at once. The layout buttons at the bottom of the panel switch between modes as sessions become available:

• Single, two stacked, two side-by-side, three stacked, or a 2x2 grid. The active pane is highlighted with an accent ring.
• Focus mode expands the active pane to about 80% of the space and shrinks the others, so you can keep an eye on background sessions while you work.
• Tab Overview -- the grid button in the tab bar (with an open-tab count badge) shows a card for every open tab across all types: terminals, Micro Apps, diagrams, editors, security scans, and previews. Click a card to jump to it, or close it with its X.

Detached Windows

Click the detach icon on a tab to pop that session out into its own window -- useful for a second monitor. The session keeps running and its output stays in sync. Click the reattach icon to bring it back into the main panel.

Search, Links & Font Size

• Find in terminal -- press Ctrl + F (or click the search icon) to open a search bar. Type to highlight matches; Enter and Shift + Enter jump between them, Esc closes it.
• Clickable links -- any http(s) URL printed to the terminal becomes clickable and opens in your default browser.
• Font size -- the +/- controls at the bottom adjust the terminal font (8-28px) independently of the app-wide font size.

Selecting Terminal Text

When you select text in the terminal, a small toolbar appears so you can:

• Copy -- copy the selection to your clipboard.
• Clip -- save the selection to your Snips (it gets a Terminal badge).
• Attach to chat -- send the selection to the chat input as an attachment so the AI has it as context.

Web Preview

When OneSidekick spots a local dev-server URL in your terminal output (for example http://localhost:3000), a pill appears offering to open it. Click Open to view the site in a preview tab right inside the app, with reload, open-in-browser, and a same-origin toggle (enable it if your dev server needs it for hot reload or auth). You can open several previews at once.

Skills let you customize how the AI assistant behaves. Each skill is a custom persona with its own name, description, and system prompt that shapes the AI's responses and expertise.

Creating a Skill

1. 1Open the Skills tab in the center panel.
2. 2Click the + New Skill button.
3. 3Enter a name (for example, "Python Expert" or "DevOps Assistant").
4. 4Write a description so you remember what this skill is for.
5. 5Enter a system prompt that tells the AI how to behave (for example, "You are an expert Python developer. Always provide code examples with explanations.").
6. 6Click Save.

Using a Skill

• Click a skill card to select it. The chat header will show a badge with the active skill name.
• Click the badge in the chat header to deselect the current skill.
• To make a skill your default for all new conversations, click Set as Default on the skill card.

Environments let you configure and manage different development setups like Docker containers, Conda environments, Python virtual environments, and more. Each environment comes with pre-checks and automated setup steps.

Setting Up an Environment

1. 1Open the Environments tab in the center panel.
2. 2Browse the available environment types (Docker, Conda, Python venv, and others).
3. 3Click Setup on the environment you want.
4. 4A dialog will appear with two phases:
   • Pre-checks verify that required tools are installed.
   • Setup steps create and configure the environment.
5. 5Once setup completes, the environment becomes available in your terminal sessions.

Smart Setup Diagnostics

The setup dialog detects what is missing and offers a one-click fix rather than just failing:

• Docker not installed offers a winget install; Docker not running can launch Docker Desktop and wait for the daemon to come up.
• Python not installed offers a one-click install (winget on Windows, apt on Linux), and Conda not installed offers a winget install.

Managing Environments

• Docker-based environments show a status badge (Running, Stopped, or Not Created) and let you start, stop, or delete the container right from the card.
• Delete an environment using the trash icon on its card.

WSL Distributions (Windows)

On Windows, the Environments tab also lists your installed WSL distributions (the internal distros used by Docker Desktop and Rancher Desktop are hidden).

• Each distro card shows a status dot (running or stopped).
• Click attach to open that distro in the active terminal, or stop a running one.
• A refresh button re-scans for distributions.

Automations are multi-step workflows that you can create with natural language, then run with one click. Each automation consists of ordered steps, optional variables for user input, and rollback steps that run if something fails.

Creating an Automation

1. 1In the chat, type /automation followed by a description of what you want to automate (for example, /automation set up a Node.js project with TypeScript).
2. 2The AI will generate an automation definition. A yellow banner appears at the top of the chat.
3. 3Click Save Automation to save it to your library.

Running an Automation

1. 1Open the Automations tab in the center panel.
2. 2Click an automation card to open its detail view.
3. 3Review the steps in the Steps tab. Click any step to expand and view its details.
4. 4If the automation uses variables, switch to the Variables tab and fill in the required values.
5. 5Click the Run button to start execution.
6. 6During execution, the view switches to the Execution tab showing real-time progress. You can Pause, Resume, or Abort the run at any time.

Other Actions

• Duplicate an automation to create a copy you can modify.
• Export an automation to a JSON file for sharing or backup.
• History tab shows previous runs with their results.
• Delete removes the automation permanently.

Micro Apps are just-in-time React applications generated on demand. Describe what you need, and the AI creates a fully working app that is compiled and runs right inside OneSidekick -- no external dependencies, no network calls, and no data leaving your machine.

Creating a Micro App

1. 1In the chat, type /app followed by a description (for example, /app a dark-mode color palette picker).
2. 2The AI generates a React component. A yellow banner appears with an Open App button.
3. 3Click Open App. The app is compiled locally and opens in the terminal panel as a new tab.

How It Works -- Bundled & Secure

Every Micro App goes through a secure, self-contained pipeline that keeps everything on your machine:

1. 1AI generates the code -- the AI writes a single-file React component based on your description.
2. 2Local compilation -- the TSX code is compiled to JavaScript on your machine using a built-in Rust compiler (SWC). Nothing is sent to an external build service.
3. 3Everything is bundled in -- React itself is pre-packaged inside the app at build time. When a Micro App runs, it loads React from this local bundle, not from the internet. There are zero network requests.
4. 4Sandboxed execution -- the compiled app runs in an isolated iframe sandbox. It cannot access your files, make network calls, or interact with the rest of the application. Communication happens only through a controlled message channel for things like console logs and file downloads.

Managing Micro Apps

• Open the Apps tab in the center panel to browse all saved Micro Apps.
• Use the search bar to find apps by name, description, or tags.
• Click the heart icon on an app card to mark it as a favorite.
• Click View Source in the detail view to see the TSX code behind the app.
• Delete an app using the trash icon.

OneSidekick can turn a description into a clean, interactive diagram. Type /diagram followed by what you want to visualize (for example /diagram our zero-trust network architecture), and the AI builds it for you. The diagram appears as a clickable card in the chat; click it to open the full, interactive version in a tab in the right panel.

Diagram Types

The AI picks the right type for your request from eight built-in kinds:

• Pipeline -- numbered steps with status (completed, running, failed, and so on).
• Flow -- flowcharts with boxes, diamonds, and labeled, branching edges.
• Sequence -- message exchanges between participants over time.
• Network -- infrastructure topology with servers, databases, routers, firewalls, and more.
• Process -- workflows organized into swim lanes by role or department.
• Decision -- decision trees with branch outcomes.
• Architecture -- layered system diagrams with grouped components.
• Database -- entity-relationship diagrams with tables, columns, and constraints (PK, FK, unique, and so on).

Working with a Diagram

Once a diagram is open in its tab, a toolbar gives you full control:

• Zoom and pan -- zoom from 0.25x to 3x with the buttons or the scroll wheel, drag to pan, and reset to fit.
• Color palette -- choose Default, Pastel, or High Contrast. The Default palette follows your light/dark theme automatically.
• Export -- save the diagram as a PNG image.
• Edit layout (database diagrams) -- drag tables and edge labels to arrange the ERD, then reset the layout if needed.

OneSidekick includes two complementary security scanners: an AI-powered code analyzer you run on demand, and a deterministic supply-chain scanner that checks your installed dependencies against a known-threat catalog. (This is separate from Secure Mode / DataVeil, which masks data in chat -- see Security & Privacy.)

AI Security Analysis (/security)

Type /security followed by code to review or a question (for example /security review this login handler). The AI performs an OWASP Top 10 / CWE-style analysis and returns a structured report inline in the chat:

• A color-coded risk score (0-100) and a count of findings by severity.
• Expandable findings -- each with severity, OWASP category and CWE tags, location, vulnerable code, and remediation guidance. Filter by severity with the pills.
• A checklist and recommendations, plus a raw-JSON view.
• View Details opens the full report in its own tab; Save stores the scan for later, and Copy Report copies it as markdown.

Supply-Chain Scanner

The supply-chain scanner inventories your dependencies and editor extensions and matches them against a catalog of known-compromised packages. It is deterministic and runs entirely on your machine -- it never sends your code or package lists anywhere.

• Auto-detected Scan button -- when your terminal is in a project folder (npm, PyPI, Go, or Cargo manifests are detected), a Scan button appears in the terminal tab bar with a badge for the number of ecosystems found.
• Three profiles -- Baseline (editor extensions only), Project (the active folder), and Deep (a deeper walk of the active folder). You can also run a scan manually from Settings > Security.
• Results tab -- opens a tab titled "Supply-chain: <folder>" with a risk score, flagged packages grouped by severity, remediation steps, a checklist, and recommendations. Save it to history or copy it as a report or JSON.
• Supported ecosystems -- npm, PyPI, Go, and Cargo lockfiles/manifests, plus VS Code, Cursor, Windsurf, and VSCodium extensions.

Threat Catalog

Matches come from a threat catalog mirrored from the public Bumblebee threat-intelligence feed. It is cached on your disk so scans work offline. Open Settings > Security to see the catalog version, entry count, last-updated time, and source, and click Update to refresh it from the network. Scans always use the cached catalog and never fetch on their own.

When the AI includes code in a response, it appears in a formatted code block with syntax highlighting. Each code block comes with five action buttons:

Command Annotations

The AI can tag runnable code blocks with hidden annotations that change how they are presented:

• @title gives the block a descriptive heading, and @run marks it as runnable.
• @type: read or modify indicates whether a command only reads or changes your system.
• @danger: low|medium|high shows a color-coded risk badge, and @confirm: true requires you to confirm before the command runs.

For commands that install tools or change the shell environment, a Run & Restart button also appears, which runs the command and then restarts the terminal so the changes take effect. You can also edit a block inline before running it (Ctrl + Enter to confirm, Esc to cancel).

The Tree tab in the center panel is a file browser for working with files alongside your terminal and chat. Expand and collapse folders, see language-aware icons, and act on any entry through its right-click menu. It stays open while you click into the terminal so it is always at hand.

Right-Click Actions

Right-click a file or folder to:

• Open in Editor -- load the file in the built-in Code Editor.
• Attach to chat -- send the file contents (or a directory listing) to the chat as context, up to 5 MB per file.
• Open in Terminal, Copy Path, Reveal in file manager, and Delete.
• Create new files and folders.

Searching

The search box has two modes. File search finds files by name using fuzzy matching (filename matches rank above path matches). Content search runs a fast, ripgrep-style regex over file contents, with case-sensitivity, glob filters (for example **/*.ts), and .gitignore awareness. Both respect ignore rules and skip protected files.

Snips are saved code and terminal text selections, all accessible from the Snips tab in the center panel. Terminal snips are marked with a Terminal badge so you can tell them apart at a glance.

• Click Clip on any AI code block to save it as a snip.
• Select text in the terminal and click Clip from the selection toolbar to save a terminal snip.
• Code snips can be executed with the Run button or copied to clipboard.
• Terminal snips can be copied or attached to a chat message for context.
• Delete individual snips with the trash icon.

Every command you run through OneSidekick (from code blocks, snips, or automations) is recorded in the History tab. This makes it easy to find and re-run commands you used before.

• Open the History tab in the center panel.
• Each entry shows the command, its language, and a timestamp.
• Click Run to re-execute a command in the active terminal.
• Delete individual entries or click Clear All to reset the history.

The Clipboard tab keeps a running log of your recent clipboard activity (up to 20 entries). It automatically captures text you copy from any source while OneSidekick is open.

• Each entry shows a preview of the copied text and a relative timestamp.
• Click Copy on any entry to send it back to your clipboard.
• Duplicate entries are automatically skipped.
• Click Clear All to remove all clipboard history.

The Files tab lets you drag and drop files into OneSidekick and deploy them to your terminal's working directory or into a Docker container.

Deploying a File

1. 1Open the Files tab in the center panel.
2. 2Drag a file from your system into the drop zone, or click to browse.
3. 3Click Deploy next to the uploaded file.
4. 4The file is copied to the terminal's current working directory. If the active terminal uses a Docker environment, the file is copied into the container instead.

The Creds tab is an encrypted vault for the secrets you use day to day -- SSH logins, API keys, tokens, passwords, and connection strings. Values are encrypted with AES-256-GCM and the vault key lives in your OS keychain. Credentials are only decrypted on demand, and every access is recorded in an audit log.

Adding a Credential

1. 1Open the Creds tab and click Add.
2. 2Give it a name and pick a type: SSH Connection, API Key, Token, Password, Connection String, or Custom.
3. 3Enter the value (for SSH, enter the host and username, and optionally a password -- leave it blank for key-based auth). You can also add a description, tags, and an expiry date.
4. 4Click Save. The value field is masked by default with a show/hide toggle.

SSH Connect

SSH credentials show a Connect button. Clicking it runs ssh user@host in the active terminal, and if a password is stored, OneSidekick watches for the password prompt and types it in for you automatically (it gives up after 30 seconds if no prompt appears). The password is written straight to the terminal and never touches your system clipboard.

Pasting & Linking Credentials

• Paste to terminal -- the key icon in the terminal tab bar lets you pick a credential and paste it directly into the terminal (with a confirmation step), again bypassing the clipboard.
• Link to automations -- automation variables can reference a stored credential instead of hard-coding a secret, with suggestions based on the variable name.
• Access log & expiry -- each card shows recent accesses (SSH connect, terminal paste, automation run, reveal) and flags credentials that are expired or expiring within 7 days.

The Git tab is a built-in source-control panel. It automatically reads the git repository in your active terminal's working directory, so as you cd between projects it follows along. If the folder is not a repository, it simply says so.

What You Can Do

• See status -- the current branch, ahead/behind counts, and changed files marked M (modified), A (added), D (deleted), R (renamed), C (copied), or U (untracked), color-coded.
• Stage and unstage -- use the + and - buttons on each file, or discard changes (restores tracked files, removes untracked ones).
• View diffs -- click a file name to open its unified diff in the Code Editor.
• Commit -- write a message and press Ctrl + Enter (or click Commit). The button shows how many files are staged.
• Fetch, Pull, and Push -- pull is fast-forward only, and push is disabled if your branch has diverged so you pull or rebase first.
• Commit history graph -- the History section draws a colored branch/merge graph of recent commits with author and date.

You can give the AI more context by attaching content to a chat message. Attachments show up as removable pills above the chat input and are sent along with your text; they are cleared once the message is sent.

What You Can Attach

• Terminal selections -- select output in the terminal and choose Attach to chat from the selection toolbar.
• Files and folders -- right-click an entry in the File Explorer and attach its contents or listing.
• Snips -- use the paperclip button on any saved snip.
• Screenshots -- captured regions of your screen (see below).

Capturing a Screenshot

Click the camera button in the chat input toolbar to capture part of your screen:

1. 1The window steps aside and a full-screen overlay appears.
2. 2Drag to select a region; the overlay shows the pixel dimensions as you drag. Press Esc to cancel.
3. 3The cropped image is attached to your message as an image, so the AI can analyze it visually.

Local AI runs an open-source language model directly on your machine, so chat works with no account and no network -- nothing leaves your device. OneSidekick downloads a small llama.cpp runtime and your chosen model, then serves it locally and routes all chat to it.

Turning It On

1. 1Open Settings > Local AI and check Local AI. A setup wizard opens.
2. 2Review the requirements (about 2.5 GB of disk for the model plus ~15 MB for the runtime, and 8 GB+ RAM recommended) and pick a model.
3. 3OneSidekick checks your disk and memory, then downloads the runtime and the model with progress bars. Internet is only needed for this initial download.
4. 4When setup completes, your chat uses the local model. A green Local Mode badge appears in the title bar.

Choosing a Model

Three curated models are available, downloaded as quantized GGUF files:

• Phi-4 Mini (Microsoft, ~2.5 GB) -- the default.
• Gemma 4 E4B Uncensored (~5 GB).
• Nemotron Terminal 8B (NVIDIA, ~5 GB).

Open Settings from the user menu in the title bar or from the settings icon in the chat header. The dialog is organized into seven sections in a left sidebar.

Key Settings Explained

• Color Theme -- twelve palettes: Default (Lime), Nord, Tokyo Night, Catppuccin, Gruvbox, Rosé Pine, Clay, Dracula, Solarized, One Dark, Everforest, and Monokai. The Theme toggle still controls light/dark for palettes that support both.
• Safe Mode -- blocks dangerous shell commands before they run, both those you launch from a code block and those the AI agent tries to run. See Security & Privacy.
• Enter to Send -- when on, Enter sends and Shift+Enter adds a line; when off, Ctrl/Cmd+Enter sends.
• Modules -- hide tabs you do not use to streamline the interface. (Some modules are turned off automatically in Local AI mode.)

OneSidekick automatically checks for new versions so you always have the latest features and fixes.

OneSidekick offers four subscription tiers. Your tier determines your daily request limit, available AI models, and monthly token allowance.

To manage your subscription, click Manage Account in the user menu. This opens the billing page in your browser where you can upgrade, downgrade, or cancel your plan.

OneSidekick is built with a security-first architecture. Your data stays on your machine, credentials are stored in your operating system's secure keychain, and your local database is encrypted at rest. This section covers every layer of protection built into the app.

Local-First Data Storage

OneSidekick runs entirely on your machine. Your data never leaves your device unless you explicitly interact with AI features that require an internet connection.

• Chat conversations, command history, snips, automations, and settings are all stored locally in an encrypted SQLite database.
• Terminal sessions run via native PTY processes on your OS. Terminal input and output never leave your machine.
• Only AI chat messages are sent to the AI provider (OpenAI) when you choose to use the chat feature. All other app features work offline.
• Micro Apps are generated via AI but compiled locally and run in a sandboxed iframe with no network access -- the generated code never phones home.

OS Keychain Credential Storage

Sensitive credentials are stored in your operating system's native secure credential manager, not in the database or config files.

• API keys -- API keys and other credentials are stored in the OS keychain (Apple Keychain on macOS, Credential Manager on Windows, Secret Service on Linux) -- never in plaintext files or the database.
• Auth tokens -- OAuth access tokens and refresh tokens are stored in the keychain, never in browser storage or plaintext files.
• Automation vault keys -- Each automation's encryption key is stored separately in the keychain under a unique identifier.

Database Encryption (SQLCipher)

OneSidekick encrypts your local database at rest using SQLCipher (AES-256 full-database encryption). This protects all stored data -- chat messages, command history, code snippets, environment configurations, and more -- even if someone gains access to your device's file system.

• A unique 256-bit encryption key is generated on first launch and stored securely on your device.
• All database reads and writes are transparently encrypted and decrypted. No changes are needed to your workflow.
• Existing unencrypted databases are automatically migrated to the encrypted format on upgrade. A .bak backup of the original is kept as a safety net.
• The encrypted database file is unreadable in any SQLite browser or hex editor without the key.

Encrypted Backups (.osk)

Database backups are exported as .osk files, which are encrypted with a password you choose during export. The encryption uses AES-256-GCM with a key derived from your password via PBKDF2-SHA256 (600,000 iterations).

• Export: Settings > Database Admin > Export Backup. You will be prompted to set a password (minimum 8 characters) and confirm it.
• Import: Settings > Database Admin > Import Backup. Select a .osk file and enter the password used during export.
• Legacy support: Unencrypted .db backup files from older versions can still be imported without a password.
• An incorrect password produces a clear error message. The GCM authentication tag ensures tampered or corrupted backups are detected.

Automation Vault Encryption

Automations can store sensitive variables (API keys, tokens, passwords) in an encrypted vault. Each automation has its own isolated vault with a separate encryption key.

• Sensitive variables are encrypted with AES-256-GCM and stored in a vault.enc file. Non-sensitive variables are stored separately in plaintext.
• Each automation's vault key is stored in the OS keychain, isolated from other automations.
• When an automation runs, sensitive values are substituted into commands at runtime and automatically redacted from all logs and output so they never appear in the UI.

Credential Vault

Credentials you store in the Creds tab (SSH logins, API keys, passwords, tokens, and connection strings) are kept in an encrypted vault, separate from the rest of your data.

• Values are encrypted with AES-256-GCM, and the vault key is held in your OS keychain -- never on disk in plaintext.
• Secrets are decrypted only on demand (to connect over SSH, paste into the terminal, or run an automation) and are written straight to the terminal, bypassing the system clipboard.
• Every access is recorded in a per-credential audit log with the access type and context, and credentials can carry an expiry date.

Offline & Network-Free by Design

• Local AI mode runs the model on your machine, so once it is set up, chat works with no account and no network -- nothing leaves your device.
• The supply-chain scanner reads your files locally and matches them against a cached catalog; it never transmits your code or package lists. Only the manual catalog refresh touches the network.

Secure Authentication (PKCE OAuth)

OneSidekick uses the PKCE (Proof Key for Code Exchange) OAuth flow for browser-based sign-in, which is the industry-standard security protocol for desktop and mobile applications.

• A unique cryptographic code verifier and challenge are generated for each login attempt using SHA-256.
• Auth codes cannot be intercepted and replayed by malicious apps, even on shared machines.
• Tokens are refreshed automatically and stored in the OS keychain. Sessions persist across app restarts without re-authentication.

Safe Mode (Command Protection)

Safe Mode blocks the execution of potentially dangerous shell commands. When enabled, every command is checked against a set of known dangerous patterns before it can run -- this covers both commands you launch yourself from an AI code block and commands the AI agent attempts to run autonomously.

Detected patterns include:

• Recursive file deletion (rm -rf), disk formatting (mkfs), and direct disk writes (dd)
• Fork bombs, overly permissive permissions (chmod 777), and remote script piping (curl | bash)
• PowerShell equivalents: Remove-Item -Recurse -Force, Format-Volume, Clear-Disk, and Invoke-Expression

1. 1Open Settings from the user menu.
2. 2Find the Safe Mode toggle.
3. 3Check or uncheck the box. Changes take effect immediately.

AI Agent Actions & Approvals

When you run the AI agent (via the /agent command), it can read files, edit code, and run commands on your behalf to complete a task. Several layers keep you in control of every change it makes:

• Approval required for changes -- Read-only actions (listing directories, reading files, searching) run automatically, but writing a file or running a command always pauses for your explicit approval first.
• Review edits as a diff -- When the agent proposes a file change, you see a colored diff of exactly what will be added and removed before anything is written.
• Accept or reject individual changes -- The diff is split into separate hunks, each with its own checkbox. Keep the changes you want and drop the ones you don't -- only the hunks you accept are written to the file.

Always-On Secret-File Protection

Independent of Safe Mode, the agent is permanently blocked from reading or writing files that typically hold secrets. This protection cannot be turned off, so the auto-approved read tools can never quietly expose your credentials.

• Secret files -- .env files, private keys (.pem, id_rsa), and credential files are refused on both read and write.
• Protected folders -- Sensitive directories such as .ssh, .aws, .gnupg, and .kube are off-limits.
• System directories -- Writes to operating-system locations (such as /etc, /usr/bin, or the Windows folder) are blocked.

Secure Mode -- DataVeil Tokenization (Experimental)

Secure Mode automatically detects and tokenizes sensitive data in your chat messages before they are sent to the AI provider. The AI only sees placeholder tokens like [EMAIL_1] or [JWT_1] -- your real values never leave your machine.

When the AI responds using those tokens, OneSidekick automatically replaces them with the original values so you see the real data in your conversation.

How to Enable

1. 1Click the Shield button in the chat header (next to the OS selector).
2. 2The button turns green when Secure Mode is active. The setting persists across sessions.

How It Works

1. 1You type a message containing sensitive data (e.g., an API key, email address, or connection string).
2. 2DataVeil scans the message with 30+ regex patterns and replaces each match with a numbered token (e.g., [email protected] becomes [EMAIL_1]).
3. 3Only the tokenized text is sent to the AI. Your real values stay local.
4. 4When the AI responds, any tokens in the response are automatically de-tokenized back to the original values before display.

Token Map Panel

The Token Map tab in the center panel shows all detected sensitive values for the current conversation, grouped by category with color-coded labels. Each entry displays the original value mapped to its token. You can clear the token map for any conversation at any time.

Message Inspection

When Secure Mode is active, hover over any message to reveal a toggle button. Click it to switch between the Original view (what you typed or the de-tokenized AI response) and the Sent to AI view (the tokenized version the AI actually received). This lets you verify exactly what was anonymized.

Categories Detected

DataVeil recognizes 30+ sensitive data patterns across these categories:

• Secrets and keys -- Private keys (RSA, EC, PGP), JWTs, AWS/GCP/Azure credentials, Slack tokens, GitHub tokens, generic API keys
• Connection strings -- MongoDB, PostgreSQL, MySQL, Redis, RabbitMQ, S3 URIs, and URLs with embedded credentials
• Personal identifiers -- Email addresses, phone numbers, SSNs/tax IDs, passport numbers, driver's license numbers, UUIDs
• Financial data -- Credit card numbers, IBAN numbers
• Network infrastructure -- IPv4/IPv6 addresses, CIDR ranges, MAC addresses, hostnames/FQDNs
• Credentials -- Environment variable secrets, password hashes (bcrypt, argon2, scrypt), Base64-encoded secrets
• Sensitive paths -- References to /etc/shadow, SSH key files, database files, and log files

Per-Conversation Isolation

Each conversation maintains its own independent token dictionary. Token numbering starts fresh per conversation (e.g., [EMAIL_1] in one conversation is unrelated to [EMAIL_1] in another). Deleting a conversation also clears its token dictionary.

Role-Based Access Control

Sensitive operations such as database export, import, and statistics are restricted to users with the admin role. Standard users cannot access these features, which prevents accidental or unauthorized data manipulation.

Cloud Platform Security

The OneSidekick cloud platform (accounts, subscriptions, and the AI proxy service) is hardened with multiple layers of protection to ensure that only authorized services can modify sensitive data.

• Row Level Security (RLS) -- Every database table has RLS policies enabled. Users can only read and update their own profile, and are blocked from modifying protected columns such as tier, role, and Stripe fields. Only the service role (server-side webhooks and admin actions) can change these values.
• Admin verification -- All admin API routes and server actions verify the caller is authenticated and has the admin role before processing. Non-admin users receive a 403 Forbidden response.
• Webhook signature verification -- Stripe webhook events are cryptographically verified using HMAC signatures before any subscription or tier changes are applied. Invalid or tampered webhooks are rejected.
• Input validation -- All API endpoints validate input parameters (UUID format, tier/role whitelists, search sanitization) to prevent injection attacks and parameter tampering.
• JWT-based API authentication -- The AI proxy worker validates JSON Web Tokens against Supabase JWKS, enforcing token expiration and audience claims. Tier-based rate limits (requests per minute, per day, and monthly token caps) are enforced server-side and cannot be bypassed.
• No sensitive keys in the browser -- Stripe secret keys, webhook secrets, and the Supabase service role key are stored exclusively in server-side environment variables and never appear in client-side JavaScript bundles.

Encryption at a Glance

The built-in Code Editor lets you make quick edits to code without leaving OneSidekick. It opens as a new tab in the right column alongside your terminal, diagrams, and micro apps. Powered by CodeMirror 6 with syntax highlighting for multiple languages.

How to Open

• Click the Edit button on any AI code block to open it in the editor.
• Use the Open File button in the editor toolbar to load a file from disk.

Supported Languages

Syntax highlighting is available for JavaScript, TypeScript, JSX, TSX, Python, Rust, Go, C/C++, Java, HTML, CSS, PHP, JSON, YAML, Markdown, Bash, and PowerShell. Other file types open with plain text editing.

Toolbar Actions

Keyboard Shortcuts

Vim Mode

Prefer modal editing? Click the Vim button in the editor toolbar to enable Vim keybindings (normal, insert, and visual modes). The toggle highlights when active and your choice is remembered for future editor tabs. While Vim mode is on, it takes over the editor's keyboard handling -- the default shortcuts above are replaced by their Vim equivalents.