Character Studio Documentation ← Table of Contents

← Table of Contents

Your First Project

Get from a blank browser tab to your first character conversation.

• Before You Begin
• Storage Modes: Choosing Where to Keep Your Project
• Creating Your First Project
• What Gets Created
• Your First Conversation
• What to Do Next

Before You Begin

Character Studio is an authoring environment, not a finished product you can just open and use. It needs a connection to a language model to power your characters. Before you create a project, you'll need an API key from Venice.AI — or from any provider with an OpenAI-compatible API.

Click the Settings button in the application header. Two fields are essential:

• API Key — Paste your Venice.AI key here. It's stored in your browser's localStorage, never sent anywhere except the API endpoint you configure.
• Model — The language model to use for your character's responses. Click the Browse button next to this field to fetch the list of models available on your account and choose one. A mid-tier chat model is a good starting point; you can always change it per-project later.

You'll also see a Base URL field, which defaults to Venice.AI's API endpoint. If you want to connect to a different provider — OpenAI, a local Ollama instance, or any other OpenAI-compatible service — change this URL and supply the corresponding key. Character Studio has no hardcoded dependency on Venice specifically; it works with any endpoint that speaks the OpenAI chat completions format.

Storage Modes: Choosing Where to Keep Your Project

Before you create a project, it helps to understand that Character Studio offers two completely different storage backends, and the one you choose has real implications for how you work. There's no wrong answer, but they're suited to different workflows.

Local Folder (File System Access API)

When you choose Local Folder, your project is a real directory on your computer — the same as any other folder you'd create in Windows Explorer or macOS Finder. Character Studio reads from and writes to files in that folder directly, using the browser's File System Access API.

This means your project files are plain text. You can open instructions.txt in VS Code, sync the folder with Dropbox or Google Drive, back it up with Time Machine, commit it to a Git repository, or rename files with your OS file manager. Everything Character Studio writes is a human-readable .txt or .json file. Nothing is hidden inside a database.

The trade-off is a small access-permission prompt. Because browsers treat File System Access as a sensitive capability, you'll be asked to re-confirm access to the folder once per browser session. This is a browser security requirement, not a Character Studio limitation. The prompt appears when you re-open the project, not constantly during use.

Best for: power users, anyone who wants to run git version control CLI themselves, synced cloud backups, or the ability to edit files outside the app.

Browser Storage (OPFS)

When you choose Browser Storage, your project lives entirely inside the browser's Origin Private File System — a sandboxed storage area managed by the browser itself. No file picker ever appears. The project is created instantly and is available every time you open Character Studio in the same browser on the same device.

This is the most frictionless path: you open the app, click New Project, and you're in. There's nothing to install and no folder to manage. It works on any operating system and tends to be more reliable on Firefox and Safari, where File System Access support varies.

The trade-off is opacity. Your files are invisible to the rest of your computer. You can't browse them in a file manager or open them in another app without explicitly exporting them. Download a zip backup regularly (the Export button in the project list does this) to protect your work — if you clear site data in your browser, OPFS projects are gone.

Best for: casual use, convenience-first workflows, users on operating systems or browsers with limited File System Access support.

Moving Between Modes

You're not locked in at creation time. The Move to Browser / Move to Disk button in the project controls lets you migrate a project from one storage backend to the other at any time. All your files, conversations, and images come along.

Creating Your First Project

With your API key set and a storage mode in mind, you're ready to create a project. "Project" and "character" are used interchangeably in the UI — each project is one character definition along with all its conversations, images, and configuration. This maps to the concept of a "character" in Venice.AI, but your project contains all of the files Venice needs and much more for its own use (hence "project").

• 1 Click New Project in the top toolbar. A dialog appears asking for a character name.
• 2 Type a name for your character — for example, Aria. This becomes the folder name and the display name in the project list.
• 3 Choose a storage mode. Click Local Folder to pick a folder on your computer, or Browser Storage to create the project instantly in the browser.
• 4 For Local Folder: your operating system's folder picker opens. Navigate to where you want the project to live, create a new folder if needed (name it anything — the project name and folder name don't have to match), and click Select. Character Studio creates all the starter files inside that folder.
• 5 The project loads. You'll see the file tabs on the left side of the screen — Instructions, System Prompt, Description, Intro, Context, Photos — and the chat panel on the right. The project is ready to use.

