Unofficial local-first desktop workspace for the Venice API.
Chat, image generation, media workflows, research, characters, prompts, projects, and local creative asset management.
Important
Venice Forge is unofficial.
Venice Forge is an independent, third-party desktop client for the Venice API. It is not affiliated with, endorsed by, sponsored by, or maintained by Venice.ai, Inc.
Venice names, marks, API references, and compatibility language are used only for nominative identification. Official Venice brand assets remain the property of Venice.ai, Inc. This project's MIT License covers only the original code and documentation in this repository.
A Venice API key is required for live model discovery, chat, generation, research, and provider-backed workflows.
Warning
User responsibility required.
Venice Forge is a local desktop client for external AI services. Users are responsible for their own prompts, generated content, storage choices, exports, and compliance with applicable laws and provider terms.
Do not use this project to create, request, store, distribute, or facilitate child sexual exploitation material, non-consensual sexual content, harassment, doxxing, illegal instructions, or other unlawful abuse.
Note
Venice Forge is maintained against the Node 22 validation matrix documented below. Before publishing release artifacts, run the full CI gate and the platform-specific packaging verifier for the target OS.
-
Download a build from GitHub Releases.
Windows:
Venice-Forge-<version>-x64-Setup.exeVenice-Forge-<version>-x64-Portable.exe
macOS:
Venice-Forge-<version>-arm64.dmgVenice-Forge-<version>-x64.dmg
Linux, when CI artifacts are available:
- AppImage
.deb.rpm
-
Install and launch Venice Forge.
-
Open Config.
-
Add your Venice API key.
-
Test the connection.
-
Start using Chat, Image Studio, Media Studio, Research, Characters, RP Studio, Workflows, and local workspace tools.
Venice Forge is a local-first creative desktop workspace for the Venice API.
Core capabilities:
- Streaming AI chat
- Persistent conversations and local chat history
- Image generation, editing, combining, upscaling, and recipe reuse
- Media gallery with metadata, lineage, export, compare, tagging, favorites, and project scoping
- Prompt Library with versioning, import/export, project/global scope, favorites, archives, and secret filtering
- Research workspace using Venice and optional Jina-backed search/scrape flows
- Character browsing and character chat using Venice-hosted characters
- Optional character chat scene generation (manual on-demand or automatic marker-based) scoped to the current conversation
- Local RP Studio for character cards, personas, scenarios, lorebooks, prompt stacks, and scene context
- Scene Composer for reusable image prompt components
- Workflow templates and visual workflow execution planning
- Audio transcription and text-to-speech
- Music generation
- Video generation and video upscaling job queues
- Embeddings generation
- Theme editor and token-based custom themes
- Secure desktop API-key handling through OS secure storage
- Local storage diagnostics, import/export, and privacy tooling
| Area | Purpose |
|---|---|
| Chat | Streaming conversations, system prompts, attachments, persistent history, memory injection, chat forking, Agent/Classical mode controls, and optional character-bound scene generation |
| Image Studio | Image generation, editing, multi-image combine/reference flows, upscaling, model-aware controls, seed handling, negative prompts, styles, steps, and capabilities display |
| Media Studio | Search, filter, inspect, tag, favorite, export, compare, bulk-select, assign to project, trace lineage, reuse recipes, regenerate, remix, upscale, and route media into other studios |
| Prompts | Prompt Library with version chains, tags, favorites, archives, safe import/export, and apply/save handoffs across Chat, Image Studio, Media Studio, Research, and workflows |
| Audio Studio | Text-to-speech and Whisper transcription |
| Music Studio | Text-to-music generation, lyrics, duration control, and instrumental mode |
| Video Studio | Async text-to-video, image-to-video, video-to-video, reference-to-video, and video-upscale queues |
| Embeddings | Text embedding generation with model and dimension visibility |
| Research | Venice/Jina search, scraping, public-profile discovery, persistent research sessions, findings, sources, citations, and summaries |
| Characters | Browse Venice-hosted characters and start character chats with venice_parameters.character_slug |
| RP Studio | Local character authoring/runtime with personas, lorebooks, scenarios, multi-character chats, scene image generation, and prompt assembly tracing |
| Scene Composer | Reusable scene components compiled into generation-ready recipes |
| Workflows | Visual and template-based model chains for multi-step creative tasks |
| Playground | Conversational workflow builder/editor with a live canvas |
| Config | API keys, model defaults, local config, themes, data import/export, secure-store controls, and diagnostics |
| Status | Runtime info, transport mode, rate-limit headers, logs, and sanitized diagnostics |
The canonical tab registry lives in:
src/config/tabs.ts
Some legacy items, such as model catalog and batch prompting, are exposed as Config sub-views rather than separate top-level tabs.
Venice Forge supports both desktop and web-mode development.
Electron main process
├─ OS secure storage for API keys
├─ IPC request validation
├─ HTTPS Venice/Jina client boundaries
├─ local chat-history filesystem access
└─ packaging/runtime integration
React renderer
├─ studios and workspace UI
├─ encrypted IndexedDB stores
├─ local project/media/prompt/research state
└─ no raw API-key access
React renderer
└─ Express proxy server
├─ .env API key access
├─ Venice/Jina request validation
└─ provider response screening
Core invariants:
- Renderer does not receive raw desktop API keys.
- Desktop keys are stored through OS secure storage.
- Web-mode Venice keys live in server-side
.env. - Venice and Jina requests pass through allowlisted, validated request paths.
- Local Family Safe Mode is separate from provider-side Venice safe-mode parameters.
- Family Safe Mode is local and privacy-preserving in scope: it performs no network moderation calls, blocked request text is not sent upstream, and blocked Jina/scrape response text is not returned to the renderer.
- Secret-like values are stripped from safe exports and diagnostics.
- Prompt text is not logged.
- No telemetry or analytics are collected by Venice Forge.
- External URL opening is constrained by trusted URL validation.
Read:
| Concern | Canonical location |
|---|---|
| Tab registry | src/config/tabs.ts |
| Desktop main process | electron/ |
| Renderer application | src/ |
| Local storage services | src/services/ |
| Theme system | src/theme/, src/styles/, docs/design/THEME_SYSTEM.md |
| Release workflow | .github/workflows/ |
| Release documentation | docs/RELEASE/ |
| Security policy | SECURITY.md |
| Privacy documentation | docs/legal/PRIVACY.md |
| Current audit ledger | docs/summary_of_work.md |
| Historical audit reports | docs/reports/historical/ |
| Requirement | Version / Notes |
|---|---|
| Node.js | 22.13+ |
| npm | 10+ |
| Windows | Windows 10/11 |
| macOS | macOS 13+ |
| Linux | Experimental; release packaging handled by CI |
| Venice API key | Required for live API usage |
| Jina API key | Optional, used for Jina-backed research/search flows |
Clone and install:
git clone https://github.com/spearchucker667/Venice_Forge.git
cd Venice_Forge
npm ci
npm run dev:electronWeb-mode development:
npm run devOr run the two processes separately:
npm run dev:server
npm run dev:webThe Vite renderer proxies /api/* to http://127.0.0.1:3000 by
default. Set VITE_API_PROXY_TARGET when the Express proxy uses a
different host or port.
Venice Forge can be configured from the app UI or from local YAML files.
Initialize local config templates:
npm run config:initValidate local config:
npm run config:validatePrint the sanitized effective config:
npm run config:printPlaintext API keys placed in local YAML are imported into OS-level secure storage on startup and then redacted from the file.
Read:
Web mode uses .env.
Copy the template:
cp .env.example .envCommon values:
VENICE_API_KEY="your-venice-inference-key"
PORT=3000
HOST=127.0.0.1
NODE_ENV=development
VENICE_FORGE_DEBUG_DEVTOOLS=false
VENICE_FORGE_ALLOW_PLAINTEXT_KEY_STORAGE=falseNotes:
- Desktop Venice keys are stored through OS secure storage.
- Web-mode Venice keys belong in the Express server
.env. - Desktop Jina keys are stored through OS secure storage.
- Web-mode Jina credentials belong in the Express server
.env; renderer-suppliedAuthorizationandx-jina-api-keyvalues are dropped by the proxy. - Never commit
.env, local config files containing secrets, generated logs, release artifacts, or exported private workspace data.
| Command | Purpose |
|---|---|
npm run dev:electron |
Start Electron app with live reload |
npm run dev:web |
Start Vite renderer only; /api/* proxies to Express |
npm run dev:server |
Start Express proxy only |
npm run dev |
Start server + web renderer |
npm run lint:eslint |
Run ESLint |
npm run typecheck |
TypeScript check for renderer and Electron code |
npm test |
Run Vitest suite |
npm run test:watch |
Run tests in watch mode |
npm run build |
Build production renderer/main output |
npm run clean |
Remove generated output |
npm run verify:safety-guard |
Verify local safety guard enforcement |
npm run verify:markdown-links |
Validate local Markdown links and heading fragments |
npm run verify:workspace-contracts |
Verify workspace/project/recipe contracts |
npm run verify:model-aware-recipes |
Verify model-aware image controls and recipe compatibility |
npm run verify:media-studio-power-tools |
Verify Media Studio bulk/compare/lineage/export/handoff contracts |
npm run verify:prompt-library |
Verify Prompt Library data/UI/import/export contracts |
npm run verify:storage-privacy |
Verify storage/privacy dashboard contracts |
npm run verify:contracts |
Run the aggregate contract verifier suite |
npm run verify:release-packaging-hardening |
Verify release, CI, packaging, artifact, and dist hygiene invariants |
npm run verify:archive-clean |
Fail on tracked archive/build/secret contaminants |
npm run verify:dist |
Verify build outputs after npm run build |
npm run ci |
Run the full local CI parity chain |
npm run profile:media-studio |
Profile encrypted Media Studio storage behavior |
For the complete command list:
cat package.jsonBefore opening a PR, tagging a release, or publishing artifacts, run:
npm run clean
npm ci
npm run lint:eslint
npm run typecheck
npm test
npm run verify:contracts
npm run verify:archive-clean
npm run build
npm run verify:dist
npm run ciIf any command fails, treat the failure as release-blocking until the root cause is understood.
npm run clean
npm ci
npm run build
npm run dist:win
npm run checksum:release
npm run verify:dist:winExpected outputs in release/:
Venice-Forge-<version>-x64-Setup.exe
Venice-Forge-<version>-x64-Portable.exe
npm run clean
npm ci
npm run build
npm run dist:mac
npm run checksum:release
npm run verify:dist:macExpected outputs in release/:
Venice-Forge-<version>-arm64.dmg
Venice-Forge-<version>-arm64.zip
Venice-Forge-<version>-x64.dmg
Venice-Forge-<version>-x64.zip
Linux release artifacts are produced by CI when configured:
AppImage
.deb
.rpm
Linux support is strictly experimental and community-supported. Local cross-building from Windows/macOS is not maintained. Build on a Linux runner for reliable Linux packages.
Local builds are unsigned by default.
Expected behavior:
- Windows may show SmartScreen warnings.
- macOS may show Gatekeeper warnings.
- Official release signing depends on configured release workflow credentials.
macOS local-build quarantine workaround:
xattr -dr com.apple.quarantine "/path/to/Venice Forge.app"Read:
| Data | Location | Protection |
|---|---|---|
| Desktop API keys | macOS Keychain / Windows DPAPI | OS secure storage |
| Web-mode Venice key | Express server .env |
Server-side only |
| Logs | Application support directory | Plain text, local disk |
| Desktop chat history | chat-history/*.json |
Plain text JSON in user profile |
| Settings | IndexedDB | AES-GCM through app storage service |
| Conversations | IndexedDB | AES-GCM through app storage service |
| Memories | IndexedDB | AES-GCM through app storage service |
| Files and attachments | IndexedDB | AES-GCM through app storage service |
| Images/videos/media metadata | IndexedDB | AES-GCM through app storage service |
| Character cards/personas/lorebooks/RP assets | IndexedDB | AES-GCM through app storage service |
| Prompts/research/scenes/workflows | IndexedDB | AES-GCM through app storage service |
| Exports | User-selected path | Versioned JSON; secret-like fields stripped |
Encryption scope:
- IndexedDB-backed encrypted stores are protected by
src/services/storageService.ts. - Desktop
chat-history/*.jsonfiles are plaintext because the Electron main process does not always have a stable cross-platform key path at load time. - Browser-managed AES-GCM reduces casual disk inspection risk but does not protect against malware, active XSS, browser compromise, same-user OS compromise, or process-memory access.
Import/export behavior:
- JSON schema validation
- Size limits
- Backup-before-import
- Merge by ID
- Secret stripping before export
- Future-version rejection where applicable
Venice Forge includes local safety controls, but users remain responsible for their use of the application and provider endpoints.
Current guard contract:
- Family Safe Mode is a local, on-device guardrail. It is enabled by default, but it is not a complete protection guarantee.
- Supported prompt-like request fields are screened before provider dispatch.
- Jina/scrape text responses are screened locally before the renderer sees them; large bodies are sampled against the first 8 KiB.
- Aggregate audit counters record counts plus last timestamp/reason metadata only; they do not store raw prompt text or blocked raw response content.
Report abuse or security concerns through the appropriate channel:
- Child exploitation / CSAM: NCMEC CyberTipline
- Venice.ai Trust & Safety: venice.ai/support
- Venice Forge vulnerabilities: GitHub private vulnerability reporting for this repository
Security policy:
Venice Forge uses named regression guards to prevent accidental weakening of security, persistence, packaging, accessibility, privacy, and workspace contracts.
Canonical audit and guard documentation lives in:
- docs/summary_of_work.md
- docs/DOCS_INDEX.md
- docs/audits/repository-todo-roadmap-current.md
- docs/reports/historical/FINAL_MASSIVE_BUG_HUNT_WITH_PROOF.md
- docs/reports/historical/DOCS_CANONICALIZATION_AND_STALE_PRUNE.md
- docs/reports/historical/AUDIT_FOLLOWUP_2026_06_05.md
- docs/reports/historical/POST_VENICE_JINA_AUDIT_2026_06_06.md
Run the high-level verification suite:
npm run typecheck
npm test
npm run verify:safety-guard
npm run verify:markdown-links
npm run verify:release-packaging-hardening
npm run verify:contractsFor maintainer guidance on adding new endpoints safely, testing safety changes, and fixture hygiene, see SECURITY.md.
Venice Forge includes a token-based theme system.
Built-in themes include:
- Forge Graphite
- Forge Daylight
- Forge Copper
- Forge Dracula
- Venice Parity Dark
- GruvBox Dark
- Rosé Pine
Theme features:
- Runtime CSS token application
- WCAG-aware semantic pairs
- Live Theme Maker
- YAML import/export
- Encrypted custom-theme persistence
- Legacy theme compatibility paths
| Symptom | Fix |
|---|---|
| Missing app icon | npm run generate:icon && npm run verify:icon |
| Packaging fails | npm run clean && npm ci && npm run build before packaging |
| SmartScreen or Gatekeeper warning | Expected for unsigned local builds |
| No API key prompt | Open Config, save key, test connection |
| Chat history not loading | Inspect chat-history; corrupted files are backed up as .backup-{timestamp} |
400 from chat/image requests |
Verify selected model and payload parameters |
401 / 403 |
Verify API key validity and scope |
429 |
Check reset information in Status |
| Research provider failure | Check Venice/Jina config, provider limits, and logs |
| Transport failure | Open Status, export sanitized diagnostics, inspect logs folder |
| Markdown badge error | Verify workflow path, release/tag existence, or use a static badge |
| Release artifact missing | Confirm the tag, workflow run, packaging target, and GitHub Release upload step |
Read:
- docs/ABOUT.md — architecture, modes, security posture
- docs/FAQ.md — common questions
- CONTRIBUTING.md — contribution workflow
- docs/DEVELOPMENT/building.md
- docs/DEVELOPMENT/platform-support.md
- docs/DEVELOPMENT/troubleshooting.md
- docs/DEVELOPMENT/macos.md
- Local builds are unsigned unless signing credentials are configured.
- Auto-update behavior depends on release workflow configuration and GitHub Releases.
- Desktop chat-history files are plaintext JSON.
- IndexedDB encryption is not a malware/XSS/browser-compromise boundary.
- Same-user OS compromise and process-memory access are outside the local threat model.
- Linux packaging is CI-oriented; local cross-builds are not supported.
- Provider behavior, available models, model capabilities, and API limits may change upstream.
- Family Safe Mode is a local guardrail, not a legal/compliance guarantee.
- Family Safe Mode coverage is explicit, not automatic. New prompt-carrying endpoints and new scrape/response paths must be wired and tested intentionally.
- Jina/scrape response-body screening samples only the first 8 KiB of text.
- Release badges only reflect the configured badge source; static badges must be updated when the release version changes.
Contributions are welcome.
Before opening a pull request:
npm run typecheck
npm test
npm run verify:markdown-links
npm run verify:contracts
npm run verify:archive-cleanRead:
Use:
- GitHub Issues for bugs and feature requests
- GitHub private vulnerability reporting for security issues
- docs/SUPPORT.md for support routing
Active work is tracked in:
Current priorities:
- Workspace/project cohesion
- Media recipe and lineage improvements
- Research session polish
- Prompt/scene/workflow reuse
- Storage/privacy dashboard hardening
- Release packaging hardening
- Documentation canonicalization
- Test coverage expansion
- Accessibility and keyboard-navigation polish
- Security and safety regression coverage
Venice Forge is an unofficial, independent, third-party client for the Venice API.
It is not:
- affiliated with Venice.ai, Inc.
- endorsed by Venice.ai, Inc.
- sponsored by Venice.ai, Inc.
- maintained by Venice.ai, Inc.
- an official Venice product
Venice names, marks, API references, and brand assets belong to Venice.ai, Inc. They are referenced only for nominative compatibility identification.
Review:
Venice Forge credits the openvenice repository and its creator, nikshepsvn, for UI, workflow, studio-layout, and conceptual inspiration.
Venice Forge remains a separate custom codebase and integration engine, not a direct port.
Built with:
Powered by the Venice API.
This project is licensed under the MIT License.
The MIT License does not grant rights to Venice.ai trademarks, logos, brand assets, API terms, or third-party materials.
Venice Forge is not affiliated with Venice.ai, Inc.