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 tabbed panel with 9 tools: Skills, Environments, Automations, Apps, Conversations, History, Snips, Files, and Clipboard. Click an icon to toggle a tab open or closed.
• Terminal Panel (right) - Integrated terminal sessions and Vibe Apps. Supports up to four concurrent terminal sessions.

Title Bar

The title bar at the top of the window shows the OneSidekick logo on the left and a user menu on the right. 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 a slash command in the chat input to trigger special actions:

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 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.

Detached and Mirror Windows

Each terminal session has two special window modes available from the tab bar:

• Detach - Opens the session in its own separate window. Useful if you want the terminal on a second monitor.
• Mirror - Opens a read-only copy of the session in a new window. Use this to watch output while you work in another tab.

Selecting Terminal Text

When you select text in the terminal, a small toolbar appears with two options:

• Copy - Copies the selected text to your clipboard.
• Clip - Saves the selection to your Snips for later reference.

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.

Managing Environments

• Docker-based environments show a status badge indicating whether the container is running.
• Delete an environment using the trash icon on its card.
• For Docker environments, you can also delete the container separately.

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.

Vibe Apps are instant, AI-generated React applications. Describe what you want, and the AI will create a working React component that runs right inside OneSidekick.

Creating a Vibe App

1. 1In the chat, type /vibe followed by a description (for example, /vibe 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 and opens in the terminal panel as a new tab.

Managing Vibe Apps

• Open the Apps tab in the center panel to browse all saved Vibe 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.

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

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.

Open Settings from the user menu in the title bar or from the settings icon in the chat header.

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.
• Vibe Apps are generated via AI but run in a sandboxed local iframe -- the generated code does not phone 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.

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 suggested by the AI. When enabled, every command is checked against a set of known dangerous patterns before it can run.

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.

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