What Gets Created

When you create a new project, Character Studio initializes the following file structure. Understanding these files now will save confusion later — every tab in the left pane corresponds to one of these files.

File / Folder	Purpose
instructions.txt	The character definition. This is where you describe who your character is: personality, backstory, speech patterns, behavioral rules. Starts empty and ready for your writing. For a quick start, try the Generate button (more on that below, and in Chapter 2).
system-prompt.txt	The full system prompt sent to the model each turn. It contains a %%CHARACTER_INSTRUCTIONS%% placeholder where your Instructions content is inserted automatically. You can edit this file to add global directives, but you rarely need to — and if you ever delete that placeholder, a warning appears on the tab to alert you.
description.txt	A short description shown on Venice.AI character cards. Read by humans browsing the Venice catalog; not sent to the model.
intro.txt	The opening message shown to users who start a conversation with your character on Venice. Sets expectations and tone without contributing to the model's context.
config.json	Per-project configuration overrides. Starts as an empty object {}. Use it to override the model, temperature, file mappings, and other settings for this project specifically. The most common use for this is to attach agents to the project and to force a specific model (overriding the global model).
conversation_01.json	The first conversation file. Stores the full message history as a JSON array. You can have any number of conversations per project. One conversation will also be the trashcan for storing deleted images.
context/	A folder for world-building documents — lore, NPC lists, location descriptions. Character Studio automatically sends these to the model as background knowledge on every turn. Chapter 3 covers this in detail.
.gitignore	Excludes conversation files from Git history by default, keeping your test chats out of version control while your character definition is tracked. You can learn more about how Studio uses git to track history in Chapter 2, while Chapter 8 expands on how the .gitignore file reduces what gets tracked.
images/	Created the first time you use an Image Session or click Visualize. Stores all generated images alongside an index.json that tracks the prompt, model, and timestamp for each one. See Chapter 6.
photos/	Created the first time you add a photo via the Photos tab. Contains three subfolders: you/ (your user avatar), character/ (the character's headshot), and portrait/ (the full-size portrait for Venice publishing).
agents/  Beta	Where you place custom JavaScript agent modules you've written yourself. Not created on new projects — only needed if you're building your own agents beyond the built-in ones. Agent state (memories, stats, quests, etc.) is stored as sidecar files in the main project folder, not here (as they are isolated to the conversation). See Chapter 7.

All of these files are created with sensible defaults. The system prompt template is pre-written to correctly wire in your instructions and context and, by default, matches Venice.AI's default system prompt. You don't need to configure anything to have a working project — you just need to write your character.

Your First Conversation

The quickest way to verify everything is working is to chat with your character right away, even before writing a complete character definition. The model needs something to work with, though — an empty Instructions file produces a generic, unhelpful assistant.

Click the Instructions tab in the left pane. The Monaco editor opens, ready for input. The fastest way to get something working is the Generate button at the bottom of the left pane — type a name and a short description of your character, and the AI will draft a full set of instructions for you. You can also write something minimal by hand to get started quickly:

You are a warm and curious research librarian named Aria. You love obscure historical facts and have a gentle sense of humor. You speak in complete sentences and never use bullet points.

Either way, once the Instructions tab has some content, save your work.

• 1 Press Ctrl+S (or click the Save Changes button in the left pane header). This writes the file to disk and creates a Git history entry. The gold glow on the Save button disappears, confirming the save.
• 2 Click into the chat input at the bottom right — the large text area labeled "Type a message…"
• 3 Type a message to your character. Something like "Hello! What's the most surprising thing you've learned recently?"
• 4 Press Ctrl+Enter or click the Send button. The model response begins streaming into the chat panel immediately.

If the response arrives and sounds like Aria — warm, curious, historically inclined — everything is working. If you get an error instead, the most likely causes are a missing or invalid API key, or a network issue reaching the API endpoint. Double-check your Settings.

What to Do Next

A two-sentence Instructions file will get you a passable character, but a really good one takes more work. The next chapter covers how to write Instructions that produce consistent, immersive characters — including how to use the AI generator to draft structure, how the System Prompt relates to Instructions, and how to set up Description and Intro for Venice publishing.