# Account Setup
Source: https://docs.voxcode.app/account-setup
Create your Voxcode account, choose a subscription plan, and configure your profile settings.
This page covers everything you need to set up your Voxcode account — from signing in for the first time to selecting a plan, managing your credit balance, and configuring API keys.
## Sign in
Voxcode uses OAuth for sign-in, so you don't create a password. On the sign-in screen, choose one of the following:
* **Continue with GitHub** — signs you in using your GitHub account
* **Continue with Google** — signs you in using your Google account
After your first sign-in, Voxcode creates your account and assigns your starting credits automatically.
All new accounts start with 20 free credits. No payment method required. This is enough to explore Voxcode with free-tier models or make a few requests with premium models.
If you want to explore without an account, tap **Try Without Account** on the sign-in screen. Guest sessions are not saved — your conversation history and VFS files are lost when you close the browser.
## Subscription tiers
Voxcode offers three plans. You can view and change your plan at any time from the **Subscription** menu in your account settings.
| Plan | Price | Monthly credits | Model access |
| ------- | ---------- | --------------- | ------------------------------------ |
| Free | \$0 | 20 (one-time) | Free-tier models only |
| Starter | \$7/month | 100 | Free + Beta models, 2 Premium models |
| Premium | \$15/month | 250 | All models + BYOK support |
Credits are consumed based on token usage — the model you choose and the length of your requests determine how many credits each conversation uses. Free-tier models (marked with **!** in the model selector) use zero credits.
### Upgrading your plan
To upgrade, open **Settings** and navigate to **Subscription**. Select the plan you want and complete the checkout flow. Your new credit balance is applied immediately.
If you're on Premium, unused credits roll over each month. Top-up packs are also available if you run low between billing cycles:
* 40 credits — \$4
* 100 credits — \$8
* 200 credits — \$15
* 420 credits — \$30
## Credit balance
Your current credit balance is displayed in the **Settings** menu. You can monitor usage per session, and detailed usage logs are available so you can see which models consumed credits and how many tokens were used per request.
Credits purchased as top-ups never expire.
## Bring Your Own Key (BYOK)
On the **Premium** plan, you can connect your own API keys from external providers. This lets you use those models without consuming Voxcode credits — you pay your provider directly.
Supported BYOK providers include OpenAI, Anthropic, Google Gemini, DeepSeek, and OpenRouter. To add a key:
1. Open **Settings** and go to the model selector
2. Select the **BYOK** tab
3. Choose your provider and model, paste your API key, and save
Keys are encrypted at rest and are never exposed in plain text.
BYOK is only available on the Premium plan. To enable it, upgrade from the **Subscription** menu.
For a full guide on configuring BYOK, see [Bring Your Own Key](/plans/byok).
## Settings overview
Once you're signed in, tap the **Settings** icon (gear icon) in the top navigation bar to access your account configuration. From there you can:
* View and top up your credit balance
* Change your subscription plan
* Select your preferred AI model
* Customize the UI theme (Default Dark, Light, or Monokai)
* Configure voice display (Voice Orb or Classic waveform)
* Adjust orb shape, style, and vibration intensity
* Add or remove BYOK API keys (Premium only)
# Settings
Source: https://docs.voxcode.app/customization/settings
A complete reference for all Voxcode settings and configuration options
The Settings panel gives you full control over Voxcode's appearance, voice visualization, navigation behavior, and more. To open it, tap the **gear icon** in the top navbar.
All settings are saved locally in your browser session. If you clear your browser data or switch to a different browser, your preferences will reset to their defaults.
***
## Opening settings
The gear icon sits in the top-right area of the top navbar, always visible regardless of which view you are in.
Tap the gear icon. The Settings panel slides in over a blurred backdrop.
The panel is scrollable. Each section is labeled — scroll down to find the setting you need.
Tap the **×** button in the top-right of the panel, or tap anywhere on the backdrop behind it.
***
## Settings reference
Controls the global look of the Voxcode interface.
**Theme**
Cycles through three color schemes. Tap the toggle to advance to the next theme.
| Value | Description |
| ------------------ | ----------------------------------------------------------- |
| **Default (Dark)** | Deep dark background with cyan accents. The default. |
| **Light** | Bright backgrounds and dark text for well-lit environments. |
| **Monokai** | Warm dark theme with a classic code-editor color palette. |
**UI Borders**
A toggle that shows or hides decorative borders around UI panels and cards. Off by default. Turn it on if you prefer more defined visual boundaries between sections.
**Chat Background**
Sets the background texture for the chat area. Three categories are available:
* **Solid** — Flat color fills: Default, Dim, or Warm.
* **Patterns** — Geometric textures: Dots, Grid, or Waves.
* **Cosmos** — Animated deep-space scenes: Cosmos (blue/purple), Cosmos Yellow (solar), or Cosmos Red (nebula).
See [Themes](/customization/themes) for a full description of each option.
Switches between the two voice visualization modes.
| Mode | Description |
| ----------- | -------------------------------------------------------------------------------------- |
| **3D Orb** | An animated 3D object rendered with WebGL that reacts to your voice in real time. |
| **Classic** | A flat 2D canvas-based waveform. Lower resource usage; five visual variants available. |
For a detailed walkthrough of all orb and waveform options, see [Voice Orb](/customization/voice-orb).
These settings are available when your Voice Display is set to **3D Orb**.
**Shape**
The 3D geometry used to render the orb. Changing the shape reinitializes the WebGL scene.
| Value | Geometry |
| -------- | ---------------------------------------------------------- |
| Sphere | Icosahedron with high vertex count for smooth deformation. |
| Cube | Box geometry with sharp, reflective edges. |
| Prism | Triangular cylinder. |
| Pentagon | Dodecahedron with 12 flat faceted faces. |
| Donut | Torus with a hollow center. |
**Style**
The shader applied to the orb surface.
| Value | Description |
| ------- | ----------------------------------------------------------- |
| Classic | Dark metallic surface with blue-purple emissive highlights. |
| Blue | Deeper blue tones with a cooler electric glow. |
**Mode**
Controls how much screen space the orb occupies during a voice session.
| Value | Description |
| ----- | ----------------------------------------------------------------------- |
| Half | Orb renders in the bottom half of the screen. Chat stays visible above. |
| Full | Orb fills the entire screen with a dark radial-gradient backdrop. |
**Vibration**
A slider from 1 to 5. Higher values make the orb react more dramatically to audio amplitude. Level 3 is the neutral baseline.
**Bottom Navbar** *(Full mode only)*
Toggle whether the bottom navigation bar remains visible over the full-screen orb. Default: on.
**Visual Feedback** *(Full mode only)*
Toggle whether the orb continues reacting visually during AI speech playback. Default: on.
These settings are available when your Voice Display is set to **Classic**.
**Wave variant**
Select the visual style of the 2D waveform drawn from your microphone input.
| Variant | Description |
| ------------ | -------------------------------------------------------------------------------------- |
| **Bars** | Five rounded vertical bars, each mapped to a different audio frequency band. |
| **String** | A continuous horizontal sine wave with amplitude driven by loudness. |
| **Circle** | A single circle that expands in radius based on mic input. |
| **Dots** | Five dots that grow in size based on their respective frequency band. |
| **Spectrum** | Eight bars spanning the full width, mapped to frequency bins like a spectrum analyzer. |
Controls how you navigate between panels and sidebars.
**Swipe Gestures**
Enables horizontal swipe gestures to open and close the sidebars.
* Swipe **left** to open the File Explorer (right sidebar), or close the History sidebar if it is open.
* Swipe **right** to open the History sidebar (left sidebar), or close the File Explorer if it is open.
A minimum swipe distance of 50px is required to trigger navigation. Disable this if you find swipes interfering with text selection or scrolling.
**Side Toggles**
Shows or hides the sidebar toggle tab buttons on the left and right edges of the screen. Hidden by default. Enable them if you prefer visible tap targets over swipe gestures.
**Sidebar Buttons**
A master switch that enables or disables the action buttons inside the History and File Explorer sidebars. When disabled, the sidebars still open but the buttons within them are inactive.
# Themes
Source: https://docs.voxcode.app/customization/themes
Customize the Voxcode interface with themes and chat backgrounds
Voxcode lets you tailor the look of the entire interface — from the overall color scheme to the texture behind your chat messages. All theme options live in the Settings panel, which you open by tapping the **gear icon** in the top-right corner of the app.
## UI themes
Voxcode ships with three themes that control the global color palette.
Tap the gear icon in the top-right navbar to open the Settings panel.
Scroll to the **Interface** section. The **Theme** row shows your current mode.
Tap the toggle button on the Theme row to cycle through the three available options.
### Available themes
The default Voxcode experience. A deep dark background with high-contrast foreground text and a cyan accent color. Best suited for low-light environments and extended coding sessions.
A bright, clean interface with light backgrounds and dark text. Useful when working in well-lit spaces or if you prefer a more traditional editor aesthetic.
A warm dark theme inspired by the classic Monokai editor color scheme. Slightly warmer tones than Default Dark, with familiar syntax-highlight-style accent colors throughout the UI.
## Chat backgrounds
In addition to the overall theme, you can set a background texture or scene specifically for the chat area. Open Settings and look for the **Chat Background** picker inside the Interface section.
Backgrounds are grouped into three categories.
### Solid
Clean, flat backgrounds with no pattern. These adapt to your active theme.
| Option | Description |
| ----------- | ---------------------------------------------------------------------------------------------------- |
| **Default** | The standard background color for your current theme — no fill override. |
| **Dim** | A slightly darker fill that reduces visual noise and adds depth in dark mode. |
| **Warm** | A subtle warm tint (light orange in dark mode, soft cream in light mode) that softens the interface. |
### Patterns
Geometric repeating textures drawn at low opacity over your theme background.
| Option | Description |
| --------- | -------------------------------------------------------------------------- |
| **Dots** | A radial dot grid pattern. Works well with both dark and light themes. |
| **Grid** | A fine rectangular grid. Evokes a developer tool or graph-paper aesthetic. |
| **Waves** | A diagonal crosshatch. Adds subtle depth without being distracting. |
### Cosmos
Animated, deep-space backgrounds that replace the standard background entirely. Each Cosmos option renders a unique animated scene using rich colors and simulated starfields.
| Option | Description |
| ----------------- | ---------------------------------------------------------------------------- |
| **Cosmos** | Blue and purple nebula-style animation with pulsing star particles. |
| **Cosmos Yellow** | A warm solar scene with yellow and orange glows and a simulated starfield. |
| **Cosmos Red** | A red and rose nebula with deep crimson radial gradients and star particles. |
The Cosmos backgrounds — especially **Cosmos** (blue/purple) — give Voxcode a premium, cinematic feel that makes voice interactions feel more immersive. If you want to make an impression during demos or live sessions, start there.
# Voice Orb
Source: https://docs.voxcode.app/customization/voice-orb
Customize the animated Voice Orb that visualizes your speech in Voxcode
The Voice Orb is Voxcode's primary voice visualization. It's a real-time animated 3D object rendered with WebGL that reacts to your microphone input — scaling, rotating, and shifting color as you speak. When the AI responds, it can pulse in sync with the audio playback, giving you a continuous visual signal of the conversation state.
You can fully customize how the orb looks and behaves, or switch to a flat 2D waveform if you prefer a lighter visual style.
## Accessing voice display settings
All Voice Orb and waveform options are in the **Voice & Audio** section of Settings.
Tap the gear icon in the top-right corner of the app.
Find the **Voice & Audio** section. The **Display Style** selector is at the top.
Select **3D Orb** to use the Voice Orb, or **Classic** to use the flat 2D waveform. The options below the selector update to match your choice.
***
## Orb options
When you select **3D Orb** as your display mode, the following settings become available.
### Shape
Choose the 3D geometry the orb renders as. The shape is re-initialized each time you change this setting.
A smooth icosahedron mesh — the default shape. The high vertex count lets the audio-driven displacement shader produce fluid, organic ripples across the surface.
A box geometry. The metallic material and bloom post-processing give the cube sharp, reflective edges that deform subtly with your voice.
A triangular cylinder. The three-sided silhouette creates a distinctive prism form that rotates and pulses with audio input.
A dodecahedron (12-sided polyhedron). The flat faces create a faceted, gem-like appearance that catches the room-environment lighting.
A torus geometry with a thick circular cross-section. The hollow center produces a completely different silhouette and makes the audio reactions more visible from all angles.
### Style
Controls the shader applied to the orb surface.
| Style | Description |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| **Classic** | A dark metallic surface with blue-purple emissive highlights that glow when audio activity is detected. |
| **Blue** | An alternate shader with deeper blue tones and a cooler, more electric glow. |
### Mode
Controls how much of the screen the orb occupies when you are in a voice session.
| Mode | Description |
| -------- | ------------------------------------------------------------------------------------------- |
| **Half** | The orb renders in the bottom half of the screen. The chat area remains visible above. |
| **Full** | The orb fills the entire screen with a dark radial-gradient backdrop, hiding the chat view. |
### Vibration intensity
A slider from **1 to 5** that scales how dramatically the orb reacts to audio. At level 1, displacement is minimal. At level 5, the orb expands and distorts more aggressively in response to loud or energetic speech.
Level 3 is the neutral baseline. Levels below 3 produce subtler reactions; levels above 3 produce more exaggerated movement.
### Orb feedback
Available only in **Full** mode. When enabled, the orb continues reacting visually during AI speech playback, not just while you speak. Disable this if you want the orb to stay static while the AI responds.
### Bottom navbar
Available only in **Full** mode. When enabled, the bottom navigation bar remains visible over the full-screen orb. Disable it for a fully immersive, distraction-free view.
For the most vivid experience, start with the **Sphere** shape, **Blue** style, and vibration set to **4** or **5**. The blue shader combined with the smooth sphere geometry produces the most fluid audio reaction, especially on high-frequency speech.
***
## Classic waveform
If you select **Classic** as your display mode, the orb is replaced by a 2D canvas-based waveform drawn in real time from your microphone input.
### Waveform variants
| Variant | Description |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Bars** | Five rounded vertical bars that scale in height based on audio frequency bands. The central bar reacts most strongly to mid frequencies. |
| **String** | A horizontal sine wave that oscillates in amplitude based on audio loudness. The wave animates continuously even when the mic is silent. |
| **Circle** | A single circle that expands outward based on mic input. Louder audio produces a larger radius with a faint fill. |
| **Dots** | Five dots arranged horizontally that grow in size based on their respective frequency band. |
| **Spectrum** | Eight vertical bars spanning the full width, each mapped to a different frequency bin. Similar to a traditional audio spectrum analyzer. |
# General FAQ
Source: https://docs.voxcode.app/faq/general
Common questions about Voxcode — the voice-first AI coding assistant.
Voxcode is a voice-first AI coding assistant that lets you build, edit, and preview web applications using natural voice commands — no keyboard required. You speak your intent, and Voxcode generates code in real time with a live preview.
Voxcode is built for:
* **Mobile developers** who want to code on the go without a physical keyboard
* **Rapid prototypers** who think faster than they type
* **Developers of all skill levels** who want an AI pair-programmer they can talk to
You can also use text input if you prefer, so Voxcode works equally well on desktop.
Yes. Voxcode is designed mobile-first. The interface uses large tap targets, swipe gestures, and a responsive layout optimized for phones and tablets.
On mobile, you can swipe right to open your conversation history and swipe left to open the file explorer. Voice mode works hands-free: after you tap the microphone once, Voxcode keeps listening and automatically picks up your next command after each AI response — no need to tap again between turns.
Voxcode is also installable as a PWA (Progressive Web App), so you can add it to your home screen and launch it like a native app.
Voxcode connects to 15+ AI models via OpenRouter, organized into three tiers:
* **Free models** — Zero credit cost. Includes Gemini 2.5 Flash, Claude Haiku 4.5, Qwen 3 Coder Plus, OpenAI o4 Mini High, and more.
* **Beta models** — Experimental and cutting-edge. Includes Grok 4.1 Fast, GPT 5.1 Codex Mini, MiMo-V2-Flash (free), and others.
* **Premium models** — Most powerful. Includes Claude Sonnet 4.5, Claude Opus 4.5, Gemini 2.5 Pro, GPT 5.1 Codex, and Grok 3.
You can switch models at any time in the settings menu. If you have a Premium plan, you can also bring your own API key (BYOK) and use any model without consuming Voxcode credits.
Your code is saved automatically in your browser's `localStorage` via Voxcode's Virtual File System (VFS). Every file the AI generates — HTML, CSS, JavaScript, TypeScript, React components — is written to the VFS instantly and persists between sessions on the same device and browser.
Your conversation history and account data are stored securely in Voxcode's database. The VFS is local to your browser, so clearing your browser data will remove your project files. Use the export feature to download your code before clearing storage.
GitHub sync (push/pull from repositories) is coming soon. Check the roadmap for updates.
No. On the Free, Starter, and Premium plans, Voxcode handles all API access for you — you just sign in and start coding. Credits are deducted automatically based on the model you use.
If you are on the **Premium plan**, you have the option to bring your own API key (BYOK) from OpenRouter or another supported provider. When you use your own key, requests go directly to your provider and do not consume any Voxcode credits.
When your credit balance reaches zero, you will no longer be able to send requests to paid models. You can still use **Free models** (marked with `!` in the model selector), which cost zero credits regardless of your plan.
To continue using paid models, you can:
* **Top up credits** — Purchase a credit pack (40, 100, 200, or 420 credits) at any time. Top-up credits never expire.
* **Upgrade your plan** — Move to Starter ($7/month) or Premium ($15/month) for a larger monthly credit allowance.
* **Use BYOK** — On the Premium plan, add your own API key to bypass the credit system entirely.
Your monthly subscription credits reset each billing cycle. Unused subscription credits do not roll over, but purchased top-up credits do.
Yes. You can download any file or your entire project from the file explorer. Individual code blocks in the chat also have a copy button so you can grab specific snippets instantly.
Export your project before clearing browser storage or switching devices, since the VFS lives in your browser's `localStorage`.
Partially. The Virtual File System (VFS) is stored in your browser and remains accessible offline — you can view and browse your existing files without an internet connection.
However, AI code generation, voice transcription (Whisper), and voice synthesis (ElevenLabs) all require an active internet connection. Offline AI generation is not currently supported.
Voxcode works best in modern Chromium-based browsers:
* **Google Chrome** (recommended)
* **Microsoft Edge**
* **Brave**
Firefox and Safari have limited support for the Web Speech API used for voice input. If you experience issues with voice recognition on those browsers, Voxcode falls back to Whisper-based transcription where possible, but Chrome is recommended for the most reliable voice experience.
For the WebContainer preview (Node.js projects), you need a browser that supports SharedArrayBuffer, which requires a secure context (HTTPS).
Yes. The Free plan gives you **20 credits** to start and access to all Free-tier models (marked `!`), which cost zero credits per request. Free models include Gemini 2.5 Flash, Claude Haiku 4.5, Qwen 3 Coder Plus, and more — capable models that handle most coding tasks well.
If you need access to more powerful models or more credits, you can upgrade:
| Plan | Price | Credits/month | Models |
| ------- | ---------- | ------------- | ----------------------- |
| Free | \$0 | 20 (one-time) | Free models |
| Starter | \$7/month | 100 | Free + Beta + 2 Premium |
| Premium | \$15/month | 250 | All models + BYOK |
You can also purchase credit top-ups at any time on any plan.
Voxcode can generate code in any language or framework the underlying AI models support. Common use cases include:
* **HTML, CSS, JavaScript** — Static sites, landing pages, portfolios
* **React / JSX / TSX** — Component libraries, full React apps
* **TypeScript** — Typed components and utilities
* **Node.js** — Server-side scripts, Express apps, API routes
* **Vue, Svelte** — With appropriate preview setup
* **Python, SQL, Bash** — For scripting and data tasks (text output, no live preview)
The live preview system auto-detects your project type: static HTML/CSS renders in an iframe, React projects run in Sandpack, and Node.js projects boot in a WebContainer.
You can reach the Voxcode team at **[support@voxcode.app](mailto:support@voxcode.app)**. When reporting a bug, it helps to include:
* A description of what you expected to happen
* A description of what actually happened
* The browser and device you were using
* Any error messages visible in the chat or browser console
For feature requests and general discussion, you can also open an issue or start a thread on the Voxcode GitHub repository.
# Troubleshooting
Source: https://docs.voxcode.app/faq/troubleshooting
Fixes for common issues in Voxcode, organized by category.
If your issue isn't covered here, email **[support@voxcode.app](mailto:support@voxcode.app)** with a description of the problem, your browser and device, and any error messages you see. We'll get back to you as soon as possible.
Many state-related issues — stuck UI, audio that won't play, a preview that won't load — resolve by refreshing the browser tab. Try a hard refresh (`Ctrl+Shift+R` / `Cmd+Shift+R`) before working through the steps below.
## Voice issues
Voxcode needs microphone access to capture your voice. If the browser blocked the permission or never asked for it, follow these steps:
When you first click the microphone icon, your browser should show a permission prompt. If you accidentally denied it, you need to reset it manually.
Click the lock icon (or the camera/microphone icon) in the address bar. Set **Microphone** to **Allow**, then reload the page.
Go to **Settings → Site permissions → Microphone** and remove the blocked entry for Voxcode. Reload and try again.
On macOS, go to **System Settings → Privacy & Security → Microphone** and make sure your browser is listed and enabled. On Windows, go to **Settings → Privacy → Microphone** and confirm browser access is on.
Some video call apps (Zoom, Teams) hold an exclusive lock on the microphone. Quit those apps and try again.
If you are accessing Voxcode over HTTP (not HTTPS), the browser will block microphone access entirely. Make sure you are using the secure `https://` URL.
Transcription quality depends on your microphone, background noise, and the transcription engine in use.
**Try these steps:**
* Speak clearly and at a moderate pace. Voxcode uses the Web Speech API on desktop Chrome and Whisper as a fallback on mobile.
* Reduce background noise. A noisy environment can confuse the silence detector and cut you off early. Move to a quieter space or use a headset.
* Use a headset or external microphone instead of a built-in laptop mic.
* Switch to **Chrome** if you are on Firefox or Safari. Chrome's Web Speech API implementation is significantly more accurate for English.
* If you have a strong accent or speak a language other than English, Whisper (the mobile fallback) handles multilingual transcription better than the Web Speech API.
If transcription is consistently wrong for specific technical terms (e.g., framework names, function names), try spelling them out or using text input for those parts.
If you finish speaking but the AI never replies, work through these checks:
Look in the chat for your transcribed message. If it appears but there is no AI reply, the issue is with the AI request, not transcription.
If your credits are at zero and you are not using a Free-tier model, the request will fail silently. Check your balance in the settings menu and top up or switch to a Free model.
AI generation requires a live connection to OpenRouter. Verify you are online and not behind a firewall that blocks API calls.
Open DevTools (`F12`), go to the **Console** tab, and look for red error messages. A 401 error means an API key issue; a 429 means you are rate-limited; a 500 means a server-side problem.
A hard refresh clears in-memory state that can cause the AI pipeline to stall. If the issue persists across refreshes, contact support.
Voxcode supports interrupting the AI mid-response by speaking. If your speech is not stopping the AI, check the following:
* **Microphone must remain active** — Interruption only works while you are in continuous voice mode (microphone icon is active/lit). If you have stopped the mic, you cannot interrupt.
* **Speak at a clear volume** — Voxcode needs to detect your voice above background noise. Quiet speech or whispering may not trigger the interrupt. Speak at a normal conversational volume.
* **Browser audio policy** — Some browsers block auto-playing audio until you interact with the page. If the AI's voice is not playing at all, click anywhere on the page first, then restart voice mode.
* **Check for browser extensions** — Ad blockers or privacy extensions can intercept audio APIs. Try in an incognito window with extensions disabled.
## Preview issues
A blank preview usually means the VFS doesn't have the right entry-point file, or the project type wasn't detected correctly.
Open the file explorer (swipe left on mobile, or click the file icon). Check that your project files — especially `index.html` for static sites or `App.tsx` / `package.json` for React — are present.
Say or type: *"Save the files and show me a preview."* Voxcode needs the AI to emit code blocks with filenames (e.g., ` ```html:index.html `) to write them to the VFS. A response with code but no filename won't be saved.
Click the refresh icon inside the preview window. This reloads the preview without resetting your chat session.
If the preview panel itself is stuck, do a full page refresh (`Ctrl+Shift+R`). Your VFS files are stored in `localStorage` and will survive the refresh.
React projects run inside Sandpack (an in-browser code execution environment). Common error causes:
* **Missing dependency** — If the AI used a package not included in Sandpack's default bundle, you'll see a module-not-found error. Ask the AI: *"Rewrite this using only standard React, no external libraries."*
* **TypeScript error** — Sandpack compiles TypeScript but strict type errors will block rendering. Ask the AI to fix the type errors or switch to `.jsx` instead of `.tsx`.
* **Syntax error in generated code** — Occasionally the AI produces slightly malformed code. Ask: *"Fix the syntax errors in the current code"* and Voxcode will regenerate.
* **`package.json` conflict** — If your VFS contains a malformed `package.json`, Sandpack will fail to initialize. Ask the AI to regenerate a clean `package.json`.
Check the error message shown in the Sandpack console panel — it usually points to the exact file and line causing the problem.
WebContainer runs Node.js entirely in the browser and has specific requirements:
* **Browser support** — WebContainer requires SharedArrayBuffer, which is only available in secure contexts (HTTPS) and in Chrome, Edge, or Brave. It does not work in Firefox or Safari.
* **Secure context required** — The page must be loaded over HTTPS for WebContainer to initialize. If you see a security-related error, make sure you are accessing Voxcode at the `https://` URL.
* **First boot is slow** — On the first load, WebContainer downloads a Node.js runtime. This can take 10–30 seconds on slower connections. Wait for the loading indicator to complete before interacting.
* **`package.json` must be valid** — An invalid or empty `package.json` will cause the container to fail. Ask the AI to generate a fresh one if needed.
WebContainer does not work behind corporate proxies that block WebSocket connections. If you are on a restricted network, use a static HTML/CSS or React project instead.
If you asked the AI to modify your code but the preview still shows the old version:
* **Check the VFS** — Open the file explorer and verify the file was actually updated. The AI must emit a new code block with the filename for changes to save.
* **Click refresh in the preview panel** — The preview doesn't always hot-reload automatically after a VFS write. Click the refresh icon to force a reload.
* **Confirm the AI targeted the right file** — If you have multiple files, the AI may have created a new file instead of updating the existing one. Check the file explorer for duplicates.
* **Re-prompt with the filename** — If the AI keeps generating code without saving it, say: *"Update `index.html` with the changes."* Specifying the filename explicitly helps the AI write to the correct VFS path.
## Credits & account issues
Credits are consumed per request based on the number of input and output tokens. Long conversations accumulate context, which increases input token counts over time. A single request on a premium model with a large context window can cost noticeably more than a short one.
**To reduce credit consumption:**
* Switch to a Free-tier model (Gemini 2.5 Flash, Claude Haiku 4.5, etc.) for exploratory or simple tasks.
* Start a new conversation to reset context rather than continuing a very long thread.
* Use fast models for quick questions and reserve premium models for complex generation tasks.
You can view your full usage history in the settings menu to see which requests consumed the most credits. Top up at any time — purchased credits never expire.
BYOK is available on the **Premium plan** only. If your key isn't working:
BYOK is not available on Free or Starter. Check your plan in account settings.
Go to **Settings → API Keys**, remove the existing key, and re-enter it. API keys are encrypted before storage, so a copy-paste error won't be visible.
Make a test request directly against OpenRouter or your provider's API to confirm the key is active and has credits/quota remaining.
A key from one provider won't work for a model from a different provider. Make sure the model you have selected is accessible via the key you entered.
If the problem persists, contact **[support@voxcode.app](mailto:support@voxcode.app)** with your account email and the provider you are trying to use (do not include the key itself).
Voxcode uses OAuth for sign-in. If sign-in fails:
* **Pop-up blocked** — Your browser may have blocked the OAuth pop-up. Allow pop-ups for Voxcode's domain and try again.
* **Cookies disabled** — NextAuth requires cookies for session management. Ensure cookies are not blocked for Voxcode's domain in your browser settings.
* **Third-party cookie restrictions** — Some browsers (Safari, Firefox in strict mode) block third-party cookies by default. Add Voxcode to your exceptions list or switch to Chrome.
* **Account already exists** — If you previously signed in with Google and now try GitHub (or vice versa) using the same email address, you may hit a conflict. Contact support to merge accounts.
* **Corporate SSO conflict** — If your Google or GitHub account is managed by an organization, that organization's IT policy may block OAuth access from third-party apps. Try a personal account.
After completing a purchase, your credit balance should update within a few seconds. If it doesn't:
A hard refresh (`Ctrl+Shift+R`) forces the app to re-fetch your account state from the server.
This clears the local session cache and re-loads your account data, including the updated credit balance.
Payment webhooks occasionally take up to 2 minutes to process. Wait briefly, then refresh.
If your balance still hasn't updated after 5 minutes, email **[support@voxcode.app](mailto:support@voxcode.app)** with your account email and the purchase receipt. We will apply the credits manually.
## Performance issues
Response latency depends on the model you have selected, your internet connection, and current server load. Here's what you can do:
* **Switch to a faster model** — Models like Gemini 2.5 Flash (`~600ms`), MiMo-V2-Flash (`~500ms`), and Grok 4.1 Fast (`~800ms`) are optimized for speed. For voice interactions especially, these models deliver a noticeably snappier experience.
* **Start a fresh conversation** — Very long conversations accumulate context that the model must process on every request. Starting a new chat for a new task reduces input token counts and speeds up responses.
* **Check your connection** — Run a speed test. Voxcode streams responses in real time, so a high-latency connection will delay time-to-first-token even if bandwidth is adequate.
* **Avoid peak hours** — Like all cloud AI services, response times can vary with server load. If speed is critical, try off-peak times.
Voxcode uses streaming TTS: the AI's voice response begins playing as soon as the first sentence is complete, without waiting for the full response. If audio feels delayed, this is usually a network issue rather than a processing issue.
Voxcode is built mobile-first, but demanding hardware can still struggle with certain features:
* **Disable the 3D Voice Orb** — The animated orb uses WebGL canvas rendering, which is GPU-intensive. Go to **Settings → Voice Display** and switch to the classic waveform mode. This significantly reduces CPU and battery usage on lower-end devices.
* **Close other browser tabs** — Mobile browsers share memory across tabs. Close unused tabs to free up RAM for Voxcode.
* **Use a lighter chat background** — Animated cosmos backgrounds have a higher rendering cost than solid or pattern backgrounds. Switch to a solid background in **Settings → Chat Background**.
* **Install Voxcode as a PWA** — Adding Voxcode to your home screen and running it as a standalone PWA can improve performance by removing the browser chrome overhead.
* **Clear browser cache** — Over time, accumulated cache data can slow down `localStorage` reads and writes. Clear your site data for Voxcode (note: this will also clear your VFS, so export your files first).
# AI Models
Source: https://docs.voxcode.app/features/ai-models
Choose the right AI model for your coding tasks in Voxcode
Voxcode gives you access to 15+ AI models from Anthropic, Google, OpenAI, xAI, and others — all through a single interface. Models are organized into three tiers based on cost and capability, and you can switch between them at any time from the model selector.
## Model tiers
No credit cost. Great for everyday coding tasks, quick questions, and exploring the platform. Available on all plans including the free tier.
Experimental and cutting-edge models. Some are free, others consume credits. Unlocked on the Starter plan and above.
The most powerful models for complex tasks. Higher credit cost per request. Unlocked on the Starter plan (2 models) and fully available on the Premium plan.
## Available models
### Free models (!)
These models consume zero credits.
| Model | Notes |
| ---------------------- | -------------------------------------- |
| Gemini 2.5 Flash | Fast and capable for most coding tasks |
| Gemini 3 Flash Preview | Next-generation Flash, preview access |
| Qwen 3 Coder Plus | Optimized for code generation |
| Claude Haiku 4.5 | Anthropic's fastest model |
| OpenAI o4 Mini High | Reasoning-focused, efficient |
| Qwen 3 Max | High-capacity general-purpose model |
| Cogito V2 Llama 405B | Large open-weight model |
### Beta models (\*)
| Model | Credit cost (avg per request) | Notes |
| --------------------- | ----------------------------- | ---------------------- |
| MiMo-V2-Flash | Free | No credit cost |
| GPT-OSS-120B | Free | No credit cost |
| GPT-OSS-120B (paid) | \~0.0015 credits | Higher throughput tier |
| Grok 4.1 Fast | \~0.004 credits | Fast inference |
| GPT 5.1 Codex Mini | \~0.015 credits | Code-focused, compact |
| Nex AGI Deepseek V3.1 | \~0.008 credits | Strong reasoning |
| MiniMax M2.1 | \~0.009 credits | Multimodal capable |
| GPT 5.1 Codex | \~0.076 credits | Full Codex model |
### Premium models (\$)
| Model | Credit cost (avg per request) | Best for |
| -------------------- | ----------------------------- | --------------------------------- |
| GPT 5.1 Codex | \~0.076 credits | Complex code generation |
| Gemini 2.5 Pro | \~0.076 credits | Long context, multi-file projects |
| Gemini 3 Pro Preview | \~0.091 credits | Latest Google flagship |
| Claude Sonnet 4.5 | \~0.114 credits | Balanced power and speed |
| Grok 3 | \~0.114 credits | Strong reasoning and coding |
| Claude Opus 4.5 | \~0.19 credits | Most capable for hardest tasks |
## Switching models
Open the model selector by tapping the model name badge at the bottom of the screen. A menu slides up with three tabs — **Beta**, **Free**, and **Premium** — plus a **BYOK** tab if you want to use your own API keys.
Tap the model name displayed near the bottom center of the screen. The selector panel opens above the input bar.
Select **Beta**, **Free**, or **Premium** to filter models by tier. Models you do not have access to on your current plan are indicated.
Tap any model in the list. The selector closes and your next message will use the selected model. Your choice persists across the session.
## Smart routing: lite vs. full prompts
Voxcode automatically decides how much context to send with each request based on query complexity.
* **Simple queries** — short questions, quick edits, single-line changes — use a **lite system prompt**. This reduces the token count and makes responses significantly faster.
* **Complex queries** — multi-file generation, architecture questions, component scaffolding — use the **full system prompt**, which includes complete project context and detailed instructions.
You do not need to configure this. Voxcode evaluates each request and routes it accordingly.
## Prompt caching
When you continue an existing conversation, Voxcode uses prompt caching to avoid re-processing the same context on every message. Repeat conversations and iterative sessions are **30–50% faster** than a fresh start, and consume fewer credits because the cached portion of the prompt is not re-billed at full rate.
Free models are available on all plans. Beta models (excluding the two free Beta models) require a **Starter** plan or higher. Premium models require a **Starter** plan for limited access (2 models) or a **Premium** plan for full access. See [Plans & Pricing](/plans/overview) for a full breakdown.
Start with a free model like **Gemini 2.5 Flash** or **Claude Haiku 4.5** to test your prompts and workflow. Once you have a prompt style that produces good results, you can switch to a premium model for the final, more complex work — and spend credits only where it matters.
# Live Preview
Source: https://docs.voxcode.app/features/live-preview
See your code running live as you build in Voxcode
Every project you build in Voxcode can be previewed instantly without leaving the browser. Voxcode detects what kind of project you are working on and chooses the right rendering engine automatically — from a simple static iframe to a full Node.js WebContainer.
## Opening the preview
Click the **Preview** button in the chat interface. Voxcode reads all files from the Virtual File System, detects your project type, and renders the output in a preview window.
Ask the AI to create a project — a landing page, a React component, a Node.js server. The generated files are automatically saved to the VFS.
Tap or click the **Preview** button. Voxcode reads all your project files from the Virtual File System, detects the project type, and opens the preview window.
Your project renders immediately. For static HTML, the iframe appears in under a second. For React and Node.js projects, the appropriate sandbox environment initializes and renders the output.
## Automatic project detection
Voxcode reads your VFS files and selects a rendering engine based on what it finds. You do not need to configure this.
| Project type | Detection rule | Rendering engine |
| ---------------- | ----------------------------------------------------------- | ----------------------------------------------- |
| Static HTML/CSS | `index.html` exists, no `package.json` | **iframe** — instant, no build step |
| Vanilla JS | `index.html` with `