# Account Deletion
Source: https://docs.workshop.ai/account-deletion
How to request deletion of your Workshop account.
To request deletion of your Workshop account and associated data, please contact us at [help@workshop.ai](mailto:help@workshop.ai).
Please send your request from the email address associated with your account so we can verify and process it.
## Considerations for paid accounts
Before deleting a Workshop account with a paid subscription:
1. Cancel your subscription from your [Account](https://account.workshop.ai) page.
2. Wait until the end of your current subscription period.
3. Once the subscription lapses, proceed with account deletion.
# Agent Engineering Essentials
Source: https://docs.workshop.ai/best-practices/index
Master the art of agent engineering — the skill of getting the most out of your AI development partner.
## Understanding Agent Engineering
Just like "prompt engineering" helps you get better results from language models, "agent engineering" is a set of best practices to maximize your success with Workshop. While Workshop is powerful and intuitive, following these practices will significantly improve your outcomes, especially for complex projects.
Agent engineering is about designing thoughtful interactions with AI systems to ensure they operate reliably, efficiently, and successfully. Even as AI models become more sophisticated, these practices help guide them toward the results you want.
## The Five Pillars of Successful Building
### 1. Separate Planning from Execution
Before diving into code, make sure you have clear requirements. If your project needs are still forming, start with collaborative planning:
```
I'm not sure about all the requirements for my project. I want to build
a data dashboard for my team, but I need help working through the details.
Don't start building until I give you the go-ahead.
```
Use **Plan Mode** to work through requirements systematically. This mode acts like an experienced technical product manager, asking the right questions and helping you scope appropriately.
Plan Mode is especially valuable at the start of a project. It helps you avoid the most common mistake: jumping into code before requirements are clear.
### 2. Build Incrementally
The most common mistake is asking for too much at once. Break your project into small, achievable steps:
**Instead of this:**
```
Build me a complete e-commerce website with user authentication,
payment processing, inventory management, and order tracking.
```
**Try this approach:**
```
Let's start by setting up a basic product catalog that displays
items with images and prices.
```
Then continue step by step:
```
Great! Now let's add a shopping cart where users can add items.
```
```
Perfect. Now let's add a simple checkout form (no payments yet).
```
This incremental approach has multiple benefits:
* Higher success rate for each step
* Easier to debug when issues arise
* Natural checkpoints to save progress
* Flexibility to change direction based on results
### 3. Verify Understanding Before Making Changes
When working with existing code, always ensure Workshop understands the current system before asking for modifications.
**The wrong approach:**
```
Change the color scheme to dark mode with blue accents.
```
**The right approach:**
```
First, examine the existing CSS structure and explain how the current
styling system works. Then show me the key files that control the
color scheme.
```
```
Now that you understand the structure, update it to use a dark mode
theme with blue accents.
```
This pattern is crucial for success with existing codebases. Just like human developers study code before modifying it, Workshop needs guided exploration to understand how things work.
### 4. Manage Task Execution
Some tasks require multiple iterations. Instead of micromanaging every step, you can give Workshop more autonomy:
**For ongoing work:**
```
Keep working on this until it's fully functional, but check with me
if you hit any major roadblocks.
```
**For quick iterations:**
```
Proceed
```
**When things get complex:**
```
Take your time with this. Make sure each step works before moving
to the next one, and commit your progress after each successful change.
```
### 5. Handle Errors Effectively
When Workshop gets stuck or makes mistakes, use these recovery strategies:
**For spinning wheels or repeated failures:**
```
Stop. Let's step back and reconsider our approach. Is there a simpler
way to achieve this goal?
```
**For dependency or environment issues:**
```
Let's try a different approach. Can we use Docker, or is there an
alternative library that might work better?
```
**For complex debugging:**
```
Let's break this down. First, create a minimal test case that
reproduces the issue, then we can fix it step by step.
```
## Using `.workshop/rules.md` for Project-Specific Instructions
Workshop automatically reads a `.workshop/rules.md` file in your project root, making it the ideal place to document project-specific context:
```markdown theme={null}
# Project: E-commerce Dashboard
## Architecture
- React frontend with TypeScript
- Node.js backend (Express)
- MongoDB database
- Authentication via Auth0
## Core Files
- src/api/auth.ts: Authentication middleware
- src/components/common/: Reusable UI components
- src/pages/: Main application views
## Style Guidelines
- Use functional components with hooks
- Use CSS modules for styling
- Follow Airbnb JavaScript style guide
## Testing
- Jest for unit tests
- React Testing Library for component tests
```
You do not need to write this file manually. Ask Workshop to create it:
```
Please create a .workshop/rules.md file for this project that documents
our code style, architecture, and main files.
```
Treat `.workshop/rules.md` as a living document. Update it as your project evolves. Focus on what is unique or non-obvious about your project — Workshop already understands common frameworks and patterns.
## Context Management Best Practices
As projects grow, help Workshop maintain context effectively:
**Start new conversations for new topics.** Credit cost per message increases as conversations get longer because each new message includes the full context of prior messages. Starting fresh conversations for distinct tasks is both cheaper and more effective.
**Use the `/compact` command.** When a conversation gets long but you are not ready to start fresh, the `/compact` command summarizes the conversation to reduce context size while preserving key information.
**Reference files explicitly.** When you need Workshop to focus on specific parts of your codebase, point it to the relevant files rather than expecting it to search the entire project.
**Keep `.workshop/rules.md` focused.** Add emphasis like "IMPORTANT:" or "NOTE:" for critical information. Avoid dumping massive amounts of context — prioritize what is most unique about your project.
## Common Success Patterns
### The MVP-First Pattern
Always start with the minimum viable version:
1. **Core functionality only** — Get the basics working
2. **Add one feature at a time** — Build on a solid foundation
3. **Enhance the user experience** — Polish after functionality is proven
### The Version Control Pattern
Establish good practices early:
```
Initialize git with a sensible .gitignore file and commit our initial setup.
```
```
Great progress! Let's commit this working version before we add
the next feature.
```
Regular commits create safety nets and clear progress markers. Workshop's built-in checkpointing provides an additional layer of safety for within-session changes.
### The Testing Pattern
Build confidence in your code:
```
Create some basic tests to verify the core functionality works correctly.
```
```
Before we deploy this, let's test it thoroughly to make sure everything
works as expected.
```
## Common Anti-Patterns to Avoid
| Anti-Pattern | What Happens | What to Do Instead |
| - | - | - |
| **"Do Everything"** | Asking for a complex multi-part app in a single request | Break it into smaller, focused steps |
| **"No Verification"** | Not testing or verifying work at each step | Ask Workshop to test after each change |
| **"Context Overload"** | Dumping massive context all at once | Introduce complexity gradually |
| **"No Progress Saves"** | Forgetting to commit working versions | Use git checkpoints at logical milestones |
| **"Too Specific"** | Over-prescribing implementation details | Give Workshop room to make good decisions |
## Measuring Success
Good agent engineering leads to:
* **Higher success rates** for complex tasks
* **Fewer iterations** needed to achieve goals
* **More maintainable** project outcomes
* **Better project continuity** across conversations
* **Reduced frustration** with debugging and errors
Agent engineering is a skill that improves with practice. Start with these patterns, experiment with your own approaches, and share what works in our [Discord community](https://discord.gg/ggqJkUN3vx).
# Refactoring AI-Generated Projects
Source: https://docs.workshop.ai/best-practices/refactoring
A practical guide to cleaning up, organizing, and improving code quality in projects built with Workshop.
One of the most powerful aspects of building with AI is the ability to rapidly create functional software through natural language. But as your projects grow, you may encounter a common challenge: managing accumulated files, potential duplicates, and maintaining a clean codebase. This guide walks you through the process of refactoring your projects to keep them organized and maintainable.
## What Is Refactoring?
Refactoring means improving your code's structure and organization without changing what it does. Think of it like reorganizing your kitchen — you are not adding new ingredients, just making everything easier to find and use.
Refactoring is essential for:
* Making your code easier to understand
* Reducing complexity
* Preparing for future enhancements
* Fixing potential issues before they cause problems
## Common Challenges with AI-Generated Code
### File Duplication
AI assistants sometimes create new files instead of modifying existing ones, especially when fixing errors. You might find both `database.py` and `database_fixed.py` in your project, with small differences between them.
### Inconsistent Naming Conventions
AI-generated code may use various naming styles across different files, making your codebase less consistent and harder to navigate.
### Unused Code and Dependencies
As your project evolves through multiple iterations, you may accumulate code that is no longer needed or dependencies that are not being used.
## Step-by-Step Refactoring Guide
### Step 1: Set Up Version Control
Before making any changes, set up version control as a safety net:
```
Help me set up git for version control in this project.
Ensure all necessary files are tracked.
```
Workshop initializes the repository, creates an initial commit, and explains basic git commands. Use git throughout the refactoring process:
```
Show me the git status to see what files I've changed
```
```
Commit my changes to git with a descriptive message
```
```
Create a new git branch where I can try removing files safely
```
### Step 2: Perform a Code Audit
Review your entire project to understand the purpose of each file:
```
Review all files in this project and explain what each one does.
Identify any duplicate or unused files.
```
Workshop analyzes your codebase and provides a comprehensive overview of each file's purpose, potential duplicates, obsolete files, and style inconsistencies.
### Step 3: Create a Refactoring Checklist
For anything beyond a small project, create a checklist to track progress:
```
Based on the code audit, create a markdown file called
"refactor_checklist.md" that includes:
1. A list of tests that need to be created before removing files
2. A list of duplicate or unused files that can be removed after testing
3. Instructions on how to use this checklist
```
Refactoring larger projects may require multiple conversations. When starting a new conversation, reference your checklist: *"Let's continue refactoring. Here's my current checklist: refactor\_checklist.md"*
### Step 4: Implement Testing
Before removing files or making significant changes, ensure you can verify your application still works:
```
Help me create tests that verify the core functionality.
Reference refactor_checklist.md for a list of tests to perform.
Choose a lightweight testing framework that ensures coverage.
```
Run tests to establish a baseline. Throughout refactoring, use these tests to ensure changes do not break functionality. If a test fails, you know exactly what stopped working and can fix it or revert to your previous git commit.
### Step 5: Clean Up Duplicate Files
With version control and tests in place, start cleaning up:
```
Let's consolidate the duplicate files you identified.
For each pair of duplicates, help me determine which to keep
and update any references to the removed file.
```
Workshop compares duplicates, identifies the most complete version, updates imports and references, commits changes, and runs tests to verify everything works.
### Step 6: Final Verification and Documentation
Once refactoring is complete, verify everything and document your project:
```
Run all tests to verify the application works correctly.
Update .workshop/rules.md to document the project structure,
tests, and how to run them.
```
## Preventing Issues in New Projects
### Establish Clear Rules
Create a `.workshop/rules.md` file with explicit instructions before starting development:
```markdown theme={null}
# Workshop Project Rules
1. Always edit existing files rather than creating new versions
2. Use git for version control with meaningful commit messages
3. Follow consistent naming conventions
4. Keep file organization according to feature/functionality
```
### Regular Housekeeping
Incorporate periodic cleanup sessions into your workflow. After every few development sessions, ask:
```
Review the project and check what every file does. Identify any
outdated, obsolete, or unnecessary files. Get my authorization
before removing anything.
```
### Commit Early and Often
Make git commits a regular part of your workflow. After each significant milestone, commit with a descriptive message. This creates checkpoints and makes it easy to track how your project evolves.
## Using Workshop to Refactor Its Own Code
One of Workshop's strengths is its ability to improve code it previously generated. You can ask Workshop to:
* **Audit its own work**: *"Review all the code you've generated in this project and identify areas for improvement."*
* **Consolidate patterns**: *"We have three different ways of handling API calls. Can you consolidate them into one consistent pattern?"*
* **Improve architecture**: *"This project has grown organically. Can you suggest a better file organization and help me restructure?"*
* **Remove dead code**: *"Find and remove any functions, imports, or files that are no longer used."*
## When to Refactor
Refactoring is not a one-time task — it is an ongoing process. Consider refactoring when:
* **After rapid prototyping**: You have built quickly and now want to clean up before continuing
* **Before adding major features**: A clean codebase makes new features easier to implement
* **When onboarding collaborators**: Clean code is easier for others to understand
* **When you notice patterns**: Repeated code or inconsistent structure signals a need for cleanup
* **Before deployment**: Production code should be clean and well-organized
## Strategies for Improving Code Quality Over Time
1. **Set standards early** with `.workshop/rules.md` and stick to them
2. **Refactor incrementally** rather than attempting massive rewrites
3. **Test before and after** every refactoring change
4. **Use version control** as a safety net at every step
5. **Document decisions** so future conversations have context
6. **Review regularly** — schedule periodic housekeeping sessions
The greatest benefit of building with Workshop is the speed of development. By combining that speed with disciplined maintenance practices, you get the best of both worlds: fast iteration and sustainable code quality.
# Using Credits Effectively
Source: https://docs.workshop.ai/best-practices/using-credits-effectively
How to manage conversations, project context, caching, and model choice without wasting credits.
The simplest way to avoid unnecessary credit use is to start a new conversation when
the goal changes or you return after a long break.
**When should you leave a long conversation behind?** When you begin a different task,
or return after more than an hour of inactivity—even if you are continuing the same
work. The usual cache window is about one hour, so reopening an older conversation can
mean paying for the model to process its full history again. Start a new conversation,
or switch to a lower-cost model, use `/compact`, then return to the capable model if
you need to continue the same task.
## What should I do?
### While actively working
| Situation | Best action |
| - | - |
| Continuing the same focused task while the cache is warm | Keep the same conversation and model |
| Starting a different feature, bug, or topic | Start a new conversation; before leaving the current one, run `/context` if it contains lasting knowledge |
| Continuing the same task without a long break, but with a long history | Run `/compact` to shorten the history carried into later turns; if needed, say what the summary should preserve |
| Changing the main model | If needed, first run `/context` to save lasting knowledge or `/compact` to continue the same task; then select the new model in the fresh or compacted conversation |
| The agent is repeating unsuccessful attempts | Interrupt it, narrow the goal, or return to planning |
### Before taking a long break
Prepare the handoff while the cache is still warm.
| What you need later | Best action |
| - | - |
| Knowledge that future conversations should know | Run `/context`; if needed, say what project knowledge it should preserve |
| The ability to continue the same task | Run `/compact` to create a shorter continuation |
You can view or edit the saved project context in `.workshop/context.md`.
If both apply, run `/context` first, then `/compact`.
### When you come back
| Situation | Best action |
| - | - |
| You saved the important knowledge with `/context` before leaving | Start a new conversation and state the next goal |
| You shortened the history with `/compact` before leaving | Continue from that shortened conversation |
| The old conversation is cold but contains unsaved knowledge | **Start fresh:** switch to a lower-cost model, run `/context`, then use the capable model in a new conversation.
**Continue the task:** switch to a lower-cost model, run `/compact`, then use the capable model in the shortened conversation |
| You do not need anything from the old conversation | Start a new conversation instead of continuing it |
## Three things that affect credit use
| | What it is | How to manage it |
| - | - | - |
| **Project context** | Stable knowledge shared across conversations | Use `/context` to save important project knowledge in `.workshop/context.md` for future conversations |
| **Conversation context** | Messages, file reads, commands, and agent responses in one conversation | Keep it focused; use `/compact` to shorten the history carried into later turns, or start fresh |
| **Prompt cache** | A temporary copy of input the model has already processed | Keep the same model while the cache is warm; assume it is cold after a long break |
## Why long conversations cost more
Each new turn includes the context needed to continue the conversation. As messages, file
reads, and tool results accumulate, there is more history to process on every turn.
A warm prompt cache makes repeated history cheaper, but it does not make the conversation
smaller. Output, new input, agent turns, and delegated work still consume credits.
**Why a fresh conversation saves credits.** It leaves the old chat history behind while
keeping the project's files, sources, and saved project context. The agent starts with
the durable information it needs, without carrying every earlier message and tool result.
Use one conversation for one clear purpose. When the purpose changes, start a new one.
## Use `/context` to save knowledge for future conversations
`/context` saves important project knowledge from the current conversation in
`.workshop/context.md` so future conversations can use it.
```text theme={null}
/context focus on architecture decisions, the current migration status,
and the commands used to verify the project
```
Run it after a milestone or lasting decision. Keep the saved context concise, and never
include secrets. You can view or edit it in `.workshop/context.md`. See
[Context and Memory](/core-concepts/context-and-memory).
## Use `/compact` to shorten history for the same task
`/compact` replaces a long working history with a shorter summary. Use it when you want to
continue the same task but no longer need every intermediate step.
```text theme={null}
/compact focus on the authentication bug, attempted fixes, and remaining verification
```
Compaction requires a summarization turn and usually starts a new cache. The saving comes
from carrying the shorter summary on later turns.
Workshop also compacts automatically near the context limit. See
[Working with the Agent](/core-concepts/working-with-the-agent#auto-compaction).
## Why caching and model switching matter
A prompt cache lets a model reuse conversation history at a discounted rate. The usual
TTL is **one hour**. Think of this as an idle timer: using the cache can refresh it, but
the exact behavior varies by model and provider.
| What happens | Result |
| - | - |
| Continue with the same model while the cache is warm | Matching history can use the lower cache rate |
| Return after the cache expires | The model must process the history again |
| Switch the main model or provider | The new model cannot use the old model's cache |
**Why a cold premium turn can be surprisingly expensive.** Think of two prices
multiplying. A premium model can cost around **10× more** than a lower-cost model. If
the cache is cold, rereading the same long conversation can cost around **10× more**
than reading it from a warm cache. Together, the conversation-history part of the first
cold turn on a premium model can cost around **100× more** than a warm turn on a
lower-cost model.
The exact difference varies, and the 100× comparison does not apply to the entire turn.
The practical rule is simple: do not make a premium model process a long, cold history.
Use a lower-cost model for `/context` or `/compact`, then use the capable model in the
fresh or shortened conversation.
## Choose the model for the task
The cheapest turn is not always the cheapest completed task. Repeated corrections can
cost more than using a stronger model once.
| Work | Model strategy |
| - | - |
| Routine edits, searches, and straightforward tasks | Use ARC or a lower-cost model |
| Everyday implementation | Use a balanced model |
| Difficult debugging, migrations, or architecture work | Choose a premium model deliberately |
[ARC](/core-concepts/settings#arc) is the simplest default when you do not want to pick
a model yourself.
## Related reading
* [Context and Memory](/core-concepts/context-and-memory)
* [When to Start Fresh vs. Persist](/troubleshooting/when-to-start-fresh)
* [Working with the Agent](/core-concepts/working-with-the-agent)
* [Plans and credits](/pricing/plans)
# Patterns from 10,000+ Projects
Source: https://docs.workshop.ai/best-practices/vibe-coding-from-10k-projects
Proven strategies for effective agentic coding, distilled from thousands of real-world Workshop projects.
Workshop is the everything builder that enables agentic coding through natural language. This guide covers proven strategies distilled from over 10,000 projects across various tech stacks and environments.
Workshop is intentionally flexible and unopinionated, providing a natural language interface to create any type of software without forcing specific workflows. This design philosophy creates a powerful tool that adapts to your needs. While powerful, this flexibility presents a learning curve — at least until you develop your own best practices.
Nothing in this guide is set in stone nor universally applicable. Consider these suggestions as starting points, and experiment to find what works best for you.
## 1. Customize Your Environment
### Create `.workshop/rules.md` Files
`.workshop/rules.md` is a special file that Workshop automatically pulls into context when working with your project. This is the single most impactful thing you can do to improve Workshop's output. Document:
* Project architecture and structure
* Core files and utility functions
* Code style guidelines
* Testing frameworks and methodologies
* Environment setup instructions
* Deployment processes
You do not need to write this file manually:
```
Please create a rules.md file for this project that documents our
code style, architecture, and main files.
```
### Optimize Your Rules Files
Your `.workshop/rules.md` files become part of Workshop's understanding of your project. Treat them as living documents:
* Focus on what is most unique or non-obvious about your project
* Keep documentation minimal for projects with standard frameworks
* Add emphasis like "IMPORTANT:" or "NOTE:" for critical constraints
* Update the file as your project evolves
### Configure Secrets Management
Workshop includes built-in secrets management for sensitive information like API keys. Configure secrets in Settings, then reference them by name:
```
Connect to the OpenAI API using the OPENAI_API_KEY secret.
```
Workshop stores secrets in your system's keychain, keeping them protected while making them available for your projects.
### Control Workshop's Autonomy
Three controls let you tune how independently Workshop works:
* **Code Execution Approval** — Review and approve each code block before it runs
* **Turns Control** — Set a maximum number of autonomous turns between your messages
* **Thinking Mode** — Enable visible step-by-step reasoning for complex problems
**Thinking Mode tends to reduce overall credit consumption.** Although it may increase credit usage per message, the structured reasoning produces more focused, accurate results — reducing wasted iterations.
## 2. Give Workshop More Context
### Start with Clear High-Level Vision
Begin by describing the overall picture, not technical details:
```
I want to build a personal expense tracker app that helps me
categorize my spending and visualize trends over time. It should:
- Import transactions from CSV bank statements
- Automatically categorize transactions based on patterns
- Show monthly spending breakdowns by category
- Generate reports I can export to PDF
- Work offline without requiring cloud services
```
### Use Multimodal Input
Workshop supports text, wireframes, screenshots, diagrams, and reference images. For visual elements like UIs, providing visual references dramatically improves output. Drag and drop images directly into the conversation.
### Reference External Documentation
Provide links to relevant docs when working with specific libraries or APIs:
```
I want to build a React Native app that uses the Stripe API.
Search for the relevant docs.
```
Workshop fetches and incorporates external documentation into its understanding of your project.
### Use Project Templates
Browse available templates when starting a new project. Templates provide pre-configured projects with appropriate structure, dependencies, and starter code. They save time and ensure your project follows established patterns from the start.
## 3. Effective Workflows
### Separate Design from Execution
Clearly separate planning from building:
1. **Discuss requirements first**: *"I want to build a dashboard that shows analytics from our API, but I need help working through the details. Don't jump to execution until I instruct you to."*
2. **Refine together**: Use Workshop as a collaborative partner to explore options
3. **Signal when to build**: Once satisfied with the plan, explicitly tell Workshop to start
### Take Incremental Steps
1. **Start with the simplest version** that demonstrates core functionality
2. **Verify each step works** before moving to the next
3. **Build progressively** once the foundation is solid
This incremental approach significantly increases success rates by avoiding complexity too early.
### Iterate Through Conversation
1. Describe your initial idea in simple terms
2. Let Workshop build a minimal implementation
3. Refine through natural language feedback: *"Make the activity feed more compact"*
4. Use visual input when possible — attach screenshots with feedback
This conversational approach yields far better results than specifying everything in a single prompt.
### Switch Modes as Needed
* **Higher autonomy** for rapid development when you want quick results
* **Manual approval** when you need precise control over specific features
* **Extended execution**: *"Keep working until you really need my input"*
## 4. Optimize Your Prompting
### Be Specific and Prioritize
| Less Effective | More Effective |
| - | - |
| Make me a weather app | Create a weather app showing the 5-day forecast for the user's current location. Display temperature, precipitation chance, and wind speed. Use React and the OpenWeatherMap API. Clean, minimalist UI with a blue color scheme. |
| Fix the authentication bugs | Debug the authentication flow in auth.js. Users are logged out after 10 minutes even though JWT expiration is set to 24 hours. Check for token refresh issues. |
| Make this code better | Refactor for performance. The database query loads all records instead of paginating. Implement pagination with 20 items per page using indexed fields for sorting. |
### Use the Right Level of Guidance
* **High-level**: *"Build a shopping cart component for an e-commerce site"* — good for standard patterns
* **Directed**: *"Build a shopping cart with these specific requirements: \[list]"* — when you have specific needs
* **Step-by-step**: *"First create a CartContext, then CartItem and CartSummary components"* — for precise control
Start with high-level guidance and become more specific if results do not match expectations.
### Show Examples
When you have a specific style in mind, reference existing code:
```
I need a user profile page similar to the product detail page in
products.js, but focused on user information. Use the same styling
approach but adapt the layout for user data.
```
## 5. Leverage Workshop's Tools
### File System Tools
Workshop can create, read, edit, and search files in your project. Explicitly tell it which files to focus on for best results. Its file editing is especially powerful for targeted changes to large codebases.
### CLI / Shell Tools
Workshop runs shell commands, package managers, build tools, version control, and deployment scripts. It can determine the right commands for a task or execute specific commands you provide.
### Search Tools
Workshop searches both your local codebase and the web for relevant patterns, documentation, error solutions, and reference materials.
## 6. Guide Workshop's Learning
### Understand Before Modifying
Before asking Workshop to change existing code:
1. **Ask it to explain** how the existing code works
2. **Verify its understanding** is correct
3. **Then make changes** with confidence
This dramatically improves success rates with established codebases.
### Embrace Iteration Over Perfection
1. Start small with minimal functionality
2. Get feedback early
3. Add features incrementally
4. Commit working versions regularly
## 7. Use Checkpoints for Safety
Workshop automatically saves checkpoints of your project at key moments during each conversation. This gives you a "time machine":
* **Experiment freely** — if something does not work out, restore to a previous state
* **Track changes** — see exactly when file modifications occurred
* **Go back in time** — revert your project to any earlier point in the conversation
Checkpoints work alongside your existing Git repository without interference — they do not create `.git` files, they respect `.gitignore`, and your own commits remain unaffected.
## 8. Share Your Work
Workshop lets you share conversations privately via unique links or publicly through Workshop Universe. Share your process, showcase ideas, and let others learn from your approach.
Ensure publicly shared conversations do not contain sensitive information, API keys, or proprietary code.
## Real-World Application Patterns
Describe your product vision in plain language. Let Workshop build a basic prototype. Gather feedback from stakeholders. Iterate quickly through natural language — dramatically reducing time from idea to testable prototype.
Set up a data analysis environment, describe your goals, request specific visualizations, and create reproducible notebooks — combining your domain expertise with Workshop's technical capabilities.
Describe the business problem, specify integrations with existing systems, start with core functionality, and deploy internally. Create tailored solutions without diverting engineering resources.
Identify systems that need to communicate, provide credentials securely via secrets management, describe the desired workflow, and test with sample data. Workshop builds APIs, webhooks, and data transformations to connect disparate systems.
***
Mastering agentic coding is about finding the right balance between clear direction and creative freedom. The most successful Workshop users view the process as a collaboration between human creativity and AI implementation, with each iteration bringing the project closer to their vision.
Keep exploring, experimenting, and sharing your experiences with the [Workshop community](https://discord.gg/ggqJkUN3vx).
# Build AI-Powered Apps
Source: https://docs.workshop.ai/build-guides/ai-apps
Ship full-stack AI applications with Anthropic, OpenAI, and Google models built in — not wrappers, real apps with intelligent backends.
## What you'll build
A complete, deployable AI-powered application — with a frontend, backend, and AI model integration — that you can publish and share with a link.
## Before you start
Sign up at [app.workshop.ai](https://app.workshop.ai). Both Workshop Cloud and Workshop Desktop support AI app development.
Your app needs access to an AI model to power its intelligent features. You have two options:
Managed connectors for Anthropic, OpenAI, and Gemini are **on by default** — no API keys, no setup required. Usage is billed to your Workshop credits.
To use one, just reference it in your prompt using the **@** mention selector or the **Add Functionality** button. Workshop handles the rest — model selection, API calls, streaming, and error handling.
Managed connectors support everything the underlying models do. For example:
* *"Add image generation using @Gemini"* — Workshop will use Gemini's image capabilities
* *"Use @Anthropic to analyze this document and return structured data"*
* *"Build a voice transcription feature powered by @OpenAI"*
If you have your own API key from a provider, you can connect it directly instead. This bills usage directly to your provider account.
1. Get an API key from [Anthropic](https://console.anthropic.com/), [OpenAI](https://platform.openai.com/api-keys), or [Google AI Studio](https://aistudio.google.com/apikey)
2. Open the **Hub** → **Connectors**
3. Search for the provider (e.g., "OpenAI (your API key)")
4. Enter your API key and save
## Step-by-step flow
Start a new conversation and describe the application. Mention the AI capabilities you want — don't worry about the implementation details, Workshop handles that.
**Example prompts:**
* *"Build an AI writing assistant that lets users paste text and rewrite it in different tones — professional, casual, concise, persuasive. Include a side-by-side comparison view."*
* *"Create a document Q\&A app where users upload PDFs and ask questions about the content. Use Claude for accurate answers with source citations."*
* *"Build a customer support chatbot with an admin panel to manage FAQ entries and a chat interface with conversation history."*
Workshop generates the full stack: frontend UI, backend API routes, and AI model integration. It uses whichever AI connector you enabled and writes the code to call it correctly — prompt engineering, streaming responses, error handling, and all.
Use the live preview to test the AI features. Send real inputs and verify the responses make sense. Refine as needed:
* *"Make the AI responses stream in word by word instead of appearing all at once."*
* *"Add a system prompt field in the admin panel so I can customize the AI's behavior."*
* *"Limit response length to 500 words and add a regenerate button."*
Click **Publish** and Workshop handles hosting and compute. Your app gets a live URL with built-in authentication. You can make it public or limit access to specific people or teams — Workshop handles the access control as part of the same flow.
## Tips and best practices
Instead of *"add AI to my app,"* describe exactly what the AI should do: *"When a user uploads a CSV, have the AI analyze the data and generate a summary with three key insights and a recommended next step."*
Managed connectors are the fastest way to get started — no API key setup, no billing configuration, no rate limit management. Switch to BYOK later if you need to.
Reference the specific connector when it matters: *"Use the Anthropic connector for the analysis — I want Claude's reasoning capabilities for this."* Workshop will route to the right model.
If your app sorts, routes, moderates or scores inputs rather than generating text, Workshop suggests the [Jev](/connectors/jev) decision model. It returns calibrated probabilities in well under a second, billed to your Workshop credits or your own OpenRouter or TypeSafe key.
Workshop's strength is building full applications around AI — with forms, databases, visualizations, and user accounts. Don't just build a chatbot; build the complete tool your users need.
Try empty inputs, very long inputs, and adversarial prompts. Ask Workshop to add input validation and error handling: *"Add a 10,000 character limit on the input field and show a friendly error if the AI call fails."*
## Next steps
* [AI Providers reference](/connectors/managed-ai-connectors) — Deep dive on managed vs. BYOK connectors
* [Publishing](/workshop-cloud/publishing) — Deploy your app with authentication and custom domains
* [Working with the Agent](/core-concepts/working-with-the-agent) — Prompting tips and communicating with Workshop
* [Checkpoints](/workshop-desktop/checkpoints) — Save working versions before experimenting (Workshop Desktop only)
***
Ship AI apps, not wrappers. Describe your app and go.
# Build Trusted Dashboards
Source: https://docs.workshop.ai/build-guides/dashboards
Connect your databases and build interactive, governed dashboards with natural language. Native dbt integration keeps your metrics trustworthy.
## What you'll build
An interactive, data-connected dashboard — with charts, KPI cards, filters, and drill-downs — deployed as a shareable web app with built-in authentication.
## Before you start
Sign up at [app.workshop.ai](https://app.workshop.ai). Workshop Cloud is the recommended platform for dashboards.
Dashboards need data. Workshop supports a wide range of data connectors — connect at least one before you start building.
Connect directly to your production or analytics database:
* **PostgreSQL**, **MySQL**, **Microsoft SQL Server**, **MongoDB**
* **Supabase**, **Neon** (managed Postgres)
* **TiDB**, **TigerGraph**
Go to **Hub** → **Connectors**, select your database type, and enter the connection credentials.
Connect to your warehouse for analytics-scale queries:
* **BigQuery** (GCP service account)
* **Snowflake** (account, user, password, optional warehouse/schema)
These are ideal for large datasets and complex analytical queries.
For lighter data needs:
* **Google Sheets** (public or private with service account)
* **CSV / Excel uploads** — paste data or upload files directly into the conversation
Great for quick dashboards or when your data isn't in a database yet.
## Step-by-step flow
Open the **Hub** → **Connectors** and set up a connection to your database, warehouse, or spreadsheet. Workshop stores credentials securely and makes the data available to your projects.
You can also mention connectors inline: type `@` in the chat and select a connector to reference it directly in your prompt.
Tell Workshop what metrics and visualizations you need. Reference the connected data source.
**Example prompts:**
* *"Build a sales analytics dashboard from my Postgres database showing revenue trends over time, top customers, regional performance on a heatmap, and key KPI cards with quarter-over-quarter comparisons."*
* *"Create a financial reporting dashboard with P\&L statement, cash flow analysis, budget vs. actuals, and drill-down by department."*
* *"Build a product analytics dashboard with user cohort retention heatmap, feature adoption funnel, and daily/weekly active users with date range filtering."*
Refine specific charts, add filters, or change the layout:
* *"Change the revenue chart to a stacked area chart broken down by product line."*
* *"Add a date range picker that filters all charts on the page."*
* *"Replace the table with a bar chart for the regional breakdown."*
* *"Add a row of KPI cards at the top: total revenue, new customers, average deal size, and churn rate."*
Click **Publish** and Workshop handles hosting and compute. Anyone you share it with gets a live, interactive view — not a static screenshot. Make it public or limit access to specific people or teams. Built-in authentication controls who can see the data.
## Tips and best practices
You don't need to know SQL. Say *"Show me monthly recurring revenue by customer segment"* and Workshop will write the queries for you. If you do know SQL, you can paste queries directly for more precise control.
If your organization uses dbt, Workshop can read your dbt models, metrics, and documentation natively. This means your dashboards are built on governed, version-controlled metric definitions — not ad-hoc queries that drift over time.
For even deeper governance, compile your dbt project into a structured agent skill using [dbt-skillz](https://github.com/atlasfutures/dbt-skillz) — an open-source compiler available on [PyPI](https://pypi.org/project/dbt-skillz/):
```bash theme={null}
pip install dbt-skillz
dbt-skillz compile --project-dir ./analytics --output ./skills/data
```
Push the compiled skill to a GitHub repo and import it into Workshop. The agent will use your metric definitions, column documentation, and lineage graph to write correct queries from the start. See [Skills](/core-concepts/skills) for import instructions.
Begin with the 3-5 key numbers your audience cares about. Once those are right, add supporting charts and drill-downs. This keeps the dashboard focused.
Ask for date range pickers, dropdown filters, and search bars: *"Add filters for date range, region, and product category that affect all charts."* Interactive dashboards are far more useful than static reports.
If your production database has millions of rows, tell Workshop: *"This table has 10M+ rows — make sure the queries are performant and use appropriate aggregations."* Workshop will optimize accordingly.
## Trusted dashboards lifecycle
Building the dashboard is step one. Keeping it accurate as your data model evolves is the real challenge. Workshop supports a full trusted dashboards lifecycle — from grounded creation through automated review and maintenance.
Automated review on deploy, downstream impact analysis, and dashboard maintenance when your dbt models change.
## Next steps
* [Connectors](/connectors) — Full list of supported data sources and setup guides
* [Publishing](/workshop-cloud/publishing) — Deploy and share your dashboard
* [Sharing and teams](/workshop-cloud/sharing-and-teams) — Control access to your dashboards
* [Working with the Agent](/core-concepts/working-with-the-agent) — Prompting tips and communicating with Workshop
* [Skills](/core-concepts/skills) — Import data skills from GitHub to ground your dashboards
* [Trusted Dashboards](/solutions/trusted-dashboards) — The full lifecycle for keeping dashboards accurate
***
Connect your data and build a dashboard you can trust.
# Build Guides
Source: https://docs.workshop.ai/build-guides/index
Step-by-step guides for building real, working software with Workshop.
Workshop builds real, deployed software — not mockups, not prototypes, not chat transcripts. You describe what you want in plain English and Workshop writes the code, sets up the infrastructure, and deploys the result.
These guides walk you through the most common types of projects people build with Workshop — from websites, AI-powered apps, and dashboards to mobile apps and local utilities that run directly on your machine.
## Choose your build type
Build and deploy responsive, accessible websites. Landing pages, portfolios, e-commerce storefronts, and more — from description to live URL.
Ship full-stack applications with Anthropic, OpenAI, and Google AI models built in. Real backends, not API wrappers.
Connect your databases and build interactive, trusted dashboards. Native dbt integration for governed metrics.
Admin panels, CRMs, and operational tools connected to your existing databases and APIs. Deploy with built-in authentication.
Build iOS and Android apps with Expo, React Native, Swift, or Kotlin using Workshop Desktop's terminal and filesystem access.
Build native utilities that run directly on your machine — keyboard tools, transcription, file organization, data processing, and other ad hoc tasks. Workshop Desktop only.
## Workshop Cloud vs. Desktop
Not every project type works on every platform. Here's a quick guide:
| Build type | Workshop Cloud | Workshop Desktop |
| - | - | - |
| Websites | Yes | Yes |
| AI-powered apps | Yes | Yes |
| Dashboards | Yes | Yes |
| Internal tools | Yes | Yes |
| Mobile apps | — | Yes |
| Local apps | — | Yes |
Workshop Cloud runs entirely in your browser. No downloads, no local setup — just describe what you want and Workshop builds it.
Workshop Desktop gives you full filesystem access and terminal control on your local machine. It's required for projects that need native toolchains — mobile development, desktop apps, or anything that must run locally.
If you're not sure which platform to use, start with [Workshop Cloud](https://app.workshop.ai). You can always move to Desktop later if your project requires it.
# Build Internal Tools
Source: https://docs.workshop.ai/build-guides/internal-tools
Build admin panels, CRMs, and operational tools connected to your databases and APIs. Deploy securely with built-in authentication.
## What you'll build
A custom internal tool — an admin panel, CRM, operations dashboard, or workflow tracker — connected to your real data and deployed with authentication so only your team can access it.
## Before you start
Sign up at [app.workshop.ai](https://app.workshop.ai). Workshop Cloud is recommended for internal tools — it handles hosting, auth, and deployment.
Internal tools are most useful when connected to your existing systems. Set up the connectors you need:
* **Databases**: PostgreSQL, MySQL, MongoDB, Supabase, Neon, Microsoft SQL Server, TiDB
* **Data warehouses**: BigQuery, Snowflake
* **Cloud storage**: AWS S3, Google Drive
* **APIs**: Use the custom connector to store API keys and secrets for any third-party service
* **Spreadsheets**: Google Sheets (public or private)
Go to **Hub** → **Connectors** to set them up.
## Step-by-step flow
Open the **Hub** → **Connectors** and add connections to the systems your tool needs to read from or write to. For custom APIs, use the **Custom Connector** to securely store API keys and endpoints.
Tell Workshop what the tool should do, who will use it, and what data it needs.
**Example prompts:**
* *"Build a customer support admin panel with ticket management, customer lookup, response templates, and performance metrics. Connect to my Postgres database for ticket and customer data."*
* *"Create an inventory management tool with product catalog, stock level tracking, low-stock alerts, and purchase order generation. Include search, filtering, and CSV export."*
* *"Build a sales CRM with a Kanban pipeline view, contact management, activity logging, and deal forecasting."*
* *"Create an employee onboarding tracker with task checklists, progress visualization, and an admin view."*
Internal tools typically need to read and write data. Ask Workshop to add the operations your team needs:
* *"Add a form to create new customers with validation on the email field."*
* *"Let users change the ticket status by clicking a dropdown in the table row."*
* *"Add a bulk action to mark selected orders as shipped."*
* *"Add CSV export for the filtered table view."*
Click **Publish** and Workshop handles hosting and compute. Built-in authentication means your team members sign in to access the tool — no one else can see the data. You can restrict access to specific people or teams without building a login system yourself.
## Tips and best practices
Tell Workshop who will use this: *"This is for our customer success team — they need to quickly look up a customer by email, see their subscription status, recent tickets, and usage metrics."* Context about the user produces better UX decisions.
Don't try to build the entire tool at once. Start with the single most important workflow — e.g., *"I need to be able to search for a customer and see all their orders"* — and expand from there.
Connect to your actual database (or a staging copy) so you can validate that queries return correct results. Dummy data hides schema mismatches and edge cases.
Internal tools handle real business data. Ask Workshop for safeguards: *"Add a confirmation dialog before deleting a record. Validate that the email format is correct before saving. Show an error message if the database update fails."*
If different team members need different access levels, describe it: *"Managers can edit and delete records. Regular users can only view and create."* Workshop can build role-based access into the tool.
## Next steps
* [Connectors](/connectors) — Set up database and API connections
* [Publishing](/workshop-cloud/publishing) — Deploy your tool with authentication
* [Sharing and teams](/workshop-cloud/sharing-and-teams) — Control who can access the tool
* [Working with the Agent](/core-concepts/working-with-the-agent) — Prompting tips and communicating with Workshop
***
No more waiting on engineering backlogs. Describe the tool and deploy it today.
# Build Local Apps
Source: https://docs.workshop.ai/build-guides/local-apps
Build native utilities and tools that run directly on your machine — from keyboard tools and transcription to file processors and ad hoc tasks. Workshop Desktop only.
## What you'll build
A native app or utility that runs directly on your machine — no browser, no server, no deployment step. Local apps can be anything from a keyboard remapper or transcription tool to a file organizer, video resizer, CSV processor, or any task you find yourself doing repeatedly.
Local app development requires **Workshop Desktop**. Workshop Cloud does not have access to your local file system, hardware, or system APIs.
## Before you start
Install Workshop Desktop from [workshop.ai/download](https://workshop.ai/download). No other setup is required — Workshop handles everything else, including downloading libraries and installing dependencies.
Workshop Desktop gives you the option to build with local models running on your own machine. Workshop will help you select the best fit based on your hardware. Building with a local model means no API costs, nothing leaving your machine, and no internet connection required.
If you prefer to build with an online model, that works too — just select one from the model picker in the toolbar.
See [Local Models](/workshop-desktop/local-models) to get set up.
Think about what system resources your app will use — files and folders, keyboard input, microphone, camera, clipboard, or system APIs. Having this in mind before you start helps Workshop make the right architecture decisions from the beginning.
## Step-by-step flow
Start a new conversation and tell Workshop what the app should do. Be specific about what it needs to access on your system.
**Example prompts:**
* *"Build a menu bar app for macOS that transcribes whatever I'm listening to in real time and shows it as scrolling text."*
* *"Create a folder watcher that automatically renames files in a target directory using a date-prefix format I can configure."*
* *"Build a desktop app that takes a folder of videos, lets me pick a resolution and format, and batch-converts them."*
* *"Make a utility that reads a CSV, lets me preview it, apply simple transformations, and export the result."*
* *"Build a global keyboard shortcut tool that expands text snippets as I type — e.g., typing `;addr` expands to my full address."*
Workshop installs the right libraries and frameworks for your platform — whether that's a Python script with a native UI, an Electron app, a Swift app on macOS, or a system tray utility. You don't need to install dependencies or configure toolchains manually.
Tell Workshop your platform upfront if it matters: *"This should be a macOS app"* or *"It needs to work on both Windows and macOS."* Workshop will choose the right approach.
Local apps run directly on your machine as soon as they're built — no deployment, no server, no URL to visit. Workshop launches the app so you can test it right away.
Iterate naturally:
```
The file picker doesn't show hidden folders — can you include those?
Add a progress bar while it's processing.
Make the window remember its position between launches.
```
Workshop has full access to your file system and terminal, so it can fix issues, install missing packages, and make changes without any manual steps on your part.
Workshop can style your app to match the platform it runs on — native macOS window chrome, Windows controls, or Linux conventions. If you want it to feel at home on your desktop rather than like a generic tool, just ask.
* *"Make this look like a native macOS app with a proper menu bar and dark mode support."*
* *"Add a system tray icon so it runs in the background."*
* *"Use the platform's native file picker instead of a custom one."*
## Tips and best practices
Tell Workshop what system resources your app requires — files, keyboard, microphone, camera, clipboard, network. This lets it make the right architecture and permissions decisions from the start, rather than retrofitting them later.
Don't try to pre-install libraries or frameworks. Give Workshop the task and let it choose and install what's needed. It will resolve errors and missing packages as part of the build process.
Workshop Desktop lets you power the agent with a local model running on your machine — no API costs, fully private, works offline. This is especially useful when you're iterating heavily and want to keep costs at zero. Switch to a frontier model when you want maximum capability.
Start with the core function, run it, verify it works, then add features:
1. *"Build the basic folder watcher that prints file names to the console"*
2. *"Add the rename logic with the date prefix"*
3. *"Add a config file so I can change the format without editing code"*
4. *"Add a simple UI so I can toggle it on and off"*
Workshop knows the conventions for each platform. If you want your app to feel native — launch at startup, live in the menu bar or system tray, use native dialogs — just describe it. You don't need to know the implementation details.
## Next steps
* [Local Models](/workshop-desktop/local-models) — Run Ollama or llama.cpp for private, offline AI features
* [AI Providers](/connectors/managed-ai-connectors) — Add cloud-powered AI features to your app
* [File System and Terminals](/workshop-desktop/file-system-and-terminals) — How Workshop Desktop interacts with your local environment
* [Working with the Agent](/core-concepts/working-with-the-agent) — Prompting tips and communicating with Workshop
* [Checkpoints](/workshop-desktop/checkpoints) — Save and restore project states
***
Build local apps that run natively on your machine — no deployment required.
# Build Mobile Apps
Source: https://docs.workshop.ai/build-guides/mobile-apps
Build iOS and Android apps with Workshop Desktop. Expo and React Native for cross-platform, or native Swift and Kotlin for platform-specific development.
## What you'll build
A mobile application for iOS, Android, or both — from project scaffolding through development to store-ready builds — using Workshop Desktop's terminal access and filesystem control.
Mobile app development requires **Workshop Desktop**. Workshop Cloud does not have access to the native toolchains (Xcode, Android Studio, simulators) needed for mobile development.
## Before you start
Install Workshop Desktop from [workshop.ai/download](https://workshop.ai/download). Workshop Desktop runs on your local machine with full filesystem and terminal access.
Workshop supports multiple mobile development paths. Choose based on your needs:
| Framework | Platforms | Best for |
| - | - | - |
| **Expo / React Native** | iOS + Android | Cross-platform apps, fastest path to both stores |
| **Swift / SwiftUI** | iOS only | Native iOS performance, Apple ecosystem features |
| **Kotlin / Jetpack Compose** | Android only | Native Android performance, Google ecosystem features |
## Recommended path: Expo / React Native
Expo is the recommended starting point for most mobile apps. It gives you a single codebase that runs on both iOS and Android, with a fast development cycle and straightforward path to the app stores.
Open Workshop Desktop, start a new conversation, and ask Workshop to set up your Expo project:
*"Help me set up Expo CLI and create a new React Native project with TypeScript, React Navigation, and a tab-based layout."*
Workshop will install the necessary tools, scaffold the project, and configure the development environment.
Once the project is set up, describe what you want to build:
**Example prompts:**
* *"Build a task management app with categories, due dates, push notifications for reminders, and a dark mode toggle."*
* *"Create a recipe app with a searchable catalog, favorites list, grocery list generator, and offline support."*
* *"Build a fitness tracker with workout logging, progress charts, and a calendar view."*
Ask Workshop to launch the app in the iOS Simulator or Android Emulator:
* *"Run this in the iOS Simulator."*
* *"Start the Expo development server so I can test on my phone."*
Use the Expo Go app on your physical device for the fastest testing loop.
Refine specific screens, add features, and polish the UI:
* *"Add pull-to-refresh on the home screen."*
* *"Make the navigation transitions smoother with shared element animations."*
* *"Add camera access for the profile photo feature."*
* *"Implement offline data persistence so the app works without internet."*
When your app is ready, ask Workshop to prepare it for the stores:
*"Help me configure EAS Build for both iOS and Android, generate app icons and splash screens, and prepare for App Store and Google Play submission."*
## Alternative: Native iOS with Swift
For apps that need deep Apple ecosystem integration (HealthKit, ARKit, Watch connectivity), native Swift development is the way to go.
*"Help me set up an iOS development environment with Xcode. Create a new SwiftUI project with a tab-based navigation structure."*
Xcode is required and only runs on macOS. Make sure you have it installed from the Mac App Store before starting.
Describe your screens, data models, and interactions. Workshop writes Swift/SwiftUI code and can help with Core Data, CloudKit, notifications, and other Apple frameworks.
*"Create a SwiftUI app with a list view of items from Core Data, a detail view with editing, and iCloud sync."*
*"Help me prepare my iOS app for App Store submission — code signing, app icons, screenshots, and review guidelines."*
## Alternative: Native Android with Kotlin
For apps that need deep Android platform features (widgets, background services, Wear OS), native Kotlin is the best choice.
*"Help me configure Android Studio and create a new Kotlin project with Jetpack Compose, navigation, and Material Design 3."*
Workshop writes Kotlin code with Jetpack Compose and can help with Room database, WorkManager, Firebase integration, and other Android frameworks.
*"Build an Android app with a Compose UI showing a list from Room database, with search, swipe-to-delete, and a floating action button to add items."*
*"Help me prepare my Android app for Google Play — generate signed APK, create store listing assets, and configure the release track."*
## Tips and best practices
Expo handles the build system, native module linking, and over-the-air updates. It covers the vast majority of mobile app use cases. Only go native if you need a specific platform API that Expo doesn't support.
Mobile development environments are notoriously tricky to configure. Give Workshop the full setup task — it will handle dependency installation, SDK configuration, and emulator setup, resolving errors along the way.
Simulators are great for rapid iteration, but real-device testing catches performance issues, gesture behavior, and hardware-specific bugs that simulators miss. Ask Workshop to help you set up device testing.
Say *"Build a settings screen with toggles for notifications, dark mode, and data sync, plus an account section with profile photo, name, and logout button"* rather than specifying components. Workshop knows which UI primitives to use for each platform.
Mobile apps have complex state. Before adding a major feature or refactoring navigation, ask Workshop to create a checkpoint so you can roll back if needed.
If your app includes AI features, you can develop and test against a local model running on your machine — zero API costs, fully private, no internet required. Switch to a managed AI connector when you're ready to ship.
## Next steps
* [Workshop Desktop overview](/workshop-desktop/index) — Learn more about Desktop's capabilities
* [File system and terminals](/workshop-desktop/file-system-and-terminals) — How Workshop Desktop interacts with your local environment
* [Checkpoints](/workshop-desktop/checkpoints) — Save and restore project states
* [Working with the Agent](/core-concepts/working-with-the-agent) — Prompting tips and communicating with Workshop
***
Build mobile apps with full terminal access and native toolchain support.
# Build and Deploy Websites
Source: https://docs.workshop.ai/build-guides/websites
Build responsive, accessible websites from a description and publish them to a live URL — no templates, no page builders.
## What you'll build
A fully responsive, production-ready website — deployed to a live URL with a custom domain — built entirely by describing what you want in natural language.
## Before you start
Sign up at [app.workshop.ai](https://app.workshop.ai) (free tier available). Workshop Cloud is the fastest path for websites, but Workshop Desktop works too.
Screenshots, URLs of sites you admire, brand colors, logos, and copy. The more context you give Workshop, the better the result.
## Step-by-step flow
Start a new conversation and tell Workshop what you want. Be specific about the type of site, its sections, and the audience.
**Example prompts:**
* *"Build a SaaS landing page with a hero section, feature grid, pricing table with monthly/annual toggle, testimonials, and an email waitlist form."*
* *"Create a portfolio site with a filterable project gallery, about page, blog with markdown support, and a contact form. Use a minimal, modern design."*
* *"Build a restaurant website with a browseable food menu organized by category, reservation booking form, photo gallery, and location map."*
Review the live preview and refine. You can ask Workshop to change specific sections without rebuilding the whole site.
* *"Make the hero section taller with more whitespace."*
* *"Change the color scheme to navy and gold."*
* *"Add a dark mode toggle."*
* *"Make the pricing cards stack vertically on mobile."*
Go beyond static pages. Workshop can wire up forms, animations, and third-party services.
* *"Connect the contact form to send emails via a backend endpoint."*
* *"Add smooth scroll animations when sections come into view."*
* *"Add a blog section that loads posts from markdown files."*
When you're happy with the result, click **Publish**. Workshop handles hosting and compute — you get a shareable URL immediately. You can make the site public or limit access to specific people or teams. Custom domains are available in settings.
## Tips and best practices
Tell Workshop about sites you like: *"I want the layout to feel like Linear's homepage — clean, lots of whitespace, monospace accents."* References give Workshop a strong design direction.
Don't try to perfect the whole site in one prompt. Get the overall structure right first, then refine individual sections. This gives you more control and better results.
Ask Workshop to show you the mobile view: *"Show me how this looks on a phone."* Catching layout issues early is much easier than fixing them at the end.
Workshop can generate placeholder text, but your site will be much stronger if you provide real headlines, descriptions, and CTAs. Paste your copy directly into the chat.
Ask Workshop to follow accessibility best practices: *"Make sure all images have alt text, use semantic HTML, and ensure the contrast ratio meets WCAG AA."*
## Next steps
* [Publishing and custom domains](/workshop-cloud/publishing) — Learn how to deploy and connect your domain
* [Sharing and teams](/workshop-cloud/sharing-and-teams) — Control who can access your site
* [Connectors](/connectors) — Connect databases, APIs, and more
* [Working with the Agent](/core-concepts/working-with-the-agent) — Prompting tips and communicating with Workshop
* [Checkpoints](/workshop-desktop/checkpoints) — Save and restore versions of your project (Workshop Desktop only)
***
Describe the website you want and watch it come to life.
# Anthropic (BYOK)
Source: https://docs.workshop.ai/connectors/anthropic
Connect your own Anthropic API key to Workshop for direct Claude model access.
## Overview
The Anthropic BYOK connector lets you use your own Anthropic API key with Workshop. Usage is billed directly to your Anthropic account.
**Published apps use your API key.** If you publish a Workshop app that uses this connector, visitors make requests using your key. You will be billed by Anthropic for all usage.
**Don't have an API key?** The [managed Anthropic connector](/connectors/managed-ai-connectors) is enabled by default — no API key needed, usage billed to your Workshop credits.
## What You'll Need
| Credential | Description | Format |
| - | - | - |
| **API Key** | Anthropic API authentication key | `sk-ant-...` |
## Getting an API Key
Go to [console.anthropic.com](https://console.anthropic.com) and sign up or sign in.
Navigate to **Settings > Billing**, add a payment method, and purchase credits. The minimum purchase is \$5, which places you in Tier 1.
Go to **Settings > API Keys** and click **Create Key**. Give it a descriptive name (e.g., "Workshop Access"). Optionally assign it to a workspace.
Copy your API key immediately. Anthropic only shows the key once — if you lose it, you'll need to generate a new one.
## Connecting to Workshop
Open the **Workshop Hub** from the sidebar.
Click the **Connectors** tab.
Click the **Anthropic (your API key)** card.
Enter a **Connection Name** (e.g., "My Anthropic API") and paste your **API Key**.
Click **Add Connection**.
Your Anthropic API is now connected and available across all conversations.
## Verifying Your Connection
Ask Workshop:
```
Use my Anthropic connection to summarize the key points of this text: [paste any text]
```
If Workshop returns a Claude-generated summary, your connection is working.
## Security Best Practices
* Your API key is stored in Workshop's encrypted storage — never shared with the AI agent directly
* Rotate keys periodically in the [Anthropic console](https://console.anthropic.com)
* Use Anthropic workspaces to organize keys by project or environment
* If you suspect a key is compromised, delete it immediately in the Anthropic console and create a new one, then update your Workshop connection
## Troubleshooting
| Issue | Solution |
| - | - |
| "Invalid API Key" | Re-enter the key from your Anthropic console. Ensure no extra spaces. |
| "Insufficient credits" | Add more credits in Anthropic billing settings. |
| "Rate limit exceeded" | Wait and retry. Check your usage tier in the Anthropic console. |
## Learn More
* [Anthropic Console](https://console.anthropic.com)
* [Anthropic API Documentation](https://docs.anthropic.com)
* [Rate Limits and Pricing](https://docs.anthropic.com/en/api/rate-limits)
# AWS S3
Source: https://docs.workshop.ai/connectors/aws-s3
Connect your Amazon S3 buckets to Workshop for cloud storage access.
## Overview
Amazon Simple Storage Service (S3) is a cloud object storage service for storing and retrieving any amount of data. Once connected, Workshop can help you explore buckets, list objects, and work with your S3 data through natural conversation.
## What You'll Need
| Credential | Description | Example |
| - | - | - |
| **Access Key ID** | AWS access key identifier | `AKIAIOSFODNN7EXAMPLE` |
| **Secret Access Key** | AWS secret access key | `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` |
| **Default Region** | AWS region for your buckets | `us-east-1` |
## Creating AWS Credentials
Log in to the [AWS Management Console](https://console.aws.amazon.com/) and navigate to **IAM** (Identity and Access Management).
Go to **Users** in the sidebar. Either select an existing user or click **Create user** to create one specifically for Workshop.
Attach the **AmazonS3ReadOnlyAccess** managed policy for read-only access. For access to specific buckets only, create a custom IAM policy.
Select your user, go to the **Security credentials** tab, click **Create access key**, and select **Application running outside AWS**.
Copy both the **Access Key ID** and **Secret Access Key** immediately. The secret is only shown once.
For security, create a dedicated IAM user for Workshop with only the permissions needed to access your S3 buckets. Avoid using root account credentials.
## Connecting to Workshop
Open the **Workshop Hub** from the sidebar.
Click the **Connectors** tab.
Click the **AWS S3** card.
Enter a **Connection Name** (e.g., "Production S3"), your **Access Key ID**, **Secret Access Key**, and **Default Region**.
Click **Add Connection**.
## Verifying Your Connection
Ask Workshop:
```
List all buckets in my S3 connection
```
If Workshop returns your bucket list, the connection is working.
## Using Your Connection
```
Show me all objects in my "data-exports" bucket
```
```
What files were uploaded to my S3 bucket in the last 7 days?
```
```
List all CSV files in the "reports" folder of my analytics bucket
```
```
What's the total size of objects in my backup bucket?
```
## Security Best Practices
* **Least privilege:** Use `AmazonS3ReadOnlyAccess` for read-only operations. For specific buckets, create a custom policy.
* **Dedicated users:** Create a dedicated IAM user for Workshop. Never use root credentials.
* **Key rotation:** Rotate access keys regularly. Create a new key, update Workshop, then delete the old key.
* **Never share keys:** Don't commit credentials to version control or share them publicly.
If you suspect your access key has been compromised, immediately deactivate it in the IAM console and create a new one.
## Troubleshooting
| Issue | Solution |
| - | - |
| Invalid access key | Verify the Access Key ID was copied correctly. Check it's active in IAM (not deactivated). |
| Access denied | Verify the IAM user has S3 permissions. Check bucket policies. Ensure the correct region is specified. |
| Bucket not found | Verify the bucket name (case-sensitive). Ensure it exists in the specified region. |
## Learn More
* [AWS S3 Documentation](https://docs.aws.amazon.com/s3/)
* [IAM Best Practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)
* [S3 Security Best Practices](https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-best-practices.html)
# Data Warehouse Connectors
Source: https://docs.workshop.ai/connectors/data-warehouses
Connect BigQuery, Snowflake, and Tableau to Workshop for enterprise analytics.
## Overview
Workshop supports three data warehouse and business intelligence connectors for enterprise-scale analytics:
| Platform | Authentication | Best For |
| - | - | - |
| [BigQuery](#bigquery) | GCP Service Account JSON | Petabyte-scale analytics on Google Cloud |
| [Snowflake](#snowflake) | Account + User/Password | Cloud data warehousing with separated storage and compute |
| [Tableau](#tableau) | Personal Access Token | Business intelligence dashboards and data visualization |
## General Setup
All data warehouse connectors follow the same workflow:
Open the **Workshop Hub** from the sidebar and click the **Connectors** tab.
Find and click the card for your data warehouse.
Fill in the connection fields described for your platform below.
Give your connection a memorable name and click **Add Connection**.
***
## BigQuery
BigQuery is Google Cloud's serverless data warehouse. Workshop connects via a GCP service account with read-only access.
### What You'll Need
| Credential | Description |
| - | - |
| **Service Account JSON** | A JSON key file from Google Cloud Platform |
### Setting Up Access
Go to the [Google Cloud Console](https://console.cloud.google.com) and create or select a project with BigQuery data.
Go to **APIs & Services > Library**, search for **"BigQuery API"**, and enable it (most projects have it enabled by default).
Go to **IAM & Admin > Service Accounts**, click **Create Service Account**, and enter a name (e.g., "Workshop BigQuery Access").
Add two roles:
* **BigQuery Data Viewer** — read access to tables and views
* **BigQuery Job User** — permission to run queries
Click **Continue**, then **Done**.
Click on the service account, go to the **Keys** tab, click **Add Key > Create new key**, select **JSON**, and click **Create**. The file downloads automatically.
### Connecting to Workshop
1. Click the **BigQuery** card in the Connectors tab
2. Enter a **Connection Name** (e.g., "Analytics Warehouse")
3. Open the JSON key file in a text editor, copy the entire contents, and paste into the **Service Account JSON** field
4. Click **Add Connection**
### Limiting Access to Specific Datasets
For finer control, grant permissions at the dataset level instead of the project level:
1. Go to **BigQuery** in the Cloud Console
2. Click on a dataset, then **Sharing > Permissions**
3. Add the service account email with the **BigQuery Data Viewer** role
### Troubleshooting
| Issue | Solution |
| - | - |
| "Permission denied" | Verify both **BigQuery Data Viewer** and **BigQuery Job User** roles are assigned. |
| "Invalid JSON" | Ensure you copied the entire JSON file contents without extra characters. |
| "Project not found" | Confirm the project ID in the JSON matches an existing project with BigQuery API enabled. |
| Can't see datasets | Grant BigQuery Data Viewer on specific datasets if using dataset-level permissions. |
Keep your service account key file secure. Don't share it or commit it to version control. If compromised, delete the key in the Cloud Console and create a new one.
**Learn more:** [BigQuery Documentation](https://cloud.google.com/bigquery/docs) | [BigQuery IAM Roles](https://cloud.google.com/bigquery/docs/access-control)
## Snowflake
Snowflake is a cloud data warehouse with separated storage and compute. Workshop connects using your account identifier and user credentials.
### What You'll Need
| Field | Required | Description | Example |
| - | - | - | - |
| Account | Yes | Account identifier | `xy12345.us-east-1` |
| User | Yes | Snowflake username | `WORKSHOP_USER` |
| Password | Yes | Snowflake password | — |
| Role | No | Snowflake role | `ANALYST` |
| Warehouse | No | Compute warehouse | `COMPUTE_WH` |
| Database | No | Default database | `ANALYTICS` |
| Schema | No | Default schema | `PUBLIC` |
Role, warehouse, database, and schema are optional. If omitted, Snowflake uses the defaults configured for your user.
### Finding Your Account Identifier
Your account identifier comes from your Snowflake URL:
* If your URL is `https://xy12345.us-east-1.snowflakecomputing.com`, the identifier is `xy12345.us-east-1`
* For `app.snowflakecomputing.com` URLs, go to **Settings > Accounts**, click `...` next to your account, and select **Manage URLs** to find the full URL
### Read-Only Role Setup
```sql theme={null}
CREATE ROLE WORKSHOP_READER;
GRANT USAGE ON DATABASE ANALYTICS TO ROLE WORKSHOP_READER;
GRANT USAGE ON SCHEMA ANALYTICS.PUBLIC TO ROLE WORKSHOP_READER;
GRANT SELECT ON ALL TABLES IN SCHEMA ANALYTICS.PUBLIC TO ROLE WORKSHOP_READER;
```
### Warehouse Cost Considerations
Warehouses incur costs when running. For Workshop:
* Use a smaller warehouse (X-SMALL) for most queries
* Enable auto-suspend to pause the warehouse after inactivity
* Monitor query costs through Snowflake's usage dashboard
### Troubleshooting
| Issue | Solution |
| - | - |
| Invalid account identifier | Verify the format matches your Snowflake URL. Include the region identifier. |
| Authentication failed | Check username/password. Verify user is not locked. Check if MFA is blocking access. |
| Warehouse not found | Verify warehouse name. Check the role has USAGE permission on the warehouse. |
| Access denied | Ensure the role has USAGE on the database/schema and SELECT on tables. |
Create a dedicated service account for Workshop rather than using personal credentials. If MFA is required, you may need a service account without MFA for programmatic access.
**Learn more:** [Snowflake Documentation](https://docs.snowflake.com/) | [Access Control](https://docs.snowflake.com/en/user-guide/security-access-control-overview)
## Tableau
Tableau is a business intelligence platform for interactive dashboards and reports. Workshop connects using a Personal Access Token.
### What You'll Need
| Field | Description | Example |
| - | - | - |
| Token Name | Name of your Personal Access Token | `workshop-integration` |
| Token Secret | Secret value of the token | `dGhpcyBpcyBhIHNlY3JldA==...` |
| Server URL | Tableau Server or Online URL | `https://10ax.online.tableau.com/` |
| Site ID | Your Tableau site identifier | `mycompanysite` |
The **Site ID** is found in your Tableau URL. For example, in `https://10ax.online.tableau.com/#/site/mycompanysite/home`, the Site ID is `mycompanysite`.
### Creating a Personal Access Token
Log in to Tableau Server or Online. Click your profile icon and select **My Account Settings**.
Scroll to **Personal Access Tokens**, enter a descriptive name (e.g., `workshop-integration`), and click **Create new token**.
Copy both the **Token Name** and **Token Secret** immediately. The secret is only shown once.
### Token Expiration
Personal Access Tokens expire if not used for **15 consecutive days**. You must use the token at least once every 15 days to keep it active. If it expires, create a new token and update your Workshop connection.
### Token Permissions
Tokens inherit the permissions of your Tableau user account. For limited access, consider creating a dedicated Tableau user with restricted permissions.
### Example Queries
```
List all workbooks in my Tableau connection
```
```
What data sources are available in my Tableau site?
```
```
Show me the views in the "Sales Dashboard" workbook
```
### Troubleshooting
| Issue | Solution |
| - | - |
| Invalid token | Verify Token Name and Token Secret were copied correctly. |
| Token expired | Create a new token if unused for 15+ days. |
| Site not found | Verify Site ID matches the URL path. For the Default site, try empty or `default`. |
| Server connection failed | Verify the Server URL includes `https://` and is accessible externally. |
**Learn more:** [Tableau Personal Access Tokens](https://help.tableau.com/current/server/en-us/security_personal_access_tokens.htm) | [Tableau REST API](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api.htm)
## Verifying Any Data Warehouse Connection
After connecting, ask Workshop:
```
What datasets are available in my data warehouse?
```
```
Show me the schema of my analytics database
```
```
List all tables I have access to
```
If Workshop returns your data, the connection is working.
# Database Connectors
Source: https://docs.workshop.ai/connectors/databases
Connect PostgreSQL, MySQL, SQL Server, MongoDB, Supabase, Neon, TiDB, and TigerGraph databases to Workshop.
## Overview
Workshop supports eight database connectors covering relational, document, distributed, and graph databases. Once connected, Workshop can query your databases, explore schemas, and help you analyze data through natural conversation.
| Database | Type | Default Port | Required Fields |
| - | - | - | - |
| [PostgreSQL](#postgresql) | Relational | 5432 | Host, Port, Database, Username, Password |
| [MySQL](#mysql) | Relational | 3306 | Host, Port, Database, Username, Password |
| [Microsoft SQL Server](#microsoft-sql-server) | Relational | 1433 | Server, Database, Username, Password |
| [MongoDB](#mongodb) | Document (NoSQL) | 27017 | Host, Port, Username, Password |
| [Supabase](#supabase) | PostgreSQL backend | — | API URL, API Key |
| [Neon](#neon) | Serverless PostgreSQL | — | Connection URL |
| [TiDB](#tidb) | Distributed SQL | 4000 | Host, Port, Database, Username, Password |
| [TigerGraph](#tigergraph) | Graph | — | Host URL, Username, Password, Graph Name |
## General Setup
All database connectors follow the same workflow:
Open the **Workshop Hub** from the sidebar and click the **Connectors** tab.
Find and click the card for your database type.
Fill in the connection fields described for your database below.
Give your connection a memorable name and click **Add Connection**.
## General Security Recommendations
These apply to all database connectors:
* **Create a dedicated read-only user** for Workshop — avoid admin or superuser accounts
* **Use SSL/TLS connections** when available (most cloud providers enable this by default)
* **Restrict network access** via firewalls, IP allowlists, or VPC/private networking
* **Rotate credentials** periodically and update your Workshop connection when you do
Never use superuser or admin accounts (`postgres`, `root`, `sa`, etc.) for Workshop connections. Always follow the principle of least privilege.
***
## PostgreSQL
PostgreSQL is a powerful, open-source relational database. Workshop connects using standard host-based credentials.
If you're using **Neon** (serverless PostgreSQL) or **Supabase**, use their dedicated connectors for a simpler setup.
### Required Fields
| Field | Description | Example |
| - | - | - |
| Host | Server hostname or IP | `postgres.example.com` |
| Port | Server port | `5432` |
| Database | Database name | `myapp_production` |
| Username | PostgreSQL user | `app_user` |
| Password | User password | — |
### Finding Credentials by Provider
* **Amazon RDS:** Endpoint and Port in the Connectivity section of your instance
* **Google Cloud SQL:** Public/Private IP in the instance overview
* **Azure Database:** Server name in the Overview page
* **Self-hosted:** Contact your database administrator
### Read-Only User Setup
```sql theme={null}
CREATE USER workshop_reader WITH PASSWORD 'YourSecurePassword';
GRANT CONNECT ON DATABASE your_database TO workshop_reader;
GRANT USAGE ON SCHEMA public TO workshop_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO workshop_reader;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO workshop_reader;
```
### Troubleshooting
| Issue | Solution |
| - | - |
| Connection refused | Verify host/port. Check `listen_addresses` and `pg_hba.conf`. Verify firewall rules. |
| Authentication failed | Check username/password. Verify `pg_hba.conf` auth method (`md5` or `scram-sha-256`). |
| Database does not exist | Verify exact database name (case-sensitive). Run `\l` in psql to list databases. |
| SSL required | Ensure `sslmode=require` is used. Most cloud providers require SSL by default. |
**Learn more:** [PostgreSQL Documentation](https://www.postgresql.org/docs/)
## MySQL
MySQL is one of the world's most popular open-source relational databases. Workshop connects using standard host-based credentials.
### Required Fields
| Field | Description | Example |
| - | - | - |
| Host | Server hostname or IP | `mysql.example.com` |
| Port | Server port | `3306` |
| Database | Database name | `myapp_production` |
| Username | MySQL user | `app_user` |
| Password | User password | — |
### Finding Credentials by Provider
* **Amazon RDS:** Endpoint and Port in the Connectivity section
* **Google Cloud SQL:** IP address in the instance overview
* **PlanetScale / other managed:** Check provider dashboard for connection details
### Read-Only User Setup
```sql theme={null}
CREATE USER 'workshop_reader'@'%' IDENTIFIED BY 'YourSecurePassword';
GRANT SELECT ON your_database.* TO 'workshop_reader'@'%';
FLUSH PRIVILEGES;
```
### Troubleshooting
| Issue | Solution |
| - | - |
| Connection refused | Verify host/port. Check `bind-address` in my.cnf. Verify firewall rules on port 3306. |
| Access denied | Check username/password. Verify user host part (`'user'@'%'` vs `'user'@'localhost'`). |
| Unknown database | Verify database name spelling and that the user has access. |
**Learn more:** [MySQL Documentation](https://dev.mysql.com/doc/)
## Microsoft SQL Server
SQL Server is Microsoft's enterprise relational database. Workshop connects using SQL Authentication (username/password).
Windows Authentication is not supported through Workshop. Use SQL Authentication mode.
### Required Fields
| Field | Description | Example |
| - | - | - |
| Server | Hostname or IP | `myserver.database.windows.net` |
| Database | Database name | `SalesDB` |
| Username | SQL login | `app_user` |
| Password | SQL password | — |
### Finding Credentials by Provider
* **Azure SQL Database:** Server name in the Overview section of the Azure Portal
* **On-premises:** Contact your database administrator
### Read-Only User Setup
```sql theme={null}
CREATE LOGIN workshop_reader WITH PASSWORD = 'YourSecurePassword';
USE YourDatabase;
CREATE USER workshop_reader FOR LOGIN workshop_reader;
ALTER ROLE db_datareader ADD MEMBER workshop_reader;
```
### Troubleshooting
| Issue | Solution |
| - | - |
| Connection refused | Verify server address. Check firewall rules on port 1433. For Azure, verify IP is allowed. |
| Login failed | Check credentials. Ensure SQL Authentication is enabled (mixed mode). |
| Database not found | Verify database name (case-sensitive on some configs). Check user permissions. |
**Learn more:** [SQL Server Documentation](https://docs.microsoft.com/en-us/sql/sql-server/)
## MongoDB
MongoDB is a NoSQL document database that stores data in flexible, JSON-like documents.
### Required Fields
| Field | Description | Example |
| - | - | - |
| Host | Server hostname | `cluster0.abc123.mongodb.net` |
| Port | Server port | `27017` |
| Username | Database user | `app_user` |
| Password | User password | — |
For MongoDB Atlas (cloud), the host is your cluster address. The default port is typically handled automatically.
### Finding Credentials (Atlas)
1. Log in to [MongoDB Atlas](https://cloud.mongodb.com/)
2. Navigate to your cluster and click **Connect > Connect your application**
3. Use the cluster address as the host and credentials from the **Database Access** section
### Read-Only User Setup
```javascript theme={null}
use admin
db.createUser({
user: "workshop_reader",
pwd: "YourSecurePassword",
roles: [
{ role: "read", db: "yourDatabase" }
]
})
```
### Troubleshooting
| Issue | Solution |
| - | - |
| Connection refused | Verify host/port. For Atlas, ensure your IP is in the **Network Access** allowlist. |
| Authentication failed | Check username/password. Ensure user is in the correct auth database (`admin`). |
| No collections found | Verify the user has read permissions. Check you're connecting to the correct database. |
**Learn more:** [MongoDB Documentation](https://docs.mongodb.com/)
## Supabase
Supabase is an open-source PostgreSQL backend with authentication, storage, and real-time capabilities. Workshop connects via the Supabase API.
### Required Fields
| Field | Description | Example |
| - | - | - |
| API URL | Your project's API URL | `https://abcdefgh.supabase.co` |
| API Key | Your project's anon or service role key | `eyJhbGciOiJIUzI1NiIs...` (JWT) |
### Finding Credentials
1. Go to [supabase.com](https://supabase.com) and open your project
2. Click **Settings > API** for the project URL and API keys
**Which key?** The **anon (public) key** respects Row Level Security (RLS). The **service role key** bypasses RLS and gives full database access. Use the service role key only when you need to bypass RLS.
### Troubleshooting
| Issue | Solution |
| - | - |
| "Invalid API key" | Verify the key and ensure it's from the correct project. |
| "Connection refused" | Confirm the project is active (free-tier projects pause after 7 days of inactivity). |
| Can't see tables | If using the anon key, check RLS policies. Try the service role key to verify tables exist. |
**Learn more:** [Supabase Documentation](https://supabase.com/docs)
## Neon
Neon provides serverless PostgreSQL with on-demand scaling and instant database branching. Workshop connects via a PostgreSQL connection string.
### Required Fields
| Field | Description | Example |
| - | - | - |
| Connection URL | Full PostgreSQL connection string | `postgresql://user:pass@ep-cool-darkness-123456.us-east-2.aws.neon.tech/neondb?sslmode=require` |
### Finding Your Connection String
1. Go to [console.neon.tech](https://console.neon.tech) and select your project
2. Click the **Connect** button
3. Select your Branch, Database, and Role
4. Copy the connection string
**Default database:** New Neon projects create a database called `neondb` with a role called `neondb_owner`.
**Pooled vs. Direct:** Pooled connections (hostname includes `-pooler`) support up to 10,000 connections and work well for most Workshop use cases.
### Troubleshooting
| Issue | Solution |
| - | - |
| "Connection refused" | Verify the connection string is complete. Check the project is active. Ensure `sslmode=require`. |
| Slow initial queries | Normal if the compute has scaled to zero. First query triggers a cold start. |
| "Authentication failed" | Verify username/password in the connection string. Try regenerating the password in the Neon console. |
**Learn more:** [Neon Documentation](https://neon.tech/docs)
## TiDB
TiDB is an open-source, MySQL-compatible distributed SQL database designed for HTAP workloads.
TiDB uses port **4000** by default, not 3306 like standard MySQL.
### Required Fields
| Field | Description | Example |
| - | - | - |
| Host | Cluster hostname | `gateway01.us-east-1.prod.aws.tidbcloud.com` |
| Port | Server port | `4000` |
| Database | Database name | `myapp` |
| Username | TiDB user | `app_user` |
| Password | User password | — |
### Finding Credentials (TiDB Cloud)
1. Log in to [TiDB Cloud](https://tidbcloud.com/) and navigate to your cluster
2. Click **Connect** and choose **General** connection type
3. Copy the Host and Port from the connection string
### Read-Only User Setup
```sql theme={null}
CREATE USER 'workshop_reader'@'%' IDENTIFIED BY 'YourSecurePassword';
GRANT SELECT ON your_database.* TO 'workshop_reader'@'%';
FLUSH PRIVILEGES;
```
### Troubleshooting
| Issue | Solution |
| - | - |
| Connection refused | Verify host/port. Remember TiDB uses port **4000**. For TiDB Cloud, check IP allowlist. |
| Authentication failed | Check credentials. Verify user exists and has the correct password. |
| Slow first query | TiDB Cloud Serverless may have cold start latency. Subsequent queries will be faster. |
**Learn more:** [TiDB Documentation](https://docs.pingcap.com/tidb/stable)
## TigerGraph
TigerGraph is a native parallel graph database for advanced analytics and machine learning on connected data.
### Required Fields
| Field | Description | Example |
| - | - | - |
| Host | Server or Cloud URL | `https://myinstance.i.tgcloud.io/` |
| Username | TigerGraph user | `tigergraph` |
| Password | User password | — |
| Graph Name | Graph to connect to | `MyGraph` |
### Finding Credentials (TigerGraph Cloud)
1. Log in to [TigerGraph Cloud](https://tgcloud.io/) and select your instance
2. Copy the instance URL from the dashboard
3. Open GraphStudio to find available graph names in the top-left dropdown
4. Use the credentials set during instance creation
### Troubleshooting
| Issue | Solution |
| - | - |
| Connection failed | Verify Host URL includes `https://`. Ensure the instance is running. |
| Authentication failed | Check username/password. Verify the user has access to the specified graph. |
| Graph not found | Verify graph name (case-sensitive). Check user permissions for the graph. |
| Timeout | Large graph traversals take time. Add limits to queries or check instance resources. |
**Learn more:** [TigerGraph Documentation](https://docs.tigergraph.com/)
## Verifying Any Database Connection
After connecting, ask Workshop:
```
Show me all tables in my database
```
```
What columns are in the users table?
```
```
How many rows are in each table?
```
If Workshop returns your data, the connection is working.
# Google Gemini (BYOK)
Source: https://docs.workshop.ai/connectors/gemini
Connect your own Google API key to Workshop for direct Gemini model access.
## Overview
The Gemini BYOK connector lets you use your own Google API key with Workshop. Usage is billed directly by Google.
**Published apps use your API key.** If you publish a Workshop app that uses this connector, visitors make requests using your key. You will be billed by Google for all usage.
**Don't have an API key?** The [managed Gemini connector](/connectors/managed-ai-connectors) is enabled by default — no API key needed, usage billed to your Workshop credits.
## What You'll Need
| Credential | Description | Format |
| - | - | - |
| **Google API Key** | API key for Google Gemini access | `AIza...` |
## Getting an API Key
Go to [aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey) and sign in with your Google account.
Click **Create API key**. Select an existing Google Cloud project or create a new one.
Copy your API key immediately. It starts with `AIza` followed by a string of characters. While you can view keys again in Google AI Studio, store it securely right away.
## Connecting to Workshop
Open the **Workshop Hub** from the sidebar.
Click the **Connectors** tab.
Click the **Gemini (your API key)** card.
Enter a **Connection Name** (e.g., "My Gemini API") and paste your **Google API Key**.
Click **Add Connection**.
Your Gemini connection is now active and available across all conversations.
## Verifying Your Connection
Ask Workshop:
```
Use Gemini to explain the concept of machine learning in simple terms
```
If Workshop returns a Gemini-generated response, your connection is working.
## Security Best Practices
* Your API key is stored in Workshop's encrypted storage — never shared with the AI agent directly
* Restrict your key in the [Google Cloud Console](https://console.cloud.google.com/apis/credentials): limit it to only the Generative Language API and add IP or referrer restrictions if needed
* If you suspect a key is compromised, delete it in [Google AI Studio](https://aistudio.google.com/app/apikey) and create a new one
**Free tier data usage:** Content processed through the free tier may be used by Google to improve their products. If you're working with sensitive data, consider using a paid tier.
## Troubleshooting
| Issue | Solution |
| - | - |
| "API key not valid" | Verify the full key was copied and starts with `AIza`. Check it hasn't been deleted. |
| "Permission denied" | Check API restrictions in Google Cloud Console. Ensure the Generative Language API is enabled. |
| "Quota exceeded" | Wait for limits to reset or upgrade your tier. Monitor usage in the Cloud Console. |
## Learn More
* [Google AI Studio](https://aistudio.google.com/)
* [Gemini API Documentation](https://ai.google.dev/docs)
* [API Key Best Practices](https://ai.google.dev/gemini-api/docs/api-key)
* [Pricing and Rate Limits](https://ai.google.dev/pricing)
# GitHub
Source: https://docs.workshop.ai/connectors/github
Connect your GitHub account to Workshop for repository access and API operations.
## Overview
The GitHub connector lets you link your GitHub account to Workshop using a Personal Access Token. Once connected, you can access repositories, analyze code, clone repos, and perform API operations through natural conversation.
**This is different from GitHub Integration.** The GitHub *connector* gives the Workshop agent API access to your repositories and issues via a Personal Access Token. [GitHub Integration](/workshop-cloud/github-integration) is the app-level feature for push/pull syncing between your Workshop project and a GitHub repo — it uses a GitHub App OAuth flow, not a PAT.
## What You'll Need
| Credential | Description | Format |
| - | - | - |
| **Personal Access Token** | Fine-grained or classic GitHub token | `ghp_...` (classic) or `github_pat_...` (fine-grained) |
## Creating a Personal Access Token
Sign in to [github.com](https://github.com), click your profile photo, and select **Settings**.
Scroll down the sidebar and click **Developer settings > Personal access tokens > Fine-grained tokens**.
Click **Generate new token**. Enter a **Token name** (e.g., "Workshop Access"), set an **Expiration** date, and choose the **Resource owner** (your account or an organization).
Under **Repository access**, select which repositories the token can access.
Under **Permissions**, grant the access you need:
* **Contents:** Read (to view files)
* **Metadata:** Read (required for all tokens)
* **Issues:** Read and write (if you want Workshop to create/manage issues)
* **Pull requests:** Read and write (if you want Workshop to create PRs)
Click **Generate token** and copy it immediately. GitHub only shows the token once.
**Organization tokens may require approval.** If you select an organization as the resource owner, the organization may need to approve the token before it becomes active. Check with your organization administrator if the token isn't working.
## Connecting to Workshop
Open the **Workshop Hub** from the sidebar.
Click the **Connectors** tab.
Click the **GitHub** card.
Enter a **Connection Name** (e.g., "My GitHub Account") and paste your **Personal Access Token**.
Click **Add Connection**.
## Using Your Connection
Once connected, you can ask Workshop to work with your GitHub data:
```
Using my GitHub connection, list all my repositories
```
```
Show me the README from my project-name repository
```
```
What are the open issues in my app repository?
```
```
Using my GitHub connection, clone my website repo and help me understand its structure
```
## Security Best Practices
* Use **fine-grained tokens** with the minimum permissions needed
* Set an **expiration date** on all tokens
* Create separate tokens for different integrations
* If you suspect a token is compromised, revoke it immediately in **GitHub Settings > Developer settings > Personal access tokens**
GitHub automatically scans for leaked tokens and may revoke them. Never commit tokens to version control or share them publicly.
## Troubleshooting
| Issue | Solution |
| - | - |
| "Bad credentials" | Verify the token was copied correctly and hasn't expired or been revoked. |
| "Not Found" for repos | Ensure the token has access to the target repository. |
| Rate limiting | GitHub limits API requests to 5,000/hour for authenticated users. Wait for the limit to reset. |
## Learn More
* [GitHub Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
* [Fine-grained Token Permissions](https://docs.github.com/en/rest/overview/permissions-required-for-fine-grained-personal-access-tokens)
# Google Drive
Source: https://docs.workshop.ai/connectors/google-drive
Browse and access your Google Drive files directly within Workshop conversations.
## Overview
The Google Drive connector uses OAuth to link your Google account to Workshop. Once connected, you can browse your Drive files from within conversations using the **@** mention popup — no API keys or service accounts required.
This connector is ideal for:
* Accessing documents stored in Drive without downloading them first
* Referencing Google Docs, Sheets, and Slides in conversations
* Working with files across personal and shared drives
## What You'll Need
| Credential | Description |
| - | - |
| **Google Account** | Your Google account with access to the Drive files you want to use |
**No API keys or service accounts required.** Google Drive uses OAuth — you sign in with your Google account and authorize Workshop to access your files.
## Connecting to Workshop
Open the **Workshop Hub** from the sidebar.
Click the **Connectors** tab.
Click the **Google Drive** card.
Click **Connect with Google**, sign in to your Google account, review the permissions, and click **Allow**.
Give your connection a memorable name (e.g., "My Drive" or "Work Drive") and click **Add Connection**.
**Published apps use your credentials.** When you publish an app that uses your Google Drive connection, it accesses files using your authorization. Be mindful of what files you reference in publicly shared apps.
## Using Your Connection
### Browsing Files with @ Mentions
The primary way to use Google Drive is through the **@** popup:
1. Type **@** in the message input
2. Select your Google Drive connection
3. Browse folders or search for files
4. Click a file to attach it to your message
Workshop reads the file contents and includes them in the conversation context.
### Supported File Types
| File Type | How Workshop Reads It |
| - | - |
| **Google Docs** | Extracted as plain text |
| **Google Sheets** | Exported as CSV data |
| **Google Slides** | Extracted as plain text |
| **Regular files** (PDF, TXT, etc.) | Downloaded directly |
Workshop requests access only to files you explicitly select or reference. Your entire Drive is not automatically indexed or accessed.
### Example Prompts
```
Summarize the key points from this document
```
```
Extract all the action items from this meeting notes document
```
```
Convert this spreadsheet data into a chart showing monthly trends
```
## Security
### OAuth Permissions
Workshop **can**:
* View files you select or reference in conversations
* Read file contents for files you explicitly attach
Workshop **cannot**:
* Modify or delete your files
* Access files you don't explicitly select
* Browse your Drive in the background
### Revoking Access
**From Workshop:** Delete the connection in the Connectors tab.
**From Google:** Go to [Google Account Security](https://myaccount.google.com/security), click **Third-party apps with account access**, find Workshop, and click **Remove Access**.
## Troubleshooting
| Issue | Solution |
| - | - |
| "Authorization failed" | Try reconnecting. Ensure popups aren't blocked. |
| Can't see files in @ popup | Verify the connection is listed in the Connectors tab. Try refreshing the page. |
| "Access token expired" | Delete and reconnect your Google Drive. |
| File content not loading | Very large files may take longer. Binary files (videos, executables) can't be read as text. |
## Learn More
* [Google Drive Help Center](https://support.google.com/drive)
* [Managing Third-Party App Access](https://support.google.com/accounts/answer/3466521)
# Google Sheets
Source: https://docs.workshop.ai/connectors/google-sheets
Connect public or private Google Sheets to Workshop for spreadsheet data access.
## Overview
Workshop supports two modes for connecting Google Sheets:
| Mode | Authentication | Best For |
| - | - | - |
| **Public Sheet** | Sheet URL only | Non-sensitive data shared via "Anyone with the link" |
| **Private Sheet** | GCP Service Account JSON | Confidential data restricted to specific accounts |
Choose the tab below that matches your use case.
## Public Google Sheet
Use this mode when your sheet is shared with **"Anyone with the link"** and contains non-sensitive data. No API keys or service accounts required — just the URL.
### What You'll Need
| Credential | Description |
| - | - |
| **Spreadsheet URL** | The sharing link to your public Google Sheet |
### Making Your Sheet Public
Navigate to your Google Sheet in the browser.
Click the **Share** button in the top-right corner.
Under **General access**, change from "Restricted" to **"Anyone with the link"**. Set permission to **Viewer**. Click **Done**.
Copy the URL from your browser's address bar. It looks like:
```
https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit#gid=0
```
### Connecting to Workshop
Open the **Workshop Hub** and click **Connectors**.
Click the **Public Google Sheet** card.
Enter a **Connection Name** (e.g., "Product Catalog") and paste your **Spreadsheet URL**.
Click **Add Connection**.
Workshop accepts URLs in any standard Google Sheets format (`/edit`, `/view`, or just the sheet ID path).
### Security Considerations
When you make a sheet public, anyone with the URL can view all data in it. Treat the URL as a credential.
Public sheets are appropriate for sample datasets, publicly available information, and shared reference materials. Avoid making sheets public if they contain personal information, financial data, or business-sensitive content.
To revoke public access, change the sheet back to **Restricted** in sharing settings.
## Private Google Sheet
Use this mode when your sheet is restricted to specific users and contains sensitive or confidential data. Requires a Google Cloud Platform (GCP) service account.
**Requires a Google Cloud project.** Accessing private sheets requires a GCP service account, which involves creating a project and sharing your sheet with the service account email. If you prefer simpler setup, consider making your sheet public and using the Public mode instead.
### What You'll Need
| Credential | Description |
| - | - |
| **Spreadsheet URL** | The full URL of your Google Sheet |
| **Service Account JSON** | A JSON key file from Google Cloud Platform |
### Setting Up Access
Go to the [Google Cloud Console](https://console.cloud.google.com). Click **Select a project > New Project**, enter a name (e.g., "Workshop Sheets Access"), and click **Create**.
Go to **APIs & Services > Library**, search for **"Google Sheets API"**, and click **Enable**.
Go to **IAM & Admin > Service Accounts**, click **Create Service Account**, enter a name (e.g., "Workshop Sheets Reader"), and click **Create and Continue**. Select the **Viewer** role, then click **Done**.
Click on the service account, go to the **Keys** tab, click **Add Key > Create new key**, select **JSON**, and click **Create**. The file downloads automatically. Note the `client_email` field inside it.
Open your Google Sheet, click **Share**, paste the service account's `client_email` (looks like `name@project.iam.gserviceaccount.com`), set permission to **Viewer**, uncheck "Notify people", and click **Share**.
The `client_email` in your JSON file looks like: `your-service-account@your-project.iam.gserviceaccount.com`. You must share your sheet with this email for the connection to work.
### Connecting to Workshop
Open the **Workshop Hub** and click **Connectors**.
Click the **Private Google Sheet** card.
Enter a **Connection Name**, paste the **Spreadsheet URL**, and paste the full contents of your **Service Account JSON** key file.
Click **Add Connection**.
### Security Considerations
* The service account only has access to sheets explicitly shared with it
* Share with **Viewer** permission unless Workshop needs to write data
* Once connected, you can delete the JSON key file from your downloads — Workshop stores credentials securely
* To revoke access, remove the service account email from the sheet's sharing settings
## Using Your Connection
Once connected (either mode), ask Workshop to work with your spreadsheet data:
```
Show me the first few rows from my spreadsheet
```
```
Using my Google Sheet connection, create a summary of all entries in column A
```
```
Create a chart from my Google Sheet data showing sales by month
```
### Working with Multiple Tabs
If your spreadsheet has multiple tabs, specify which one:
```
Show me data from the "Sales Q4" tab in my spreadsheet
```
By default, Workshop reads from the first sheet if no tab name is specified.
Workshop works best with spreadsheets under 10,000 rows. For very large datasets, consider using a [database connector](/connectors/databases) or [BigQuery](/connectors/data-warehouses) instead.
## Troubleshooting
| Issue | Solution |
| - | - |
| "Unable to access spreadsheet" (public) | Verify the sheet is set to "Anyone with the link". Try opening the URL in an incognito window. |
| "Permission denied" (private) | Ensure the sheet is shared with the service account `client_email`. |
| "Invalid JSON" (private) | Verify you copied the entire JSON file contents without extra characters. |
| "Google Sheets API not enabled" (private) | Enable the Google Sheets API in your GCP project and wait a few minutes. |
## Learn More
* [Google Sheets API Documentation](https://developers.google.com/sheets/api)
* [Creating Service Accounts](https://cloud.google.com/iam/docs/service-accounts-create)
* [Sharing Google Sheets](https://support.google.com/docs/answer/2494822)
# Connectors
Source: https://docs.workshop.ai/connectors/index
Connect AI providers, databases, and external services to Workshop.
## What Are Connectors?
Connectors link external services to Workshop. Once connected, Workshop can use AI models, query your databases, and access your files across all your conversations — no need to manually copy data or explain your setup each time.
## AI Providers
Workshop includes three built-in AI providers — **Anthropic** (Claude), **OpenAI** (GPT), and **Google Gemini**. Enable them per project via **Add-Ons** in project settings or during project creation. When enabled, Workshop provisions a managed connector that handles API keys, authentication, and billing through your Workshop credits — no setup required.
If you prefer to manage billing directly with a provider, BYOK (Bring Your Own Key) connectors are available for each.
How managed connectors work, what each provider offers, and when to use BYOK instead.
### BYOK Setup Guides
Use your own Claude API key
Use your own GPT API key
Use your own Gemini API key
### Decision Models
Classify, route and score inputs with TypeSafe's decision model, billed to Workshop credits or your own OpenRouter or TypeSafe key.
## Database Providers
Workshop can provision a managed **Neon** serverless Postgres database for your project. Enable it via **Add-Ons** in project settings or during project creation. Workshop handles provisioning, credentials, and cleanup automatically — including **Neon Auth**, a built-in authentication service that keeps your app's auth domains in sync as you publish and add custom domains.
How managed databases work, what gets provisioned, and Neon Auth.
If you already have your own Neon database (or another database), connect it manually:
Connect PostgreSQL, MySQL, SQL Server, MongoDB, Supabase, Neon, TiDB, or TigerGraph with your own credentials.
## Data Connectors
Connect Workshop to your databases, cloud storage, and productivity tools. You provide credentials once, and Workshop can access and query your data in any conversation.
| Connector | Type | Authentication |
| - | - | - |
| [PostgreSQL, MySQL, SQL Server, MongoDB, Supabase, Neon, TiDB, TigerGraph](/connectors/databases) | Databases | Host + credentials or connection URL |
| [BigQuery, Snowflake, Tableau](/connectors/data-warehouses) | Data warehouses | Service account or credentials |
| [Google Sheets](/connectors/google-sheets) | Spreadsheets | URL (public) or Service Account (private) |
| [Google Drive](/connectors/google-drive) | Cloud storage | OAuth |
| [AWS S3](/connectors/aws-s3) | Cloud storage | Access Key + Secret |
| [GitHub](/connectors/github) | Source control API | Personal Access Token |
## Custom Connector
Use a Custom Connector for any API or service that doesn't have a built-in connector, such as your own or a partner's API. It keeps all the credentials for one service together under a single name, and each key/value pair becomes a secret the agent can use.
Open the **Hub** from the sidebar, click the **Connectors** tab, and choose **Custom Connector**.
Enter a **Connection Name**, for example `Inventory API`. This is the name you'll see in the @ mention popup.
Enter each credential as a **Key** and **Value**, for example `API_KEY` and its value. Click **Add Field** for more, then click **Create Connection**.
Mention the connector with **@** in a conversation and the agent will use its credentials to authenticate on your behalf.
## How Connectors Work
When you add a data connector:
1. **Your credentials are stored securely** in Workshop's encrypted storage
2. **Workshop's agent receives a reference** to your connection, not the raw credentials
3. **Data stays in your source** — Workshop queries it on-demand rather than copying it
You maintain full control over your data while giving Workshop the ability to help you work with it.
## Adding a Data Connector
Open the **Workshop Hub** from the sidebar.
Click the **Connectors** tab.
Select the connector type you want to add from the card list, or search by name.
Fill in the required connection details for that connector.
Click **Add Connection**. Workshop tests the connection and saves it.
Once connected, reference your connection by name or type in any conversation:
* *"Using my **Production Database** connection, show me all users who signed up last week"*
* *"Query my **Supabase** data for the top 10 products by revenue"*
## Managing Connections
Your active connections appear in the **Active Connections** table in the Connectors tab. From there you can:
* View connection details and status
* Edit connection credentials
* Delete connections you no longer need
Deleting a connection removes both the connector configuration and its stored credentials from Workshop.
## Security
* **Credentials are encrypted** at rest and in transit
* **Connections use SSL/TLS** for all data transmission
* **Data is queried on demand** — Workshop queries your sources directly and does not store your data separately
* **You control access** — delete connections anytime to revoke access
Published apps use the same connector credentials you configure in development. Be mindful of which connectors you attach to apps you plan to publish.
# Jev
Source: https://docs.workshop.ai/connectors/jev
Connect Jev, TypeSafe's decision model, to classify, route and score inputs in your Workshop apps.
## Overview
[Jev](https://typesafe.ai) is a decision model by TypeSafe. It is not a chat model: instead of generating text, it answers typed questions about an input with calibrated probabilities, in well under a second. Use it in your apps for classification, routing, triage, moderation and scoring.
The Jev connector works in one of three ways, depending on the API key you give it:
| API key | Billing |
| - | - |
| **None** (leave the field empty) | Workshop credits |
| **OpenRouter API key** (`sk-or-...`) | Billed by OpenRouter |
| **TypeSafe API key** | Billed by TypeSafe |
**Published apps use the connector's key.** If you publish a Workshop app that uses this connector, visitors make requests using it — billed to your Workshop credits, or to your OpenRouter or TypeSafe account.
## Connecting to Workshop
Open the **Workshop Hub** from the sidebar.
Click the **Connectors** tab.
Click the **Jev** card.
Enter a **Connection Name** (e.g., "My Jev"). Leave **API Key** empty to use Workshop credits, or paste an OpenRouter or TypeSafe API key.
Click **Add Connection**.
Your Jev connection is now active and available across all conversations. When you leave the key empty, Workshop creates a Workshop API key for the connection. Deleting the connection, or switching it to your own key, revokes that key.
## Verifying Your Connection
Ask Workshop:
```
Build an app that uses Jev to flag incoming support emails as spam or not spam
```
If the app returns a spam probability for each email, your connection is working.
## How Jev Answers
Each request sends an input (the `state`) and one or more named questions. There are three question types:
| Type | Asks | Answer |
| - | - | - |
| `noul` | A yes-or-no question | The probability of yes |
| `choice` | Which of several options fits | The chosen option, with a probability for each |
| `score` | Where the input sits on an ordered scale | A score from 0 (the first level) to the last level's index, with a probability for each level |
Workshop's agent knows how to write these requests; describe the decision you want in plain language.
## When Workshop Uses Jev
When you ask for classification, routing, triage, moderation or scoring that needs no generated text, and don't name an AI provider, Workshop suggests the Jev connector instead of Gemini. Tasks that also generate text, such as drafting a reply to a classified ticket, still default to Gemini. Naming a provider (for example, "use OpenAI") overrides both.
Jev runs in your app's backend, so it isn't available in **Static React App** projects. Use a template with a backend, such as **Dynamic React App**.
## Troubleshooting
| Issue | Solution |
| - | - |
| "Invalid API key" | Check that the full key was copied. OpenRouter keys start with `sk-or-`. |
| Requests fail with 402 | You are out of Workshop credits. Add credits, or switch the connector to your own key. |
| Requests fail with 400 | A question is malformed; the error message names the field. All instructions and criteria must be strings. |
## Learn More
* [TypeSafe](https://typesafe.ai)
* [OpenRouter](https://openrouter.ai)
# Managed AI Connectors
Source: https://docs.workshop.ai/connectors/managed-ai-connectors
Add AI capabilities to your Workshop apps — enabled by default, no API keys or setup required.
## How It Works
Workshop includes managed connectors for **Anthropic** (Claude), **OpenAI** (GPT), and **Google Gemini**. Enable them per project via the **Add-Ons** panel in project settings, or during project creation — some templates (Dynamic React App, Static React App, Dynamic HTML App) auto-enable Gemini by default. No accounts to create, no API keys to manage, no setup steps.
Usage is billed to your Workshop credits. You reference a connector via the **@** mention selector or the **Add Functionality** button in your conversation, and Workshop handles authentication, rate limits, and billing behind the scenes.
Managed AI connectors add AI features **to the apps you build**. They are separate from the model that powers the Workshop agent (which you select in [Settings](/core-concepts/settings)).
## What Each Provider Offers
All three providers are available simultaneously. You can use multiple providers in the same app.
Strong at careful reasoning, long-form writing, and nuanced instruction following.
**Capabilities:** Extended thinking, PDF and image analysis, structured JSON output, tool use.
Workshop provides access to the latest Claude models, from fast and cost-effective to most capable.
[Anthropic Models Documentation →](https://docs.anthropic.com/en/docs/about-claude/models)
Broad general-purpose capabilities including image generation and function calling.
**Capabilities:** Image generation (DALL-E), JSON mode, function calling, embeddings.
Workshop provides access to the latest GPT models across the efficiency-to-capability spectrum.
[OpenAI API Documentation →](https://platform.openai.com/docs)
Excellent at multimodal tasks, very long context windows, and grounded responses.
**Capabilities:** Image generation, video understanding, very long context, grounding.
Workshop provides access to the latest Gemini models, including Flash (fast) and Pro (capable) variants.
[Google Gemini API Documentation →](https://ai.google.dev/docs)
## Using AI Connectors in Your Apps
Reference a connector in your conversation and Workshop handles the rest:
```
Add an AI summary feature to the dashboard using Claude.
```
```
Use OpenAI to generate product descriptions from the database fields.
```
```
Add Gemini image generation — let users describe what they want and generate it.
```
Workshop writes the integration code, manages the API calls, and injects credentials automatically — including when you publish the app.
## Disabling a Managed Connector
If you want to disable an AI provider for a project:
1. Open your project and go to **Settings** → **Resources**
2. Under **Add-Ons** → **AI Providers**, toggle off the provider you want to disable
The connector is removed from the project and your app will no longer be able to call that provider. You can re-enable it at any time by toggling it back on.
## Bring Your Own Key (BYOK)
If you prefer to use your own API keys — to manage billing directly with a provider, access models not available through managed connectors, or meet compliance requirements — BYOK connectors are available for each provider:
* [Anthropic (BYOK)](/connectors/anthropic) — Use your own Claude API key
* [OpenAI (BYOK)](/connectors/openai) — Use your own GPT API key
* [Google Gemini (BYOK)](/connectors/gemini) — Use your own Gemini API key
You can have both managed and BYOK connectors enabled for the same provider simultaneously.
* You want zero setup — just start building
* You don't have accounts with each provider
* You're publishing apps where you want Workshop to handle the API key lifecycle
* You already have a provider account with credits or a billing agreement
* You need access to specific models not available through managed connectors
* You want usage billed directly to your provider account
* Your organization requires direct provider relationships for compliance
## Security
Workshop handles API key management for managed connectors automatically:
* Keys are generated securely on your behalf
* Keys are stored encrypted and never exposed to the AI agent directly
* Keys are automatically revoked when you delete a connector
* You never need to manage or rotate keys manually
## Troubleshooting
Verify your internet connection. Try deleting and re-enabling the connector.
Check your Workshop credit balance in **Settings > Usage and Billing**.
# Managed Database
Source: https://docs.workshop.ai/connectors/managed-database
Add a serverless Postgres database with built-in authentication to your Workshop project — one click, no setup required.
## How It Works
Workshop can provision a managed **Neon** serverless Postgres database for your project. Enable it via the **Add-Ons** panel in project settings, or during project creation — some templates (Dynamic React App, Static React App, Dynamic HTML App) auto-enable Neon by default. No accounts to create, no credentials to manage, no setup steps.
When you enable the database, Workshop provisions:
* A **Neon serverless Postgres** instance with a dedicated project and branch
* **Neon Auth** — a built-in authentication service powered by Better Auth
* **Connection credentials** injected automatically into your app's environment
The managed database is available to the apps you build and publish. Workshop's agent can query it, create tables, and write data on your behalf during development.
## What You Get
### Serverless Postgres
A full PostgreSQL database that scales to zero when idle and wakes on demand. No capacity planning, no cold start management — Workshop handles it.
Your app receives these environment variables automatically:
| Variable | Description |
| - | - |
| `DATABASE_URL` | Pooled connection string (recommended for most use cases) |
| `DIRECT_URL` | Direct connection string (for migrations and schema changes) |
### Neon Auth
Every managed database comes with **Neon Auth** enabled — a hosted authentication service that gives your app user sign-up, sign-in, and session management out of the box.
Your app receives:
| Variable | Description |
| - | - |
| `NEON_AUTH_URL` | Base URL for the authentication service |
Workshop automatically keeps your app's **trusted domains** in sync — when you publish your app, rename its slug, or add a custom domain, Workshop updates the Neon Auth configuration so authentication works seamlessly across all your app's URLs.
## Using the Database in Your Apps
Reference the database in your conversation and Workshop handles the rest:
```
Create a users table and add a registration form that saves to the database.
```
```
Add authentication to my app using Neon Auth.
```
```
Query the database and show a chart of signups by month.
```
Workshop writes the integration code, manages the connection, and injects credentials automatically — including when you publish the app.
## Disabling the Database
If you want to remove the database from a project:
1. Open your project and go to **Settings** → **Resources**
2. Under **Add-Ons** → **Database Providers**, toggle off **Neon**
3. Confirm the removal in the dialog
Removing the database **permanently destroys** the Neon database instance and all its data. This action cannot be undone. Make sure to export any data you need before disabling.
## Bring Your Own Database
If you already have a Neon database — or prefer to use another database provider — you can connect it manually instead:
* [Neon, PostgreSQL, MySQL, and more](/connectors/databases) — Connect using your own credentials
You can have both a managed database and manually connected databases in the same project.
## Security
Workshop handles database credentials for managed databases automatically:
* Credentials are generated securely on your behalf
* Credentials are stored encrypted and never exposed to the AI agent directly
* Credentials are automatically cleaned up when you remove the database
* Neon Auth trusted domains are kept in sync with your app's published URLs
## Troubleshooting
Try toggling the database off and back on in Add-Ons. If the issue persists, check your internet connection and try again.
Workshop syncs trusted domains automatically when you publish or update your app's URL. If auth isn't working, try re-publishing your app to trigger a domain sync.
Normal if the database has scaled to zero. The first query triggers a cold start — subsequent queries are fast.
# OpenAI (BYOK)
Source: https://docs.workshop.ai/connectors/openai
Connect your own OpenAI API key to Workshop for direct GPT model access.
## Overview
The OpenAI BYOK connector lets you use your own OpenAI API key with Workshop. Usage is billed directly to your OpenAI account.
**Published apps use your API key.** If you publish a Workshop app that uses this connector, visitors make requests using your key. You will be billed by OpenAI for all usage.
**Don't have an API key?** The [managed OpenAI connector](/connectors/managed-ai-connectors) is enabled by default — no API key needed, usage billed to your Workshop credits.
## What You'll Need
| Credential | Description | Format |
| - | - | - |
| **API Key** | OpenAI API authentication key | `sk-proj-...` |
## Getting an API Key
Go to [platform.openai.com](https://platform.openai.com) and sign in or create an account.
Click **Settings > Billing**, add a payment method, and add credits (minimum \$5). Billing is required before the API key will work.
Click **API keys** in the sidebar, or go directly to [platform.openai.com/api-keys](https://platform.openai.com/api-keys).
Click **Create new secret key**, enter a name (e.g., "Workshop Access"), and optionally select a project.
Copy your key immediately. OpenAI only shows it once — if you lose it, you'll need to generate a new one.
## Connecting to Workshop
Open the **Workshop Hub** from the sidebar.
Click the **Connectors** tab.
Click the **OpenAI (your API key)** card.
Enter a **Connection Name** (e.g., "My OpenAI Account") and paste your **API Key**.
Click **Add Connection**.
Your OpenAI account is now connected and available across all conversations.
## Verifying Your Connection
Ask Workshop:
```
List the available OpenAI models
```
If Workshop returns a list of models, your connection is working.
## Security Best Practices
* Your API key is stored in Workshop's encrypted storage — never shared with the AI agent directly
* Rotate keys periodically at [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
* Use OpenAI projects to organize keys by application
* If you suspect a key is compromised, delete it immediately in your OpenAI settings and create a new one
## Troubleshooting
| Issue | Solution |
| - | - |
| "Invalid API key" | Verify the full key was copied. Ensure format is `sk-proj-...`. |
| "Insufficient quota" | Check billing at [platform.openai.com](https://platform.openai.com/settings/organization/billing). Add credits if needed. |
| "Rate limit exceeded" | Wait and retry. Check rate limits in your OpenAI dashboard. |
| "Model not found" | Verify model access. Some models require special access or are in limited beta. |
## Learn More
* [OpenAI API Documentation](https://platform.openai.com/docs)
* [API Key Best Practices](https://platform.openai.com/docs/guides/production-best-practices)
* [Rate Limits Guide](https://platform.openai.com/docs/guides/rate-limits)
* [OpenAI Pricing](https://openai.com/pricing)
# Context and Memory
Source: https://docs.workshop.ai/core-concepts/context-and-memory
How Workshop remembers your project — the .workshop/ directory, context files, rules, skills, and how context carries across conversations.
## How Workshop knows your project
Every conversation starts fresh in terms of the AI context window — but Workshop doesn't start from zero. It reads project context files at the beginning of each conversation, giving it persistent knowledge about your project's architecture, conventions, and current state.
This context lives in the `.workshop/` directory at your project root.
## The `.workshop/` directory
```
your-project/
├── .workshop/
│ ├── context.md # Project context — what Workshop should know
│ ├── rules.md # Project rules — how Workshop should behave
│ └── skills/ # Custom skills for specialized tasks
├── src/
├── README.md
└── ...
```
### `context.md`
The primary project context file. Workshop reads this at the start of every conversation to understand your project's architecture, current state, and conventions.
**How to update it:**
* **Using `/context`:** Type `/context` in any conversation. Workshop analyzes your project files and conversation history, then updates `context.md` with an intelligent summary.
* **With custom focus:** Type `/context focus on API patterns` to steer what gets emphasized.
* **Manually:** Edit `.workshop/context.md` directly to add or correct information.
**When to update:**
* After completing a major feature or milestone
* Before starting a new conversation in an existing project
* When Workshop seems to have forgotten important project details
### `rules.md`
Project-specific rules that guide Workshop's behavior. Use this for coding standards, naming conventions, framework preferences, and any guidelines Workshop should follow consistently.
```markdown theme={null}
# Project Rules
- Use TypeScript for all new files
- Follow BEM naming for CSS classes
- All API endpoints must include input validation
- Write tests for every new utility function
```
Rules are different from context: context describes *what your project is*, rules describe *how Workshop should behave* when working on it.
### `skills/` directory
Custom skills are reusable instruction sets for specialized tasks. They extend Workshop's capabilities for project-specific workflows like deployment, testing patterns, or domain operations.
## Context file precedence
Workshop checks for context files in a specific order, using the first one found:
| Priority | File | Description |
| - | - | - |
| 1 (highest) | `.workshop/context.md` | Workshop's native context format |
| 2 | `.workshop/rules.md` | Workshop's rules file |
| 3 | `.cursor/rules/*.mdc` | Cursor-compatible rules (all `.mdc` files concatenated) |
| 4 (lowest) | `.cursorrules` | Legacy Cursor rules file |
Only the highest-priority file found is loaded — they are not merged. If you have both `.workshop/context.md` and `.cursorrules`, only `context.md` is used.
If you're migrating from another AI coding tool, Workshop automatically picks up your existing `.cursorrules` or `.cursor/rules/` files — no changes needed.
## Custom instructions
Custom Instructions are global preferences set in **Settings** (wrench icon) that Workshop follows across **all** conversations and projects. Think of them as your personal defaults.
```
Every visualization should have a transparent background and white labels.
```
```
When building web applications, prioritize clean, accessible design and responsive layouts.
```
```
Always commit working code after each major milestone.
```
Custom Instructions differ from `rules.md` in scope: custom instructions apply everywhere, rules apply to a specific project.
For details on where to set them, see [Settings](/core-concepts/settings).
## Context window management
AI models have limited context windows — the amount of information they can process at once. As you use more of the window, costs increase, latency increases, and response quality can degrade.
### Keep conversations focused
Each conversation should have a clear purpose — one feature, one bug fix, one exploration thread. Starting new conversations for different tasks keeps context clean and relevant.
### Use `/compact` proactively
Don't wait for Workshop to warn you. If a conversation has been going for a while and you've completed a logical milestone, compact and continue. See [Working with the Agent](/core-concepts/working-with-the-agent) for details on the `/compact` command.
### Maintain your `context.md`
A well-maintained `context.md` means Workshop starts every conversation with a solid understanding of your project. This reduces the need to re-explain architecture, conventions, and current state.
### Provide files strategically
There are two ways to give Workshop files, and they serve different purposes:
**Inline attachments (content)** — Drag and drop files into the chat, paste images, or use the upload button in the message toolbar. These files are sent as part of your message. Use this for material Workshop should *work with directly* — images to display, CSVs to process, reference screenshots, or code files you want modified.
**Project sources (context)** — Add files, connectors, and secrets through the **Sources panel** in the sidebar. These become persistent project context that Workshop reads across all conversations. Use this for material Workshop should *understand and reference* — design specs, API documentation, data schemas, or configuration files.
| Method | When to use | Persists across conversations? |
| - | - | - |
| **Attach in chat** (drag/paste/upload) | Workshop should act on this file *now* | No — scoped to the current message |
| **Sources panel** (sidebar) | Workshop should *know about* this file in every conversation | Yes — part of project context |
If you find yourself re-attaching the same file in multiple conversations, add it to your project sources instead. Workshop will reference it automatically.
### Auto-compaction
When your conversation approaches the context window limit, Workshop automatically compacts it — summarizing the conversation so far and continuing seamlessly. You don't need to do anything; long conversations stay fast without manual intervention. See [Working with the Agent](/core-concepts/working-with-the-agent#auto-compaction) for details.
# Conversations and Projects
Source: https://docs.workshop.ai/core-concepts/conversations-and-projects
How Workshop organizes your work into projects and conversations for a structured, productive development experience.
## Conversations
Conversations are the primary way you interact with Workshop. They follow a chat structure and are made up of pairs of user-Workshop interactions called *turns*.
Each conversation lives within a project and maintains its own history, context, and state. You can have multiple conversations within the same project — useful for separating different features, debugging sessions, or exploration threads.
### Starting a new conversation in a new project
Click the **Home** button at the top of the left panel, then type your prompt. Starting a conversation from the Home screen creates a new project and assigns the conversation to it.
### Starting a new conversation in an existing project
Navigate to the project you want from the Home screen, then write your prompt in the input field. The new conversation will be associated with that project, sharing its files, context, and settings.
A conversation can only belong to a single project, but a project can contain many conversations.
### When to start a new conversation
Start a **new conversation** when you:
* Begin working on a separate feature or task
* Want a clean context window after a long session
* Need to explore an alternative approach without affecting your current thread
* Have used `/compact` to condense and continue (the parent becomes read-only)
**Continue an existing conversation** when you:
* Are iterating on the same feature
* Need Workshop to remember recent decisions and context
* Are debugging something discussed earlier in the thread
## Projects
A project is a structured container for your work with Workshop. It groups conversations, files, settings, and context around a specific goal or codebase. On your file system, a project corresponds to a specific directory.
Projects ensure that all actions, code, and files are associated with the correct context. The environment you set up in one conversation is available to other conversations in the same project.
### The project screen
Each project has its own page with the following sections:
A description rendered from the `README.md` file in the project directory.
A list of all conversations in the project. Click any conversation to navigate to it.
Project-specific rules rendered from `.workshop/rules.md` that guide Workshop's behavior.
A browser for all assets in the project directory.
### Creating a new project
Click **"+ New Project"** on the Home screen. You will be prompted to choose between:
1. **Create new project** under the Workspace directory — use this when starting from scratch. Provide a project name and Workshop creates the directory for you.
2. **Select existing folder** (Workshop Desktop only) — use this when you have an existing codebase or directory on your machine you want Workshop to work on.
3. **Import from Git** — use this when your code is in a repository. Paste the repository URL and Workshop clones it for you. See [GitHub integration](/workshop-desktop/github-integration). On Workshop Cloud the same option appears in the template picker as **Import from GitHub**, and clones into your cloud project — see [Templates](/workshop-cloud/templates#import-from-github).
### Creating a project from a template
Workshop Templates are ready-made starting points. Browse them under **Templates** on the Home screen.
When you select a template, Workshop clones it into your local environment and it becomes available as one of your projects.
### Renaming a project
Rename a project from the **top bar breadcrumb** — click the project name and select **Rename**, or use the project dropdown menu (⋯). You can also rename via the desktop menu bar under **Project → Rename Project**.
### Renaming a conversation
Click the conversation name in the top bar or open the conversation dropdown menu (⋯) and select **Rename**. Giving conversations descriptive names makes it easier to find them later — especially in projects with many threads.
## Project context
Every Workshop project can include a `.workshop/` directory at its root containing project-level configuration that Workshop reads automatically — including context files, rules, and custom skills.
For details on the `.workshop/` directory structure, context file precedence, and how project memory works, see [Context and Memory](/core-concepts/context-and-memory).
## Working across environments
**Workshop Cloud** — Projects live on a cloud virtual machine. You can sync projects to Workshop Desktop using [Web ↔ Desktop Sync](/core-concepts/web-desktop-sync) to continue working locally.
**Workshop Desktop** — A project corresponds to a directory in your Workspace folder on your computer. Workshop has direct access to your local file system. You can push changes back to Workshop Cloud using Web ↔ Desktop Sync.
Projects created with **Create new project** go into your Workspace folder, which by default lives in your home directory:
| Platform | Location |
| - | - |
| **Windows** | `%USERPROFILE%\Workspace` |
| **macOS** | `~/Workspace` |
| **Linux** | `~/Workspace` |
Projects created with **Select existing folder** stay where they already are and are not moved into Workspace. To open the folder for the project you are working on, whichever way it was created, see [Opening the project folder](/workshop-desktop/file-system-and-terminals#opening-the-project-folder).
Both environments share the same project structure and conversation model, so your workflow stays consistent regardless of where you build.
# Settings
Source: https://docs.workshop.ai/core-concepts/settings
Configure how Workshop's agent behaves and how the platform operates — from model selection to secrets management.
Workshop has two categories of settings: **Agent Settings** control how the AI behaves during conversations, and **App Settings** configure platform-level capabilities and integrations.
## Agent Settings
Access Agent Settings in either of two ways: click the **gear icon** in the left sidebar to open Settings, then select the **Agent** tab; or click the **+ button** in the message input box and choose **Agent Settings**. These affect how Workshop operates during conversations.
### Custom instructions
Custom Instructions set consistent guidelines that Workshop follows across **all** your conversations. They act as extensions to Workshop's system prompt, reflecting your personal preferences.
```
Every visualization should have a transparent background and white labels.
```
```
When building web applications, prioritize clean, accessible design and responsive layouts.
Use TypeScript for all JavaScript projects.
```
```
Always commit working code after each major milestone.
```
**Best practices:**
* **Be specific but not restrictive.** `"Include proper error handling in APIs"` is good. `"Only use Express 4.18.2 with these exact middleware packages"` is too rigid.
* **Focus on consistent preferences.** Instructions that apply across conversations work best — project-specific rules belong in `.workshop/rules.md`.
* **Match your skill level.** Beginners: `"Explain technical concepts in simple terms."` Advanced: `"Focus on efficiency and assume familiarity with development tools."`
### Model selector
Choose which AI model powers your conversations. The model selector appears as a chip in the message input toolbar.
Models are grouped by provider. Each model shows interactive ratings for speed, intelligence, reliability, and cost so you can pick the right tradeoff for your task.
**Anthropic (Claude)**
| Model | Best for | Relative cost |
| - | - | - |
| **Claude Haiku 4.5** | Fast tasks, rapid iteration | \$ |
| **Claude Sonnet 5** | Everyday development — the default | \$\$\$\$ |
| **Claude Opus 4.7** | Complex problems requiring deep reasoning | \$\$\$\$\$ |
| **Claude Opus 4.6** | Deep reasoning with high reliability | \$\$\$\$\$ |
**OpenAI (GPT)**
| Model | Best for | Relative cost |
| - | - | - |
| **GPT-5.4 Nano** | Lightweight, low-cost text tasks | \$ |
| **GPT-5.4 Mini** | Balanced speed and capability | \$\$ |
| **GPT-5.4** | Complex tasks requiring high intelligence | \$\$\$\$ |
**Google (Gemini)**
| Model | Best for | Relative cost |
| - | - | - |
| **Gemini 3.1 Flash-Lite** | Fastest option, great for simple tasks | \$ |
| **Gemini 3.1 Pro** | Capable reasoning with strong intelligence | \$\$\$\$ |
**Open Source**
| Model | Best for | Relative cost |
| - | - | - |
| **GLM-5.1** | High-intelligence open-source (text only) | \$ |
| **GLM-5** | Capable open-source alternative (text only) | \$ |
| **GLM-5 Turbo** | Fast open-source option (text only) | \$ |
| **GLM-5V Turbo** | Open-source with image understanding | \$ |
| **Kimi K2.6** | Multimodal open-source — attach screenshots | \$\$ |
Open Source models are significantly cheaper than premium models — 4–8× lower cost per turn. They're a good choice for straightforward tasks where you want to conserve credits.
#### ARC
**ARC** — at the top of the model selector — is the simplest way to keep your credit use down. Instead of committing to one fixed model, it matches your work to a model suited to it: a lighter, cheaper model for routine tasks, and a more capable one for harder ones. Because it avoids running the most expensive model on work that doesn't need it, ARC stretches your credits further — and it means you don't have to pick a model for every task.
ARC is powered by [Rayline](https://rayline.ai), which handles the model routing behind the scenes. You can switch between ARC and a specific model at any time during a conversation — a common pattern is a fast, cheaper model for exploration, a balanced model for building, and a top-tier model for hard problems.
### Code execution control
Control when Workshop executes code on your system.
Workshop executes code blocks automatically without asking. Recommended once you're comfortable with Workshop's behavior.
Workshop shows you each code block before execution. You choose to **Run** or **Skip**. Useful for sensitive systems, learning, or reviewing implementation steps.
### Max turns
Limit how many autonomous actions Workshop takes before stopping for your input. By default, Workshop continues working until it completes your request. When enabled, use the slider to set a limit from 1 to 25 turns.
| Use case | Turns | Why |
| - | - | - |
| Learning / reviewing | 1–3 | See each step of the implementation |
| Moderate oversight | 5–10 | Regular check-ins without micromanagement |
| Full automation (default) | Off | Let Workshop complete tasks without interruption |
### Thinking mode
When enabled, Workshop works through problems step-by-step before jumping to solutions, showing its reasoning process.
| Level | Label | Description |
| - | - | - |
| 1 | **Light** | Simple problem breakdown, quick decision explanations |
| 2 | **Balanced** | Thorough analysis, multiple approaches considered |
| 3 | **Deep** | Comprehensive exploration, detailed trade-off analysis |
| 4 | **Max** | Extensive reasoning, multiple solution paths explored |
Despite using more tokens per message, Thinking Mode often reduces overall credit consumption by producing more accurate solutions on the first attempt.
For complex problems, pairing **Genius** model with **Thinking Level 3–4** produces exceptional results, though at higher credit cost.
### Local model setup (Desktop only)
Connect Workshop Desktop to a local Anthropic Messages API-compatible server, such as llama.cpp or Ollama with an adapter.
Provide the URL of your local model server (e.g., `http://127.0.0.1:8080`).
Enter a display name for the model (e.g., `qwen3-coder-30b`). This is for your reference only.
Click **Test Connection** to verify Workshop can reach your local server. On success, the local model is automatically enabled.
For a full guide on setting up and using local models, see [Local Models](/workshop-desktop/local-models).
### Skills
Skills are a cross-platform core concept in Workshop.
In Desktop, use the **Skills** tab in Settings to install, enable, disable, and import skills that extend the agent's capabilities.
For the complete skills guide (concept + Desktop workflows), see [Core Concepts → Skills](/core-concepts/skills).
### Sub Agents
The **Sub Agents** tab lets you set a persistent default model for each built-in sub-agent. This is the durable alternative to overriding a model [mid-conversation](/core-concepts/sub-agents#choosing-models-for-sub-agents) — set it once and it applies to **every new conversation**, instead of just the current delegation.
Each built-in sub-agent (`explore`, `plan`, `verification`, `reviewer`, `web-search`, `frontend`, and `visual-qa`) has a dropdown:
* Leave it on **Default** to use the agent's recommended model.
* Pick any available model to override it. Overridden agents are highlighted so you can see your customizations at a glance.
* Agents that require vision (such as **visual-qa**) only list vision-capable models.
Click **Save Settings** to apply your overrides, or **Reset All to Defaults** to clear them. Changes take effect on new conversations.
For the full list of built-in agents and the models you can route them to, see [Core Concepts → Sub-agents](/core-concepts/sub-agents).
### Task Management
When enabled, Workshop creates and maintains structured task lists when implementing project plans. Workshop automatically breaks down plans into discrete, trackable tasks, updating their status as work progresses.
Task lists and plans are stored as files in your project directory (for example `tasks.json` and `plan.md`, sometimes grouped under subfolders like `tasks/` or `plans/`), so you can review progress at any time — even outside of Workshop.
### Quick reference by experience level
* **Custom Instructions:** `"Explain technical concepts clearly and provide step-by-step guidance"`
* **Code Execution:** Manual approval for learning
* **Max Turns:** 3–5 for oversight
* **Thinking Mode:** Level 2 for educational benefit
* **Custom Instructions:** Focus on tech stack preferences and coding standards
* **Code Execution:** Automatic for speed
* **Max Turns:** 10+ or off
* **Thinking Mode:** Level 3–4 for complex problems only
* **Custom Instructions:** Include team coding standards and review practices
* **Code Execution:** Manual for shared environments
* **Max Turns:** 5–7 for reviewable progress
* **Context management:** Workshop [automatically compacts](/core-concepts/working-with-the-agent#auto-compaction) when your context window fills up, but you can also `/compact` proactively at milestones
***
## App Settings
Access App Settings through the main **Settings** menu (gear icon). These apply across all projects and conversations.
### Secrets management
Secrets are sensitive values like API keys, database passwords, or access tokens that your applications need. Workshop provides a built-in system to store and use them securely.
We recommend defining secrets through a [Custom Connector](/connectors#custom-connector). It keeps all the credentials for a service together under one name that you can @-mention in conversations.
**How secrets work:**
* **Workshop Cloud:** Secrets are encrypted, stored securely, and available to the agent in your dedicated isolated environment.
* **Workshop Desktop:** Workshop uses your operating system's native keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) to store values. Raw values are never stored in Workshop's own files, and secrets remain on your machine.
* **Key tracking:** Workshop maintains a list of secret *names* you've stored, but actual values are encrypted and kept in secure storage.
**Managing secrets:**
Click **Hub** in the left sidebar and select the **Secrets** tab. In Workshop Cloud you can also go straight to [app.workshop.ai/hub?tab=secrets](https://app.workshop.ai/hub?tab=secrets).
Enter a descriptive key name (e.g., `OPENAI_API_KEY`, `DATABASE_PASSWORD`), enter the value, and click **Add Secret**.
Click the **Edit secret** icon next to the secret, paste the new value, and click **Update Secret**.
Reference secrets by their key name in your prompts:
```
Use the API key stored as 'STRIPE_API_KEY' to configure the payment gateway.
```
**Security details:**
* **Case insensitive:** Workshop finds secrets regardless of case — `OPENAI_API_KEY`, `openai_api_key`, and `OpenAI_API_Key` all work.
* **Permission prompts (Desktop):** The first time Workshop accesses a secret, your OS may ask for permission. You can approve permanently or per-session.
* **Scope (Desktop):** Secrets are available to all projects within Workshop on that machine.
### MCP servers (Desktop only)
The [Model Context Protocol](https://modelcontextprotocol.io/introduction) is a standard for connecting AI models to tools, data sources, and services. Workshop supports both **using** and **building** MCP servers.
**Managing MCP servers:**
Go to **Settings** (gear icon) > **MCP** tab to browse three sections:
| Section | Description |
| - | - |
| **Configured Servers** | View, enable/disable, and manage your installed MCP servers |
| **Server Directory** | Browse and install curated, Workshop-tested servers (Neon, Netlify, GitHub, Context7, and more) |
| **Add Custom Server** | Install any MCP server from the broader ecosystem via GitHub URL or local path |
**Using MCP in conversations:**
Workshop integrates with enabled MCP servers naturally — often requiring no special instructions:
```
Use playwright to check if this website loads correctly and take a screenshot.
```
```
Use the Neon MCP to create a new table for user profiles in our database.
```
**Building MCP servers:**
Workshop can build MCP servers from natural language descriptions, test them, and add them to your available tools — all in a single conversation.
**Best practices:**
* Only enable servers you're actively using to reduce context overhead
* Test new servers in non-critical projects first
* Use Secrets for server authentication credentials
* Disable unused tools within servers to keep context focused
### Control Center
The Control Center provides quick-action buttons for common development tasks, accessible from within your project.
**Version control** — Initialize Git, make commits, and manage your repository with single clicks. Workshop often handles this automatically during development; the Control Center lets you trigger it at specific moments.
**Application management** — Start, stop, and monitor your applications. Workshop analyzes your project structure and creates custom startup scripts, handling environment activation, dependency loading, and complex startup sequences.
**Documentation generation** — Generate or improve your project's `README.md` from the current project structure with one click.
**Interactive Terminal** — Workshop handles command-line tools that require interactive input — scaffolding wizards, interactive installers, deployment setup. Terminal sessions are visible in the Control Center.
### Privacy Mode
Your code is never stored anywhere other than your machine.
With **Privacy Mode** enabled, your conversations are also never stored externally. When disabled, Workshop may collect usage and telemetry data to improve the product.
Privacy Mode is available to Build, Scale, and Max plan users. Manage it from **Settings** > **Other**.
### Sound settings
Toggle whether Workshop plays a sound notification when the agent finishes a task. Useful for knowing when a long-running operation completes while you're doing other work.
# Skills
Source: https://docs.workshop.ai/core-concepts/skills
Skills are reusable instruction sets that give the Workshop agent domain expertise. Import skills from GitHub, compile them from your data layer, or write them by hand.
## What are skills?
Skills are structured context documents that give the Workshop agent specialized knowledge about a domain, codebase, or dataset. When a skill is loaded, the agent reads it at the start of each conversation — giving it persistent expertise that goes beyond general knowledge.
Think of skills as "expert briefings" — they tell the agent what your data means, how your APIs work, what your design system looks like, or how your deployment pipeline runs.
## Managing skills in Settings
Skills work the same way in Workshop Cloud and Workshop Desktop. In both products, open **Settings → Skills** to manage what capabilities are installed and enabled.
*Skills are managed from Settings with search, filtering, and quick install actions.*
**What you can do in Skills settings:**
* **Browse installed skills** and read each skill's description
* **Search** by name or description
* **Filter to Official** skills only
* **Enable/disable** skills with the toggle on each card
* **Install official skills** to your user space
* **Remove custom skills** (user or project/plugin, depending on source)
* **Add custom skills** from ZIP, official catalog, or GitHub
Workshop shows a warning before disabling an official skill because it can reduce your agent's baseline capabilities.
### Adding skills
Use **+ Add** in the Skills tab to choose how you want to install a skill.
*Add from ZIP, from official skills, or by importing from GitHub.*
**Option 1: Upload `.zip`** — Choose this when you already have a packaged skill archive. Click **+ Add → Upload .zip**, select your file, and Workshop installs it.
**Option 2: Add from official** — Choose this for curated, Workshop-maintained skills. Click **+ Add → Add from official**, pick from the modal list, and click **Install**.
**Option 3: Import from GitHub** — Choose this when your skill lives in a GitHub repository. Click **+ Add → Import from GitHub**, then paste a public repo URL or connect GitHub to browse your repos (including private ones).
*The GitHub import flow supports both direct public URLs and connected-account repository browsing.*
### Skill sources
In practice, you'll encounter these source types:
* **Official/system**: Workshop-maintained defaults
* **User**: installed into your personal skill space
* **Project/plugin**: tied to project/plugin context
If you're not sure where to install a skill, start with **user-level** so it's available across your work.
## The `.workshop/skills/` directory
Skills live in your project's `.workshop/skills/` directory:
```
your-project/
├── .workshop/
│ ├── context.md
│ ├── rules.md
│ └── skills/
│ ├── data/
│ │ ├── SKILL.md # Entry point
│ │ └── ref/
│ │ ├── sources.md
│ │ ├── staging.md
│ │ └── marts.md
│ └── design-system/
│ └── SKILL.md
├── src/
└── ...
```
Each skill is a directory containing a `SKILL.md` entry point and optional reference files. The agent reads `SKILL.md` first and follows references as needed.
## Importing skills from GitHub
Workshop supports importing skills directly from GitHub repositories — both public and private.
Push your skill files to a GitHub repository. The repository should contain the skill directory structure with a `SKILL.md` entry point.
If the repository is private, connect your GitHub account in Workshop via **Hub** → **Connectors** → **GitHub**.
In your Workshop project, import the skill from the repository. Workshop downloads the skill files and makes them available to the agent.
Skills imported from GitHub can be updated when the source repository changes. In the future, Workshop will support automatic pulling of the latest version.
## dbt-skillz: compiling data skills
The most common use of skills today is grounding agents in your data warehouse schema. [dbt-skillz](https://github.com/atlasfutures/dbt-skillz) is an open-source compiler that turns your dbt project into a structured agent skill.
```bash theme={null}
# Install
pip install dbt-skillz
# Compile your dbt project into a skill
dbt-skillz compile --project-dir ./analytics --output ./skills/data
```
The compiled skill includes:
* **Model descriptions** — what each table represents
* **Column types and documentation** — field-level context
* **Metric definitions** — governed calculations
* **Test constraints** — data quality rules
* **Lineage graph** — how models depend on each other
When the agent builds a dashboard or writes a query, it reads these definitions instead of guessing. See [Trusted Dashboards](/solutions/trusted-dashboards) for the full lifecycle.
dbt-skillz works with any coding agent — Claude, Cursor, Windsurf, and more. It's not Workshop-specific, but Workshop provides the deepest integration.
## Other skill use cases
Skills aren't limited to data. Common examples include:
Provide your API documentation as a skill so the agent writes correct integrations, uses the right endpoints, and handles authentication properly.
Give the agent your component library documentation, color tokens, and layout conventions so it generates UI that matches your brand.
Document your team's conventions — naming patterns, testing requirements, architectural decisions — so the agent follows them from the first line of code.
Describe business logic, regulatory requirements, or industry-specific terminology so the agent understands your domain context.
## Skills vs. context vs. rules
| Feature | `context.md` | `rules.md` | Skills |
| - | - | - | - |
| **Purpose** | What the project is | How to behave | Domain expertise |
| **Scope** | Entire project | Entire project | Specific domain |
| **Updated by** | `/context` command or manual | Manual | Compiler or manual |
| **Example** | "This is a Next.js e-commerce app" | "Use TypeScript strict mode" | "Here are all dbt metric definitions" |
## Writing skills by hand
You can create skills manually for any domain:
1. Create a directory under `.workshop/skills/` (e.g., `.workshop/skills/my-skill/`)
2. Add a `SKILL.md` file as the entry point
3. Optionally add reference files in subdirectories
```markdown theme={null}
# My Skill
## Overview
This skill provides context about [domain].
## Key Concepts
- Concept A: explanation
- Concept B: explanation
## Reference
See [detailed reference](ref/details.md) for more.
```
Keep skills focused — one domain per skill. The agent can load multiple skills simultaneously.
***
Open-source data skill compiler. Apache 2.0.
The full lifecycle for data-grounded dashboards.
Step-by-step guide to building dashboards with Workshop.
# Sub-agents
Source: https://docs.workshop.ai/core-concepts/sub-agents
Orchestrate multiple AI models — across providers and environments — in a single workflow.
## What are sub-agents?
Workshop's main agent can spin up helper agents to handle specific tasks inside the same workflow. These are called **sub-agents**.
Each sub-agent runs in its own separate context window. It reads files, runs tools, and does its work without consuming the main agent's context. When it's done, only a short summary comes back to your main conversation.
Sub-agents don't all need to use the same model. They can use different models, from different providers — and in Workshop Desktop, they can even run in different environments, including local models on your device.
*Three sub-agents researching in parallel, each with a live progress indicator.*
## Why this matters
You no longer need one model to do everything. Different parts of a workflow can be delegated to the models best suited for those parts.
Some models are better at certain types of tasks than others. By delegating subtasks to better-fit models, the overall workflow produces better results than any single model could.
Not every task needs a top-tier model. Simpler or narrower subtasks can be routed to more affordable models, reducing overall cost without sacrificing quality where it matters.
Some tasks benefit more from speed than from maximum intelligence — reading large volumes of text, scanning files, repetitive processing. These can be delegated to faster models to keep things moving.
Sub-agents work without consuming the main agent's context in the same way. You can keep building in the same conversation without hitting limits as quickly.
### Privacy and control
Workshop can combine cloud models with local models. That means you can keep your main workflow powered by a frontier cloud model, but route a sensitive task to a local model running on your device.
This is especially useful when a task involves:
* Private data or sensitive internal files
* Content you don't want sent to an external inference provider
* Compliance requirements around data residency
Local model routing requires [Workshop Desktop](/workshop-desktop/local-models). Workshop Cloud uses cloud-hosted models only.
### The real differentiator
It's not just "multiple models." Workshop lets you orchestrate multiple models, from multiple providers, across cloud and local environments, in the same workflow — frontier cloud models, open-source models, and local models working together in one product experience.
Use the best AI for each part of the job, instead of forcing one model to do everything.
***
## How sub-agents work
As conversations grow longer, the agent's performance gradually declines — it may lose track of earlier decisions, repeat work, or miss details it would have caught earlier. This happens because every AI conversation has a **context window**: the total amount of information the agent can work with at once. Everything counts — your messages, files it reads, tool outputs, its own responses. You can see the context window filling up as a percentage in the UI. As it fills, quality drops. Eventually, you'll need to either start fresh or use `/compact` to summarize and continue.
Sub-agents solve this by working outside your main conversation — each one gets its own fresh context window, does its work, and returns only a short summary. That keeps your main conversation lean and focused.
### Why sub-agents matter
Without sub-agents, every file read and tool call fills your context window, limiting how complex a task can be. Sub-agents handle the heavy lifting in their own space, so your main conversation stays focused on the big picture and stays sharp for longer.
A sub-agent with a single clear objective — "review this diff for security issues" or "explore how the payment flow works" — dedicates its full attention to that one job, without being distracted by the rest of your conversation.
Up to 3 sub-agents run simultaneously, each potentially on a different model. A quick search uses a fast model; a thorough code review uses a more capable one. You get speed and specialization without managing any of it.
### Built-in agents
Workshop includes six specialized agents, each with a focused toolset:
| Agent | What it does | Default model | Why | Best for |
| - | - | - | - | - |
| **explore** | Searches code, reads files, traces call chains. Read-only. | Haiku 4.5 | Fast read-only searches don't need a heavy model | "Where is this defined?", "How does auth work?", pattern searches |
| **plan** | Analyzes codebase, produces structured implementation plans with steps, critical files, and risks. | Inherits yours | Benefits from the same model you're reasoning with | Planning before coding — especially multi-step features |
| **verification** | Adversarial checker that reviews your changes for regressions, missing tests, and edge cases. Returns PASS/FAIL verdict. | Inherits yours | Should match the reasoning depth of your main workflow | Sanity check after implementation, before you move on |
| **reviewer** | Code review specialist. Hunts for bugs, security issues, correctness problems. Can run linters and tests. | GPT-5.4 | Strong at code review and reasoning about diffs | PR-style review of a diff or changed files |
| **web-search** | Searches the web for docs, best practices, API references, error solutions. | Haiku 4.5 | Speed matters more than depth for lookups | Looking up documentation, debugging error messages |
| **frontend** | Full-stack frontend dev. Can read, write, edit files and run dev servers/build tools. | GLM-5.1 | Optimized for frontend and long-horizon UI tasks | Building or fixing UI components, CSS, frontend code |
You can override the default model for any built-in agent mid-conversation — see [Choosing models](#choosing-models-for-sub-agents) below.
### How to trigger sub-agents
Tell Workshop to use sub-agents in your prompt. The key phrase is **"use sub-agents"** or **"delegate"** — Workshop will recognize the intent and spin up the right agents:
```
Build me a landing page. Use sub-agents to research color palette
trends, look up hero section best practices, and find open-source
icon libraries — all in parallel before you start coding.
```
You can also name specific agents:
```
Have the reviewer agent check the changes we just made.
```
```
Use the explore agent to trace how the payment flow works.
```
Workshop may also delegate on its own when it judges a task benefits from specialization — but being explicit gives you more control over what gets delegated and how.
Multiple sub-agents can run simultaneously. Each one appears as a collapsible card in your chat with a live progress indicator.
*All three research agents finished in 73.9 seconds. The main agent synthesizes the results and starts building.*
### Limits
* Sub-agents **cannot spawn their own sub-agents** (depth limit of 1)
* Each sub-agent starts fresh — it cannot see your conversation history, so include everything it needs in the delegation prompt
* Sub-agents complete autonomously — they cannot ask you questions mid-task
## Choosing models for sub-agents
Each built-in agent has a default model chosen for its task type — shown in the Built-in agents table above. You can override any of them two ways: **mid-conversation** by just asking, or **persistently** in Settings.
To set a default model for a built-in agent that applies to **every new conversation**, open the **Sub Agents** tab in [Settings](/core-concepts/settings#sub-agents). The mid-conversation method below is best for one-off overrides.
### Changing a model mid-conversation
You don't need to configure anything upfront. Just tell Workshop which model you want a sub-agent to use, and it will apply that for the delegation:
```
Have the reviewer agent check these changes, but use Gemini 3.1 Pro.
```
```
Run the explore agent on Sonnet for this one — I need deeper analysis.
```
```
Use Claude Opus for the plan agent on this refactor.
```
Workshop passes the model assignment through to the sub-agent when it delegates. The available models are:
| Model | Provider | Best for | Speed | Cost |
| - | - | - | - | - |
| `haiku` | Anthropic | Fast, focused tasks — searches, file scans, checklists | Fastest | Low |
| `sonnet` | Anthropic | Balanced — code review, refactoring, documentation | Fast | Medium |
| `opus` | Anthropic | Complex reasoning — architecture, multi-file analysis | Slower | Highest |
| `gpt-5.4` | OpenAI | Backend coding, code review, general-purpose reasoning | Fast | Medium |
| `gpt-5.4-mini` | OpenAI | Lighter tasks at lower cost | Fast | Low |
| `gpt-5.4-nano` | OpenAI | Simple tasks, lowest cost | Fastest | Lowest |
| `gemini-3.1-pro` | Google | Frontend dev, long-context analysis (1M token window) | Fast | Medium |
| `gemini-3.1-flash` | Google | Fast general-purpose tasks, large context | Fastest | Low |
| `glm-5.1` | Z.ai | Frontend dev, long-horizon tasks, cost-efficient coding | Fast | Lowest |
| `glm-5` | Z.ai | General-purpose coding | Fast | Low |
| `glm-5-turbo` | Z.ai | Fast coding tasks | Fastest | Lowest |
| `glm-5v-turbo` | Z.ai | Vision + coding tasks | Fast | Low |
| `kimi-k2.6` | Moonshot | Coding, reasoning, multilingual tasks | Fast | Low |
***
## Create your own agents
Workshop's six built-in agents handle most workflows out of the box — you don't need to create custom agents to use sub-agents. This section is for teams who want to define their own reusable agents for specialized or repeated tasks.
Beyond the built-in agents, you can define **custom agents** — reusable markdown files that give Workshop specialized personas, toolsets, and instructions for tasks you run repeatedly.
Workshop implements the [Agent Skills](https://agentskills.io) open standard — the same format used by Claude Code, Cursor, GitHub Copilot, Gemini CLI, OpenAI Codex, and [many other tools](https://agentskills.io/home). Agents you create for Workshop work in any compatible client, and vice versa.
### Quick start
Create an `agents/` directory in one of the supported paths and add a markdown file:
```
your-project/
├── .workshop/agents/ # Workshop-native (recommended)
├── .agents/agents/ # Cross-client standard path (works in all compatible tools)
└── .claude/agents/ # Claude Code compatible
```
Pick whichever path fits your team. If you want your agents to work across Workshop, Claude Code, Cursor, and other tools, use `.agents/agents/`. If you only use Workshop, `.workshop/agents/` is the simplest choice.
Each file is one agent. The filename (minus `.md`) becomes the agent name.
```markdown theme={null}
---
description: Reviews code changes for quality, test coverage, and common pitfalls.
model: haiku
tools:
- Read
- Grep
- Bash
---
You are a QA reviewer. When given a branch or set of changes:
1. Read every changed file
2. Check for missing error handling, edge cases, and test coverage gaps
3. Verify naming conventions match the surrounding code
4. Report findings as a numbered list with file:line references
```
```
Have the qa-reviewer agent check the changes on this branch.
```
Workshop matches your request to the agent by its **description** field and delegates the task with the specified model and tools.
### Agent file format
Each agent file uses YAML frontmatter followed by markdown instructions:
```markdown theme={null}
---
description: What this agent does (required — this is how Workshop decides when to use it)
model: haiku
tools:
- Read
- Grep
- Bash
maxTurns: 10
---
Your detailed instructions go here. This is the agent's system prompt —
tell it what role to play, what steps to follow, and what output format to use.
```
**Frontmatter fields:**
| Field | Required | Description |
| - | - | - |
| `description` | Yes | What the agent does. Workshop uses this to match your requests to the right agent. Be specific. |
| `model` | No | Model to use: `haiku`, `sonnet`, or `opus`. Defaults to your conversation's model. Use `haiku` for fast, focused tasks. |
| `tools` | No | List of tools the agent can use (e.g., `Read`, `Bash`, `Grep`, `Edit`). Defaults to all tools. |
| `maxTurns` | No | Maximum number of turns before the agent stops. Useful for keeping agents focused. |
| `disallowedTools` | No | Tools the agent cannot use, even if otherwise available. |
| `hidden` | No | If `true`, the agent won't appear in the agent list but can still be used by name. |
| `memory` | No | Memory scope: `user`, `project`, or `local`. Controls where the agent stores learned context. |
The `description` field is crucial — it's how Workshop decides which agent to delegate to. Write it like a job title and responsibility summary, not a vague label.
### Where to put agents
Place agents in `.workshop/agents/` at your project root. These are shared with your team via version control — great for project-specific workflows like deployment checks, code review standards, or domain-specific analysis.
```
your-project/
└── .workshop/
└── agents/
├── deploy-check.md
├── api-reviewer.md
└── db-migration-validator.md
```
Place agents in `~/.workshop/agents/` (your home directory). These are available in every project but aren't shared with your team — useful for personal productivity agents.
```
~/.workshop/
└── agents/
├── commit-message-writer.md
└── research-assistant.md
```
Project agents take precedence over personal agents when names conflict.
### Cross-client compatibility
Workshop implements the [Agent Skills](https://agentskills.io) open standard, which means your custom agents are portable across a growing ecosystem of AI development tools — including Claude Code, Cursor, GitHub Copilot, Gemini CLI, OpenAI Codex, Roo Code, and more.
Workshop discovers agents from three directory paths in priority order:
| Path | Purpose |
| - | - |
| `.workshop/agents/` | Workshop-native (recommended) |
| `.agents/agents/` | Cross-client standard path — works in any [compatible tool](https://agentskills.io/clients) |
| `.claude/agents/` | Claude Code compatibility |
If the same agent name exists in multiple directories, the first match wins.
If your team uses multiple AI tools, put your agents in `.agents/agents/` — they'll be discovered by Workshop, Claude Code, Cursor, and every other tool that supports the [Agent Skills standard](https://agentskills.io). One set of agents, every tool.
### Writing effective agents
The quality of your agent depends on three things: a precise description, the right model, and clear instructions.
#### Descriptions that trigger reliably
The `description` field is how Workshop decides which agent to delegate to. Front-load the key action and context:
```yaml theme={null}
# Too vague — when would Workshop use this?
description: Helps with code
# Too broad — matches everything
description: A general purpose assistant for development tasks
# Missing the "when" — what triggers it?
description: Knows about our API conventions
```
```yaml theme={null}
# Specific action + clear trigger
description: Reviews code changes for security vulnerabilities, injection risks, and auth bypass. Use when reviewing PRs or before merging.
# Domain + action + scope
description: Validates database migrations for safety, rollback paths, and index impact. Use before applying migrations to production.
# Clear capability boundary
description: Generates TypeScript types from OpenAPI specs. Use when API contracts change or when adding new endpoints.
```
#### Choosing the right model
Workshop supports models from multiple providers. Refer to the [full model table](#choosing-models-for-sub-agents) above for the complete list with speed and cost guidance. When setting the `model` field in your agent file:
* Use `haiku` for fast, focused tasks (searches, file scans, checklists)
* Use `sonnet` for balanced tasks (code review, refactoring, documentation)
* Use `opus` for complex reasoning (architecture decisions, multi-file analysis)
* For frontend-heavy agents, `glm-5.1` or `gemini-3.1-pro` are strong choices
* For backend code review, `gpt-5.4` excels
If you omit `model`, the agent inherits your conversation's current model.
#### Structuring instructions
Write instructions like you're briefing a capable colleague who has no context. Include:
1. **Role** — Who the agent is and what lens it uses
2. **Steps** — Numbered sequence of what to do
3. **Constraints** — What to avoid or what boundaries to respect
4. **Output format** — How to structure the response
```markdown theme={null}
---
description: Reviews PRs for security issues including injection, auth bypass, and data exposure.
model: haiku
tools:
- Read
- Grep
- Bash
maxTurns: 12
---
You are a security reviewer. For each changed file:
1. Read the diff with `git diff main...HEAD`
2. Check for:
- SQL injection (string concatenation in queries)
- XSS (unescaped user input in templates)
- Auth bypass (missing permission checks)
- Secret exposure (hardcoded keys, tokens, passwords)
3. For each finding, cite the exact file and line
## Output
Return findings as:
| Severity | File:Line | Issue | Fix |
|----------|-----------|-------|-----|
| HIGH | src/api.ts:42 | Raw SQL interpolation | Use parameterized query |
If no issues found, say "No security issues detected" — don't fabricate findings.
```
### Agents vs skills
Workshop supports both **agents** and **[skills](/core-concepts/skills)**. They serve different purposes:
| | Agents | Skills |
| - | - | - |
| **What they are** | Autonomous sub-conversations with their own model, tools, and context window | Instruction documents loaded into your current conversation |
| **How they run** | In a separate context — can't see your chat history | Inline — become part of your conversation |
| **Best for** | Delegated tasks: "review this", "check that", "research X" | Persistent knowledge: conventions, patterns, reference material |
| **File format** | Single `.md` file with frontmatter | Directory with `SKILL.md` and optional supporting files |
| **Location** | `.workshop/agents/`, `.agents/agents/`, `.claude/agents/` | `.workshop/skills/`, `.agents/skills/`, `.claude/skills/` |
Use an **agent** when you want to hand off a complete task. Use a **skill** when you want Workshop to know something while working with you.
### Example agents
An agent that runs pre-deployment safety checks with a structured PASS/FAIL verdict:
```markdown theme={null}
---
description: Runs pre-deployment safety checks including test status, migration review, and environment variable validation.
model: haiku
tools:
- Read
- Grep
- Bash
maxTurns: 15
---
You are a deployment readiness checker. Run through this checklist
and report a PASS/FAIL verdict for each item:
## Checklist
1. **Tests passing** — Run the test suite and confirm 0 failures
2. **No debugger statements** — Grep for `debugger`, `binding.pry`,
`console.log` in changed files
3. **Migration safety** — If any new migrations exist, verify they
have a rollback path
4. **Environment variables** — Check that any new env vars referenced
in code are documented in `.env.example`
5. **No secrets in code** — Scan for hardcoded API keys, tokens,
or passwords
## Output format
Return a summary table:
| Check | Status | Details |
|-------|--------|---------|
| Tests | PASS/FAIL | ... |
| ... | ... | ... |
End with a clear **DEPLOY** or **DO NOT DEPLOY** recommendation.
```
An agent that reads your code and generates API documentation:
````markdown theme={null}
---
description: Generates API documentation from source code. Reads route handlers, extracts endpoints, parameters, and response shapes, and produces markdown documentation.
model: sonnet
tools:
- Read
- Grep
maxTurns: 20
---
You are an API documentation writer. Given a codebase:
1. Find all route/endpoint definitions (look for decorators like
@app.get, @router.post, or framework-specific patterns)
2. For each endpoint, extract:
- HTTP method and path
- Request parameters (path, query, body)
- Response shape and status codes
- Authentication requirements
3. Organize by resource (e.g., /users/*, /projects/*)
## Output format
For each endpoint:
### `METHOD /path`
> Brief description
**Auth:** Required / Public
**Parameters:**
| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
**Response:** `200 OK`
```json
{ "example": "response" }
````
Sort endpoints alphabetically within each resource group.
````
A read-only agent that helps new team members understand a codebase:
```markdown
---
description: Explores and explains a codebase for new team members. Maps architecture, identifies key patterns, and answers questions about how things work.
model: haiku
tools:
- Read
- Grep
maxTurns: 25
---
You are a codebase guide helping a new team member get oriented.
Start by understanding the project structure:
1. Read the top-level directory and key config files
2. Identify the tech stack (languages, frameworks, build tools)
3. Map the main modules and their responsibilities
4. Find the entry points (main files, route definitions, etc.)
Then answer the user's specific questions with:
- File paths and line numbers for every claim
- Diagrams (ASCII) for complex relationships
- "I don't know" when you genuinely can't determine something
Never guess. If you're unsure, say so and suggest where to look.
````
An agent that generates tests for existing code:
```markdown theme={null}
---
description: Writes tests for existing code. Reads the implementation, identifies edge cases, and generates comprehensive test files following the project's testing conventions.
model: sonnet
tools:
- Read
- Grep
- Edit
- Bash
maxTurns: 20
---
You are a test engineer. When asked to write tests:
1. Read the target file and understand its public interface
2. Grep for existing test files to learn the project's testing
conventions (framework, assertion style, file naming)
3. Identify test cases:
- Happy path for each public function/method
- Edge cases (empty input, null, boundary values)
- Error cases (invalid input, missing dependencies)
4. Write the test file following the project's existing patterns
5. Run the tests to verify they pass
## Rules
- Match the existing test style exactly (don't introduce new patterns)
- Use real implementations over mocks when possible
- Each test should be independent — no shared mutable state
- Name tests descriptively: what's being tested and what's expected
```
### Best practices
One agent, one job. An agent that "reviews code, writes tests, and deploys" will do all three poorly. Create separate agents for each concern.
Most custom agents don't need the most powerful model. `haiku` is fast, cheap, and capable enough for grep-and-report tasks. Save `sonnet` and `opus` for complex reasoning.
Set `maxTurns` to prevent agents from spiraling. A focused agent should finish in 10-15 turns. If it needs more, the instructions probably aren't specific enough.
Only give agents the tools they need. A read-only reviewer doesn't need `Edit` or `Bash`. Fewer tools means fewer ways to go wrong.
Tell the agent exactly how to structure its response — tables, checklists, JSON. Without this, you'll get inconsistent free-form text.
Commit project agents to your repo. They're documentation of your team's workflows, reviewable in PRs, and automatically available to anyone who clones the project.
# Web ↔ Desktop Sync
Source: https://docs.workshop.ai/core-concepts/web-desktop-sync
Sync project files between Workshop Cloud and Workshop Desktop so you can work on the same project from either environment.
Workshop Cloud and Workshop Desktop can sync project files directly, without a separate GitHub repository. This lets you start a project on the web, continue on desktop, and push changes back — or the other way around.
Web ↔ Desktop Sync is separate from [GitHub Integration](/workshop-desktop/github-integration). GitHub sync connects your project to your own repository for version control and collaboration. Web ↔ Desktop Sync moves files between Workshop's two environments — no GitHub account required.
## How It Works
Push and pull to move your project files between Workshop Cloud and Workshop Desktop:
| Action | What happens |
| - | - |
| **Push from Desktop** | Sends your local project files to Workshop Cloud |
| **Pull to Desktop** | Downloads the latest files from Workshop Cloud into your local project |
| **Push from Cloud** | Sends your cloud project files to Workshop Desktop |
| **Pull to Cloud** | Downloads the latest files from Workshop Desktop into your cloud project |
Syncing is manual — you decide when to push and pull. Nothing happens automatically.
## Getting Started
### Starting from Workshop Cloud
Build your project on the web as usual. Your files are stored in the cloud workspace.
Open the project settings and click **Push** in the **Web ↔ Desktop Sync** section. This sends your project files so Desktop can download them.
In Workshop Desktop, go to the **Projects** page. Cloud projects that haven't been downloaded yet appear at the top. Click the **download** button to pull the project files to your machine.
Your project is now on Desktop with all its files. Push and pull as needed to keep both sides up to date.
### Starting from Workshop Desktop
The **Web ↔ Desktop Sync** section only appears for a project that was downloaded from Workshop Cloud. A project created directly in Workshop Desktop does not have this section. To move a Desktop-created project to Workshop Cloud or another machine, use [GitHub Integration](/workshop-desktop/github-integration) instead.
For a project that was originally downloaded from Workshop Cloud, you can push local changes back up:
Navigate to your project and open the settings panel. The **Web ↔ Desktop Sync** section appears under **Integrations**.
Click the **Push to web** button (up arrow). This sends your local project files so Workshop Cloud can access them.
Sign in to Workshop Cloud with the same account. Your project appears in the project list. Open it and pull the latest changes.
## Using the Sync Controls
The **Web ↔ Desktop Sync** section appears in the project settings panel under **Integrations**. In Workshop Cloud it is always available; in Workshop Desktop it appears only for projects that were downloaded from Workshop Cloud. It shows:
* The last push and pull timestamps
* Sync status (when refreshed)
* Three action buttons:
| Button | Action |
| - | - |
| **Up arrow** | Push your changes to the other environment |
| **Down arrow** | Pull changes from the other environment |
| **Refresh** | Check the current sync status |
### Sync Status
After clicking **Refresh**, the status indicator shows:
| Status | Meaning |
| - | - |
| **In sync** | Both sides have the same files |
| **Local ahead** | You have unpushed local changes |
| **Remote ahead** | The other side has changes you haven't pulled |
| **Diverged** | Both sides have independent changes |
## Handling Conflicts
If both Workshop Cloud and Desktop have made independent changes to the same project, a pull may result in a merge conflict. Workshop detects this and prompts you:
* **Force pull** overwrites your local files with the other side's version. Workshop asks for confirmation before proceeding.
Force pull is a destructive operation. The overwritten local changes cannot be recovered. Make sure you know which version you want to keep before confirming.
## Web ↔ Desktop Sync vs GitHub Integration
Both features sync project files, but they serve different purposes:
| | Web ↔ Desktop Sync | GitHub Integration |
| - | - | - |
| **Purpose** | Move files between Workshop Cloud and Desktop | Version control with your own GitHub repo |
| **GitHub account required** | No | Yes |
| **Collaboration** | Between your own Cloud and Desktop environments | With anyone who has access to the repo |
| **Use together** | Yes — both can be active on the same project | Yes |
# Working with the Agent
Source: https://docs.workshop.ai/core-concepts/working-with-the-agent
How to communicate with Workshop, scope your work, and get the best results — from first prompt to iterative refinement.
## How Workshop builds
Workshop defaults to **Build Mode** — you describe what you want, and it starts building. For most tasks, this is all you need. Describe the goal, provide context, and iterate on the results.
When a project needs more upfront thinking, **Plan Mode** is available as a scoping tool. It acts like an experienced technical product manager — asking questions, pushing back on scope, and producing a structured plan before any code gets written.
Neither mode is "the right way." Build Mode is the default because most interactions are iterative. Plan Mode is there when you need it.
## Model selector
Workshop is multi-model and multi-provider — you choose which model powers your main agent. Open the model selector in the top-left of the conversation to switch at any time.
**For most projects, we recommend a strong orchestrator model** like Claude Sonnet 4.6, GLM-5.1, or GPT-5.4. These models are especially good at breaking down complex tasks, using tools effectively, and delegating work to [sub-agents](/core-concepts/sub-agents) when needed. If you need maximum performance on a complex project, top-tier models like Claude Opus will produce excellent results — just note they consume more credits. A strong orchestrator will also delegate simpler subtasks to faster, cheaper models automatically, so you're not paying top-tier rates for everything.
**Smaller models like Gemini 3.1 Flash or Claude Haiku 4.5** are a good choice for quick, focused tasks that aren't part of a larger project — reading a document, summarizing something, or answering a question. They're fast and cost-efficient, but may underperform on multi-step builds or complex orchestration.
If you're using Workshop Desktop, local models are also available in the selector — see [Local Models](/workshop-desktop/local-models) to set them up.
To keep credit use down without picking a model yourself, choose **ARC** at the top of the selector — Workshop routes your work to a suitable model, using a cheaper one for routine tasks and a stronger one for harder ones. See [ARC in Settings](/core-concepts/settings#arc).
Open the model selector and click **"What's this?"** at the top for a detailed breakdown of what each model is best at.
The currently available models are:
| Model | Provider | Best for | Speed | Cost |
| - | - | - | - | - |
| Claude Sonnet 4.6 | Anthropic | Balanced — code, review, orchestration | Fast | Medium |
| Claude Haiku 4.5 | Anthropic | Fast, focused tasks — searches, scans, checklists | Fastest | Low |
| Claude Opus 4 | Anthropic | Complex reasoning — architecture, multi-file analysis | Slower | Highest |
| GPT-5.4 | OpenAI | Backend coding, code review, general-purpose reasoning | Fast | Medium |
| GPT-5.4 Mini | OpenAI | Lighter tasks at lower cost | Fast | Low |
| GPT-5.4 Nano | OpenAI | Simple tasks, lowest cost | Fastest | Lowest |
| Gemini 3.1 Pro | Google | Frontend dev, long-context analysis (1M token window) | Fast | Medium |
| Gemini 3.1 Flash | Google | Fast general-purpose tasks, large context | Fastest | Low |
| GLM-5.1 | Z.ai | Frontend dev, long-horizon tasks, cost-efficient coding | Fast | Lowest |
| GLM-5 | Z.ai | General-purpose coding | Fast | Low |
| GLM-5 Turbo | Z.ai | Fast coding tasks | Fastest | Lowest |
| GLM-5v Turbo | Z.ai | Vision + coding tasks | Fast | Low |
| Kimi K2.6 | Moonshot | Coding, reasoning, multilingual tasks | Fast | Low |
This list is updated regularly as new models become available. For the latest, check the model selector in the app.
For more on how different models work together in a single workflow, see [Sub-agents](/core-concepts/sub-agents).
## Communicating effectively
The clearer you are about what you want, the better Workshop can deliver. Think of it as a collaborative conversation.
### Be specific and descriptive
Vague prompts produce generic results. Specificity gives Workshop the information it needs to make the right decisions.
```
Make me a website.
```
```
Create a responsive website for my consulting business with a home page,
services page, about page, and contact form. Use a professional design
with navy blue and gold. Include a sticky navigation menu.
```
### Provide context and purpose
Tell Workshop *why* you're building something, not just *what*. Context about your situation, audience, and constraints leads to better decisions.
```
Build a database.
```
```
I need a database to track inventory for my small retail business. Store
information about products (name, SKU, price, quantity, category, supplier),
suppliers (name, contact info, payment terms), and sales transactions.
```
### Iterate and refine
Building software is iterative. Instead of expecting perfection on the first try, guide Workshop through incremental improvements with specific feedback.
```
This isn't right. Fix it.
```
```
The layout looks good, but I'd like three changes: 1) Make the navigation
menu more prominent, 2) Add email validation to the contact form, and
3) Add a gallery section to showcase past projects.
```
## Prompting by intent
### Starting a project
Give Workshop a clear picture of what you're building, who it's for, and what success looks like.
```
I'd like to create a fitness tracking app called "FitTracker". The goal is to
monitor workouts, nutrition, and progress toward specific goals. Users should
see a dashboard summarizing their activity, calorie intake, and workout
history. Include data visualization for tracking progress.
```
### Describing design and UI
Reference specific styles, colors, layouts, and interaction patterns rather than abstract adjectives.
```
The interface should follow a minimalist design with navy, white, and light gray.
Use subtle shadows and rounded corners for a modern feel.
```
```
Add a navigation menu with Home, Products, Services, About, and Contact. Fixed
at the top, collapses into a hamburger on mobile. Highlight the active page.
```
### Defining functionality
Describe user interactions as specific scenarios — what the user does, what should happen, and what edge cases to handle.
```
When a user clicks "Submit", validate all form fields. If validation fails,
show error messages below the problematic fields. On success, send the data
and show a confirmation.
```
### Backend and API work
Specify data models, integrations, performance requirements, and security considerations.
```
Connect to the OpenWeatherMap REST API. Authenticate with our API key, fetch
current weather and 5-day forecast, and cache responses for 30 minutes.
```
### Debugging and troubleshooting
Describe what you expected, what actually happened, and any relevant context about when the issue occurs.
```
The contact form fails silently when attachments exceed 5MB. Instead of a blank
error page, show a user-friendly message with the file size limit.
```
### Requesting changes
Be specific about *what* to change, *where* to change it, and *why*.
```
On the product detail page: 1) Move description above specifications,
2) Make images larger with a zoom feature, 3) Add a "Frequently bought
together" section at the bottom.
```
## Plan Mode
Plan Mode is an optional scoping tool for when you want structured requirements gathering before building. It's especially useful when starting a new project from scratch or when you're not sure exactly what you need.
### What Plan Mode does
* **Asks probing questions** to understand your true needs — typically 2–3 structured questions per turn
* **Scopes down to an MVP** before expanding — build something valuable first
* **Pushes back** when you're over-engineering or adding unnecessary complexity
* **Produces a plan document** that Build Mode can follow step by step
### How it works
Plan Mode asks questions to understand your needs using structured multiple-choice for clear, efficient communication.
Based on your answers, Plan Mode identifies the smallest version that delivers real value. It steers away from scope creep.
Before generating the plan, Plan Mode presents a concise summary of scope and technical decisions. You review and approve — or request adjustments.
Plan Mode creates a structured `plan.md` file saved in your project under `./plans/[timestamp_topic-name]/`.
### The plan document
Each plan is append-only — new plans never overwrite existing ones, preserving your decision history. The plan includes:
* **Spec Header** — Name, smallest scope, non-goals
* **Decision Snapshot** — Key technical and product decisions
* **Architecture at a Glance** — Recommended stack and structure
* **Implementation Plan** — Step-by-step development phases
* **Verification & Demo Script** — How to test each phase
* **Deploy** — Deployment strategy
Plan Mode is read-only — it cannot modify files or execute code. Planning stays separate from implementation.
### Switching between modes
Open the **+** menu to the left of the conversation input and choose **Mode: Build** to reveal the mode picker, then select **Plan** or **Build**. You can also just type "Use Plan mode." (or "Switch to Build mode.") — Workshop will flip the toggle for you. The mode persists across sessions and defaults to Build Mode.
A common workflow for new projects:
1. **Plan Mode** — Define requirements, scope the MVP, create a plan
2. **Build Mode** — Implement Phase 1
3. **Plan Mode** — Evaluate results, plan Phase 2
4. **Build Mode** — Continue implementation
For existing projects or clear requirements, skip Plan Mode entirely and work in Build Mode.
## Voice input
Workshop supports voice dictation — speak your prompt instead of typing it. Your speech is transcribed and inserted into the message input.
**How to use it:**
* Click the **microphone icon** in the message input toolbar, or press ⌘⇧D (Mac) / Ctrl⇧D (Windows/Linux)
* Speak your prompt — the button pulses while recording
* Click the microphone again (or press the shortcut again) to stop — Workshop transcribes your audio and inserts the text
* Edit the transcription if needed, then send as usual
Voice input works in both Workshop Cloud and Desktop. Audio is sent to a transcription service for processing — it is not stored after transcription completes.
Voice input is especially useful for describing UI changes, explaining bugs, or dictating long prompts where typing would be slower.
## Files and attachments
You can attach files directly in the message input — but how you attach a file determines what Workshop can do with it.
**Attaching in the input box (drag-and-drop, paste, or clipboard)**
The model can read and understand the file — useful for showing Workshop a design reference, a screenshot of a bug, or a spec to follow. The file is *not* stored anywhere your app can access, so it won't appear in what gets built.
**Uploading a file for your app to use**
If you want Workshop to use a file inside your app — a logo, a background image, a data file — you need to upload it first:
1. Click the **+** button in the message input and choose **Files & Uploads**, or go to Workshop Hub → **Uploads**
2. Type **@** in the message input and select the file by name
3. Tell Workshop how to use it — e.g. *"Use @logo.png as the logo in the header"*
**Context vs content — when it matters:**
* **Context** files help Workshop *understand* your project — reference material, design specs, data schemas, or documentation it should read but not directly include in output. Add files to your project's context through the sidebar Sources panel.
* **Content** files are material Workshop should *use directly* — images to display, data files to process, CSVs to transform. Upload these and reference with @ in your message.
For persistent context across conversations, use the Sources panel in the sidebar or the `.workshop/` directory structure described in [Context and Memory](/core-concepts/context-and-memory).
## Message queuing
You can keep typing while Workshop is responding. Messages you send during an active response are queued and delivered automatically once the current response completes.
This means you don't need to wait for the agent to finish before giving your next instruction — just type and send as you think of things. Queued messages appear above the input so you can review or remove them before they're sent.
### Send now
If you want your queued messages sent immediately without waiting for the current response to finish, click **Send now**. This interrupts the agent's current response and delivers your queued messages as a single combined prompt.
## Managing long conversations
Every conversation has a finite context window — the amount of information Workshop can hold in memory at once. As a conversation grows, responses can slow down and quality can degrade toward the end of the window.
Workshop handles this automatically so you can focus on building.
### Auto-compaction
When your conversation approaches the context window limit, Workshop automatically compacts it. This creates an intelligent summary of the conversation so far and continues seamlessly — no action needed from you.
Here's what happens:
1. Workshop detects that the conversation is nearing its context limit
2. It generates a focused summary that preserves the key decisions, code context, and current task state
3. Your conversation continues in a new child conversation, carrying forward the essential context
4. The original conversation becomes read-only history you can review anytime
Auto-compaction is always active. You don't need to configure or enable anything — long conversations stay fast without manual intervention.
### The `/compact` command
You can also compact manually at any time using the `/compact` command. This is useful when you want to start a fresh context on your own terms — for example, after completing a milestone.
When a conversation nears the context limit, a banner appears suggesting compaction:
You can click **Compact conversation and continue** in the banner, or type `/compact` in the chat input at any time.
```
/compact
```
Summarizes everything and continues in a new conversation.
```
/compact focus on the authentication flow
```
Prioritizes specific context in the summary.
Workshop analyzes the full conversation and distills it into a structured summary — capturing your original request, key decisions, current project state, and what to do next.
Once complete, the conversation is replaced with a clean summary. You can expand it to review what was captured, and continue prompting as usual — the agent retains full understanding of what was built.
### Other useful commands
| Command | Description | Example |
| - | - | - |
| `/context [guidance]` | Update project context from conversation | `/context focus on API patterns` |
| `/summarize [focus]` | Summarize the current conversation | `/summarize action items` |
## Tips for better results
Projects can evolve quickly and it's easy to lose a working state. Ask Workshop to initialize Git and commit at key milestones so you can always go back to a version that worked — or connect a GitHub repository using the native [GitHub integration](/workshop-cloud/github-integration) to back up your code and collaborate with others.
When starting from scratch, Plan Mode helps you define clear requirements and creates a structured plan — even from vague ideas.
Build features one at a time. Get core functionality working before adding complexity. This makes debugging easier and progress more visible.
Set consistent preferences in [Settings](/core-concepts/settings) so you don't repeat the same guidance in every conversation.
Keep your `.workshop/context.md` updated so Workshop always understands your project's current state and conventions. See [Context and Memory](/core-concepts/context-and-memory).
# Workshop Cloud in 5 Minutes
Source: https://docs.workshop.ai/getting-started/cloud-quickstart
Workshop Cloud runs entirely in your browser. No downloads, no local setup — just describe what you want and Workshop builds it.
## Step-by-Step
Go to [app.workshop.ai](https://app.workshop.ai) and create an account.
Click **New Project** and give it a name. You'll be asked to choose a starting template:
* **Dynamic React App** — A fullstack app with a React frontend and a Python backend. Best for anything that runs as a website or web app. Supports one-click publish.
* **Static React App** — A React frontend with no backend. Best when you don't need a server, database, or logins. Supports one-click publish.
* **Dynamic HTML App** — A plain HTML/CSS/JavaScript frontend with a Python backend. Best when your tools don't support React. Supports one-click publish.
* **Streamlit App** — Python-native data apps with charts, tables, and interactivity built in. Supports one-click publish.
* **Anything** — The most flexible option. Custom web apps or ad-hoc tasks using any framework or package that runs in the cloud. Requires manual deployment.
* **Import from GitHub** — Start from an existing repository.
The project creation dialog also includes an **Add-Ons** section where you can enable AI Providers (Anthropic, OpenAI, Gemini) and a Database Provider (Neon). Some templates pre-select defaults — see [Project Templates](/workshop-cloud/templates#add-ons) for details.
Not sure which template to pick? **Dynamic React App** is the best default for websites and web apps.
This is where the magic starts. Describe your idea in plain language:
```
I want to build a dashboard that shows sales trends by region,
with filters for date range and product category.
```
If you want to scope and clarify your project before writing any code, use **Plan Mode** — open the **+** menu next to the chat input and pick **Plan**, or just type "Use Plan mode." Workshop will ask clarifying questions and create a structured plan. When the plan looks right, follow the prompt to switch to **Build Mode**.
If you already know what you want, you can skip straight to **Build Mode** and Workshop will start writing code immediately.
You can bring data and functionality into your project in several ways:
* **File upload** — Drag a CSV, Excel, or JSON file directly into the chat
* **Google Sheets** — Share a link and Workshop will read it
* **Data connectors** — Connect to PostgreSQL, MySQL, BigQuery, Snowflake, Supabase, Google Drive, and more through the [Connectors](/connectors) panel
* **AI Providers** — Add AI features to your app using Workshop's [managed AI connectors](/connectors/managed-ai-connectors) for Anthropic, OpenAI, and Google Gemini. Enable them via Add-Ons in project settings, or bring your own API keys instead.
* **Database Providers** — Add a [managed Neon Postgres database](/connectors/managed-database) with built-in authentication to your project via Add-Ons. Or connect your own database through [Connectors](/connectors).
Tell Workshop what you'd like it to do with the data:
```
Load this CSV and create some initial visualizations so I can
understand the data before we build the dashboard.
```
As Workshop builds, the **preview pane** on the right shows your app updating in real time. Interact with it — click buttons, test filters, hover over charts.
When you want changes, describe them naturally:
```
Change the bar chart to a pie chart and add percentage labels.
The date filter should default to the last 30 days.
```
Workshop updates the code and the preview refreshes automatically.
When your app is ready, click the **Publish** button. Workshop handles hosting and compute — there's nothing to provision or maintain on your end. You get a shareable URL your users can open immediately.
You choose who can access it: make your app public, or limit it to specific people or teams for things you want to keep private. Workshop handles the access control as part of the same flow.
To update a published app, make your changes and click **Update**.
## Tips for Better Results
```
❌ "Make a dashboard"
✅ "Create a dashboard showing monthly revenue trends with a
dropdown to filter by product category and a date range picker"
```
Start with the core functionality, then layer on features:
1. "Load the data and show it in a table"
2. "Add a chart of sales by month"
3. "Add filters for product category and date range"
4. "Style it to match our brand colors"
```
The chart in the preview looks crowded — only show the top 10 products.
The filter dropdown is cut off on mobile. Can you fix the layout?
```
Use Workshop's native [GitHub integration](/workshop-cloud/github-integration) to keep your code backed up and collaborate with others. You can also ask Workshop to commit at logical milestones:
```
Commit our current progress with a descriptive message.
```
## What You Can Build
Workshop Cloud excels at:
* **Dashboards** — Sales, marketing, operations, KPI tracking
* **Data explorers** — Let teams filter and explore datasets interactively
* **Internal tools** — Admin panels, data entry forms, approval workflows
* **Interactive reports** — Reports with drill-down, charts, and export
* **Prototypes** — Test ideas with real data before committing to a full build
## Next Steps
* **Connect your data sources** with [Connectors](/connectors)
* **Add AI features** with [AI Providers](/connectors/managed-ai-connectors)
* **Add a managed database** with [Database Providers](/connectors/managed-database)
* **Publish and share your app** with [Publishing](/workshop-cloud/publishing)
* **Learn how to work with the agent** in [Working with the Agent](/core-concepts/working-with-the-agent)
* **Read prompting tips** in [Working with the Agent](/core-concepts/working-with-the-agent)
* **Join the community** on [Discord](https://discord.gg/ggqJkUN3vx)
# Workshop Cloud vs Desktop
Source: https://docs.workshop.ai/getting-started/cloud-vs-desktop
A detailed comparison of Workshop Cloud and Workshop Desktop to help you choose the right tool for your project.
Workshop comes in two products that share the same AI agent but differ in where your code runs and what you can do with it.
## Feature Comparison
| Feature | Workshop Cloud | Workshop Desktop |
| - | - | - |
| **Runs in** | Browser (any device) | Native app (macOS, Windows, Linux) |
| **Setup required** | None — sign up and go | Download and install |
| **Tech stack** | Dynamic React App, Static React App, Dynamic HTML App, Streamlit App, Anything, Import from GitHub | Any language, any framework |
| **File system** | Cloud (persistent across sessions) | Full local file system access |
| **Live preview** | Built-in preview pane | Run dev servers locally |
| **Publishing** | One-click publish with shareable URL | Deploy anywhere (Vercel, AWS, Docker, etc.) |
| **Local AI models** | Not available | Ollama, llama.cpp, or any compatible server |
| **Local apps** | Not available | Yes |
| **Offline support** | No | Yes (with local models) |
| **MCP servers** | Not available | Built-in directory + custom servers |
| **GitHub integration** | Link and sync projects | Import repos, push/pull sync |
| **Terminal** | Cloud terminal | Local terminal on your machine |
| **Connectors** | Full connector library | Full connector library |
| **AI connectors** | Anthropic, OpenAI, Gemini, Jev | Anthropic, OpenAI, Gemini, Jev |
| **Checkpoints** | Yes | Yes |
| **Thinking mode** | Yes | Yes |
## Workshop Cloud
Workshop Cloud is designed for speed and simplicity. Everything runs in your browser — no local environment to configure, no dependencies to install, no ports to manage.
**How it works:** Workshop writes and executes code in the cloud, and you see results in a live preview pane. When you're done, publish with one click to get a shareable URL — Workshop handles hosting and compute.
**Templates available:**
* **Dynamic React App** — Fullstack app with a React frontend and a Python backend. Best for anything that runs as a website or web app. Supports one-click publish.
* **Static React App** — React frontend with no backend. Best when you don't need a server, database, or logins. Supports one-click publish.
* **Dynamic HTML App** — Plain HTML/CSS/JavaScript frontend with a Python backend. Best when your tools don't support React. Supports one-click publish.
* **Streamlit App** — Python-native data apps with built-in charts, tables, and UI components. Supports one-click publish.
* **Anything** — The most flexible option. Custom web apps or ad-hoc tasks using any framework or package that runs in the cloud. Requires manual deployment.
* **Import from GitHub** — Start from an existing repository.
**Connectors:** Connect to PostgreSQL, MySQL, MongoDB, Supabase, Neon, BigQuery, Snowflake, MSSQL, TiDB, TigerGraph, Tableau, Google Sheets, Google Drive, and AWS S3 — plus AI model connectors for Anthropic, OpenAI, Gemini, and Jev.
## Workshop Desktop
Workshop Desktop is a native application that runs on your local machine. There are no sandbox restrictions — you have full access to your file system, any installed tools, and your local network.
**How it works:** Workshop creates a project directory on your machine and works with your files directly. It runs commands in local terminals, installs packages with your system's package managers, and starts dev servers on your ports. You own everything.
**Key capabilities beyond Cloud:**
* **Any tech stack** — React, Vue, Next.js, Django, Flutter, Swift, Rust, Go — if it runs on your machine, Workshop can build with it.
* **Local apps** — Build native utilities and tools that run directly on your machine. From keyboard tools and transcription to file organization and ad hoc data tasks.
* **Local AI models** — Power the Workshop agent with a local model via Ollama or llama.cpp. Zero API costs, fully private, available offline.
* **MCP servers** — Extend Workshop with Model Context Protocol servers for specialized tools and integrations.
* **No session limits** — Work as long as you need. No timeouts, no restarts.
## Which Should I Choose?
* You want to start building **immediately** without any setup
* You're building **dashboards, data apps, or internal tools** with Python
* You want **one-click publishing** with a shareable URL
* You're working from a **tablet, Chromebook, or shared computer**
* You don't need a specific framework or tech stack
* You want a **managed environment** so you don't have to think about infrastructure
* You need a **specific framework** (React, Next.js, Flutter, etc.)
* You want to work with your **existing codebase** or local files
* You want to build **local apps** — native utilities that run on your machine
* You want to use **local AI models** for privacy, offline use, or zero API costs
* You need **MCP server** integrations for specialized tools
* Your project needs to be **deployed to a specific platform** (AWS, Vercel, Docker, etc.)
**Not sure?** Start with Workshop Cloud. It's the fastest path from idea to working app. If you hit a limitation — need a different framework, want local models, local apps, or need to deploy somewhere specific — switch to Desktop.
## What They Share
**A system-aware agent that works end-to-end**
Workshop's agent understands the full workflow — what to build, which connectors to use, and how to get things ready to ship. It works across Cloud and Desktop, powered by frontier models or local models.
**A real runtime environment**
The agent works inside a real execution environment. In Workshop Cloud, that environment runs in the cloud. In Workshop Desktop, it runs on your machine, with access to local files, runtimes, and your existing tools. The stack isn't preset — Workshop builds across whatever tech fits the project.
**Managed connections to AI and your systems**
Workshop handles model selection, credentials, billing, and rate limits through managed connectors for Anthropic, OpenAI, and Gemini — or bring your own keys. Beyond AI, Workshop connects to databases, warehouses, GitHub, and the tools your workflows depend on.
**Built-in publishing and sharing**
When you're ready to ship, Workshop handles hosting — no separate deployment project needed. Publishing includes access control: share publicly or with specific people, as part of the same flow.
## Moving Between Cloud and Desktop
Your Workshop account works across both products. You can sync projects directly between Cloud and Desktop using [Web ↔ Desktop Sync](/core-concepts/web-desktop-sync) — no GitHub repository required.
1. **Start in Cloud, continue on Desktop** — Prototype quickly in Cloud, then download the project to Desktop when you need more flexibility, and push and pull to keep both sides in sync.
2. **Sync directly** — Push from one environment and pull in the other. Files move through a private intermediary managed by Workshop, no GitHub repository required.
3. **Use GitHub to sync between machines** — Store and back up your project in a private or public GitHub repository, then work on it from any machine. Push it up with [GitHub Integration](/workshop-desktop/github-integration) and bring it into Workshop Cloud or another Desktop machine with [Import from GitHub](/workshop-cloud/github-integration#importing-a-repository-as-a-new-project).
You can also use [GitHub Integration](/workshop-desktop/github-integration) alongside Web ↔ Desktop Sync. GitHub gives you version control and collaboration; Web ↔ Desktop Sync gives you a fast path between environments.
# Workshop Desktop in 5 Minutes
Source: https://docs.workshop.ai/getting-started/desktop-quickstart
Workshop Desktop is a native application for macOS, Windows, and Linux. It gives you full access to your local file system, any programming language or framework, and your existing tools — with no constraints on what you can build or how you ship it.
## Step-by-Step
Go to [workshop.ai](https://workshop.ai) and download the installer for your platform:
* **macOS** — `.dmg` installer (Apple Silicon and Intel)
* **Windows** — `.exe` installer
* **Linux** — `.AppImage` or `.deb` package
Run the installer and launch Workshop Desktop. Sign in with your account or create one.
Something that sets Desktop apart: you can choose to power the Workshop agent with a local model running on your machine via Ollama or llama.cpp — at zero API cost, fully private, and available offline.
Click the model selector in the toolbar to choose between a frontier model (Claude) or a local model you have running. See [Local Models](/workshop-desktop/local-models) for setup instructions.
Click **New Project** and give it a name. You can start from a template or from scratch:
* **Dynamic React App** — Fullstack app with a React frontend and a Python backend. Supports one-click publish.
* **Static React App** — React frontend with no backend. Supports one-click publish.
* **Dynamic HTML App** — Plain HTML/CSS/JavaScript frontend with a Python backend. Best when your tools don't support React. Supports one-click publish.
* **Streamlit App** — Python-native data apps. Supports one-click publish.
* **Anything** — The most flexible option. Desktop apps, working with files on your computer, custom web apps, or ad-hoc tasks in any framework, any language, any stack.
* **Import from GitHub** — Clone an existing repository into a new project.
Workshop creates a project directory on your local file system. You can open this folder in any editor at any time.
This is where the magic starts. Describe your project in plain language:
```
I want to build a React app with a Node.js backend that manages
a task list with due dates, priorities, and categories.
```
If you want to scope and clarify before writing any code, use **Plan Mode** — open the **+** menu next to the chat input and pick **Plan**, or just type "Use Plan mode." Workshop will ask about requirements, design decisions, and technical preferences, then create a structured plan. When it looks right, switch to **Build Mode**.
If you already know what you want, skip straight to **Build Mode** and Workshop will start immediately. You don't need to specify a tech stack upfront — Workshop will recommend one based on your description.
In Build Mode, Workshop writes code, installs packages, creates files, and runs your application — all on your local machine. For web projects, a live preview pane shows your app as it's being built. Watch the progress in the chat and iterate naturally:
```
Add a dark mode toggle to the settings page.
The task list should sort by due date by default.
```
Workshop has full access to your project files and terminal. It can run dev servers, install dependencies, execute scripts, and debug issues directly.
When your project is ready, click **Publish** to deploy it to Workshop's infrastructure — Workshop handles hosting and compute, just like in Cloud. You can make it public or limit access to specific people or teams.
For projects that need to live somewhere else, you have full flexibility:
* Push to **GitHub** and deploy with Vercel, Netlify, Railway, or any CI/CD pipeline
* Build **Docker containers** and deploy to any cloud
* Use platform CLIs (AWS, GCP, Azure, Fly.io) directly
* Run **locally** for personal tools and internal utilities
You can also ask Workshop to help:
```
Help me deploy this to Vercel. Set up the configuration and walk me through it.
```
## Desktop-Only Features
Workshop Desktop is the only place to build local apps — native utilities and tools that run directly on your machine. From keyboard tools and transcription to file organization and ad hoc data tasks, these run immediately without any deployment step.
Workshop runs commands in integrated terminals on your local machine. You see exactly what it's doing and can interact with the terminal yourself at any time.
## Tips for Better Results
Workshop can read files you drag into the conversation — PDFs, images, data files, design mockups. Use this to give it reference material, existing specs, or visual inspiration.
Start with core functionality, verify it works, then add features:
1. "Set up the project with React and Express"
2. "Create the task list with add/edit/delete"
3. "Add categories and filtering"
4. "Add the dark mode toggle"
Ask Workshop to initialize Git and commit at logical milestones. This gives you safety nets to roll back if needed:
```
Initialize git for this project and commit our current progress.
```
You can also connect a GitHub repository using Workshop's native [GitHub integration](/workshop-desktop/github-integration) to keep your code backed up and collaborate with others.
Tell Workshop upfront what system resources your app needs — files, keyboard, microphone, camera. This lets it make the right architecture decisions from the start rather than retrofitting permissions later.
## Next Steps
* **Explore local models** in [Workshop Desktop → Local Models](/workshop-desktop/local-models)
* **Set up MCP servers** in [Workshop Desktop → MCP Servers](/workshop-desktop/mcp-servers)
* **Learn how to work with the agent** in [Working with the Agent](/core-concepts/working-with-the-agent)
* **Read prompting tips** in [Working with the Agent](/core-concepts/working-with-the-agent)
* **Join the community** on [Discord](https://discord.gg/ggqJkUN3vx)
# Choose Your Path
Source: https://docs.workshop.ai/getting-started/index
Workshop comes in two flavors — Cloud and Desktop. Pick the one that fits how you work.
Workshop is agentic coding for builders who don't code. You bring the domain expertise, Workshop brings the execution. There are two ways to get started.
## Workshop Cloud
Build directly in your browser. No downloads, no setup, no configuration.
Workshop Cloud is ideal when you want to go from idea to working app as fast as possible. It runs your code in a managed sandbox environment, gives you a live preview as you build, and lets you publish with one click.
**Best for:** Dashboards, data apps, internal tools, prototypes, and anything you want to share quickly.
Give four AI models the same brief, compare their working apps, and choose one to continue building.
Sign up and build your first app in under 5 minutes.
## Workshop Desktop
Full-stack development power on your local machine. Any language, any framework, your files.
Workshop Desktop gives you complete flexibility. Work with any tech stack, access your local file system, run local AI models, connect MCP servers, and deploy anywhere. It's the full development environment for projects that need more than a sandbox.
**Best for:** Full-stack web apps, mobile apps, local utilities, projects with specific framework requirements, and working with existing codebases.
**Build with local models — free, private, and offline.** Workshop Desktop supports local AI models through Ollama and llama.cpp. No API costs, no data leaving your machine, and no internet connection required.
Download, install, and build your first project in under 5 minutes.
## Not Sure Which to Pick?
**Start with Workshop Cloud.** It's the fastest way to experience Workshop and requires zero setup. You can always move to Desktop later if your project needs it.
If you want a detailed breakdown of features, capabilities, and trade-offs:
Side-by-side feature comparison to help you decide.
## What They Share
**A system-aware agent that works end-to-end**
Workshop's agent understands the full workflow — what to build, which connectors to use, and how to get things ready to ship. It works across Cloud and Desktop, powered by frontier models or local models.
**A real runtime environment**
The agent works inside a real execution environment. In Workshop Cloud, that environment runs in the cloud. In Workshop Desktop, it runs on your machine, with access to local files, runtimes, and your existing tools. The stack isn't preset — Workshop builds across whatever tech fits the project.
**Managed connections to AI and your systems**
Workshop handles model selection, credentials, billing, and rate limits through managed connectors for Anthropic, OpenAI, and Gemini — or bring your own keys. Beyond AI, Workshop connects to databases, warehouses, GitHub, and the tools your workflows depend on.
**Built-in publishing and sharing**
When you're ready to ship, Workshop handles hosting — no separate deployment project needed. Publishing includes access control: share publicly or with specific people, as part of the same flow.
# Import from Bolt
Source: https://docs.workshop.ai/import/from-bolt
Export your Bolt project to GitHub and continue building in Workshop with full-stack tools, local development, and more.
You can bring your Bolt project into Workshop and continue building with capabilities that go beyond Bolt -- custom backends, database connectors, multi-model AI support, and full local development.
**Workshop Desktop is recommended** for the best import experience, but Workshop Cloud works too.
## Step 1: Export Your Bolt Project to GitHub
Bolt lets you connect your project to GitHub:
Navigate to the project you want to export.
In your Bolt project, look for the **GitHub** option in the project menu or settings. Click to connect your GitHub account if you haven't already.
Create a new repository or push to an existing one. Bolt will export your project code to the GitHub repository.
Check your GitHub repository to confirm all project files are there -- source code, `package.json`, configuration files, etc.
Copy the GitHub repository URL -- you'll need it in the next step. It looks like `https://github.com/your-username/your-project`.
## Step 2: Connect GitHub in Workshop
If you haven't already connected your GitHub account to Workshop:
1. Open Workshop Desktop and navigate to **Hub** > **Connectors**
2. Click **Connect** on the GitHub connector
3. Authorize the Workshop GitHub App and select which repositories to grant access to
4. Confirm the connection
See [GitHub Integration (Desktop)](/workshop-desktop/github-integration) for detailed instructions.
1. Open Workshop Cloud and navigate to **Hub** > **Connectors**
2. Click **Connect** on the GitHub connector
3. Authorize the Workshop GitHub App
4. Confirm the connection
See [GitHub Integration (Cloud)](/workshop-cloud/github-integration) for detailed instructions.
## Step 3: Create a Project from Your Bolt Repository
1. Click **New Project** from the Projects page
2. Select **Import from Git**
3. Choose your Bolt repository from the list, or paste the repository URL
4. Workshop clones the repository and creates your project
1. Create a new blank project (select **None** as the template)
2. Open the project settings and navigate to the **GitHub** section
3. Click **Link GitHub Repository** and select your Bolt repository
4. Pull the code from GitHub into your project
## Step 4: Set Up and Run Your Project
Once the project is created, open a conversation and ask the agent to get your project running:
```text Recommended Prompt theme={null}
Please set up and run my Bolt project so I can begin extending it with new features.
Detect the framework and install dependencies, then start the development server.
```
The agent will detect your project's framework (React, Next.js, Vue, or whatever Bolt generated), install dependencies, and start the development server.
## What You Can Do Next
With your Bolt project now in Workshop, you have access to the full platform:
| Capability | Example Prompt |
| - | - |
| **Add AI models** | *"Add a Gemini connector for AI-powered features"* |
| **Connect databases** | *"Set up a Supabase database for persistent storage"* |
| **Build a backend** | *"Create API routes with authentication and data validation"* |
| **Add integrations** | *"Integrate Salesforce to pull customer data into the dashboard"* |
| **Custom deployment** | *"Help me deploy this to Vercel with environment variables configured"* |
## Deployment
Workshop's one-click publish is designed for projects built natively in Workshop. For your imported Bolt project, ask the agent to set up deployment:
```text Netlify Deployment theme={null}
Help me set up deployment for my project to Netlify with automatic deploys from GitHub.
```
```text Vercel Deployment theme={null}
Help me deploy this project to Vercel and configure production environment variables.
```
Download Workshop Desktop to import your Bolt project with the best experience.
# Migrating from Bubble
Source: https://docs.workshop.ai/import/from-bubble
Bubble projects can't be exported as code, but Workshop can help you rebuild with more flexibility, real backends, and full ownership.
Bubble is a no-code platform where projects are built visually and stored in Bubble's proprietary format -- there's no way to export Bubble projects as source code. This means you can't directly import a Bubble project into Workshop the way you can with tools like [Lovable](/import/from-lovable) or [Bolt](/import/from-bolt).
However, Workshop is an excellent platform for **rebuilding** your Bubble application with full code ownership, real backends, and capabilities that Bubble doesn't offer.
## Why Rebuild in Workshop?
If you've hit limitations in Bubble, Workshop gives you:
* **Full code ownership** -- your code lives in your GitHub repository, not locked in a proprietary platform
* **Real backends** -- Python/FastAPI, Node.js, or any backend framework instead of Bubble's workflow engine
* **Database flexibility** -- PostgreSQL, MySQL, MongoDB, Supabase, or any database instead of Bubble's built-in data store
* **AI capabilities** -- built-in support for Claude, GPT, Gemini, and local models
* **Local development** -- work offline with Workshop Desktop and local LLMs
* **Custom deployment** -- deploy anywhere instead of being locked to Bubble's hosting
## How to Approach the Rebuild
Rather than trying to recreate your Bubble app exactly, focus on the core value and user flows. Workshop's AI agent can help you build faster than starting from scratch.
Before starting in Workshop, take screenshots and notes about your Bubble app's key pages, workflows, and data structure. This gives the agent context to work with.
Ask the agent to help design and set up your database schema based on your Bubble app's data types and relationships.
Describe your key pages and user flows to the agent. It will generate a modern React frontend that matches your requirements.
Bubble workflows become proper backend API routes. The agent can build authentication, data processing, and business logic as code.
This is where Workshop shines -- add AI features, complex integrations, custom deployment, and more.
## Getting Started
1. [Download Workshop Desktop](https://workshop.ai/download)
2. Create a new blank project
3. Start a conversation describing your Bubble app and what you want to build
**Example prompt:**
```text theme={null}
I'm rebuilding my Bubble application in Workshop. It's a [describe your app --
e.g., "customer portal with user authentication, a dashboard showing order
history, and an admin panel for managing products"].
Let's start by setting up the project structure with a React frontend and
FastAPI backend. First, help me design the database schema based on these
data types: [list your Bubble data types].
```
1. Go to [app.workshop.ai](https://app.workshop.ai)
2. Create a new project (select the template that best fits your needs)
3. Start a conversation describing your Bubble app
The same approach works in Workshop Cloud, though Workshop Desktop gives you more flexibility for complex applications.
## Tips for a Successful Migration
Don't try to rebuild everything at once. Pick the most important user flow and get it working first. You can iterate from there.
Upload screenshots of your Bubble app when talking to the agent. Visual context helps it understand what you're building.
Your rebuilt app doesn't need to be a 1:1 clone. Take advantage of capabilities Bubble doesn't offer -- like AI features, custom backends, and multi-database support.
Connect GitHub and link your project from the start. This gives you version control and a backup of your work as you build. See [GitHub Integration](/workshop-desktop/github-integration).
Download Workshop Desktop and start building your next-generation app.
# Import from FlutterFlow
Source: https://docs.workshop.ai/import/from-flutterflow
Push your FlutterFlow project to GitHub and continue developing in Workshop with full Flutter/Dart toolchain support.
You can export your FlutterFlow project's code and bring it into Workshop for continued development. This gives you full control over the Flutter/Dart codebase with the ability to add custom packages, native plugins, and backend services.
**Workshop Desktop is strongly recommended** for FlutterFlow imports, as Flutter development benefits from local toolchain access.
## Step 1: Push Your FlutterFlow Project to GitHub
FlutterFlow supports pushing generated code to GitHub:
Navigate to the project you want to export.
Navigate to **Settings** > **Integrations** > **GitHub**. Connect your GitHub account if you haven't already.
Select or create a GitHub repository. Choose the branch to push to (typically `main` or `flutterflow`).
Click **Push to Repository** to export your project's Flutter/Dart code to GitHub. Verify the code appears in your repository.
Copy the GitHub repository URL -- you'll need it in the next step. It looks like `https://github.com/your-username/your-project`.
Once you import your FlutterFlow project into Workshop and start making manual code changes, syncing back to FlutterFlow's visual editor may cause conflicts. Plan to continue development primarily in Workshop going forward.
## Step 2: Connect GitHub in Workshop
If you haven't already connected your GitHub account to Workshop:
1. Open Workshop Desktop and navigate to **Hub** > **Connectors**
2. Click **Connect** on the GitHub connector
3. Authorize the Workshop GitHub App and select which repositories to grant access to
4. Confirm the connection
See [GitHub Integration (Desktop)](/workshop-desktop/github-integration) for detailed instructions.
## Step 3: Create a Project from Your FlutterFlow Repository
1. Click **New Project** from the Projects page
2. Select **Import from Git**
3. Choose your FlutterFlow repository from the list, or paste the repository URL
4. Workshop clones the repository and creates your project
## Step 4: Set Up and Run Your Project
Once the project is created, open a conversation and ask the agent to get your Flutter project running:
```text Recommended Prompt theme={null}
Please set up and run my FlutterFlow project so I can begin extending it. This is a
Flutter/Dart project exported from FlutterFlow. Set up the Flutter development
environment, install dependencies with `flutter pub get`, and start the app in
development mode.
```
The agent will:
* Verify Flutter SDK is available (or help you install it)
* Run `flutter pub get` to install dependencies
* Identify the target platform (web, iOS, Android)
* Start the development server
Flutter development requires the Flutter SDK installed locally. Workshop Desktop's terminal gives you full access to manage the Flutter toolchain. If you need to install Flutter, the agent can guide you through the process.
## What You Can Do Next
With your FlutterFlow project now in Workshop, you can:
| Capability | Example Prompt |
| - | - |
| **Custom widgets** | *"Create a custom animated chart widget that FlutterFlow doesn't support"* |
| **Native plugins** | *"Add camera access and image processing with a native Flutter plugin"* |
| **Backend services** | *"Build a Dart backend with shelf to handle API requests"* |
| **State management** | *"Refactor the state management to use Riverpod for better scalability"* |
| **Custom deployment** | *"Help me set up Firebase Hosting deployment for the web build"* |
## Deployment
For your imported FlutterFlow project, ask the agent to set up deployment appropriate for your target platform:
```text Firebase Hosting (Web) theme={null}
Help me deploy the Flutter web build to Firebase Hosting with automatic deploys.
```
```text App Store / Play Store theme={null}
Help me set up the build configuration for releasing to the App Store and Google Play.
```
Download Workshop Desktop to import your FlutterFlow project.
# Import from Lovable
Source: https://docs.workshop.ai/import/from-lovable
Bring your Lovable project into Workshop via GitHub and continue building with backends, databases, AI connectors, and more.
You can bring your Lovable project into Workshop and continue building with full-stack capabilities that go beyond what Lovable offers -- custom backends, multiple database options, multi-model AI support, and local development.
**Workshop Desktop is recommended** for the best import experience, but Workshop Cloud works too.
## Step 1: Sync Your Lovable Project to GitHub
Lovable has built-in GitHub integration. If you haven't already connected it:
Navigate to the project you want to import.
Go to your project's **Settings** and find the **GitHub** section. Click **Connect to GitHub** and authorize Lovable to access your GitHub account.
Choose to create a new repository or connect to an existing one. Lovable will sync your project code to this repository.
Confirm that your project code appears in the GitHub repository. You should see your React/Vite source files, `package.json`, and other project files.
Copy the GitHub repository URL -- you'll need it in the next step. It looks like `https://github.com/your-username/your-project`.
## Step 2: Connect GitHub in Workshop
If you haven't already connected your GitHub account to Workshop:
1. Open Workshop Desktop and navigate to **Hub** > **Connectors**
2. Click **Connect** on the GitHub connector
3. Authorize the Workshop GitHub App and select which repositories to grant access to
4. Confirm the connection
See [GitHub Integration (Desktop)](/workshop-desktop/github-integration) for detailed instructions.
1. Open Workshop Cloud and navigate to **Hub** > **Connectors**
2. Click **Connect** on the GitHub connector
3. Authorize the Workshop GitHub App
4. Confirm the connection
See [GitHub Integration (Cloud)](/workshop-cloud/github-integration) for detailed instructions.
## Step 3: Create a Project from Your Lovable Repository
1. Click **New Project** from the Projects page
2. Select **Import from Git**
3. Choose your Lovable repository from the list, or paste the repository URL
4. Workshop clones the repository and creates your project
1. Create a new blank project (select **None** as the template)
2. Open the project settings and navigate to the **GitHub** section
3. Click **Link GitHub Repository** and select your Lovable repository
4. Pull the code from GitHub into your project
## Step 4: Set Up and Run Your Project
Once the project is created, open a conversation and ask the agent to get your project running:
```text Recommended Prompt theme={null}
Please set up and run my Lovable project so I can begin extending it with new features.
This is a React/Vite project that was built in Lovable. Install the dependencies and
start the development server.
```
The agent will:
* Detect the project structure (React + Vite + TypeScript + Tailwind is typical for Lovable projects)
* Install dependencies with `npm install`
* Start the development server
* Verify everything is running correctly
## What You Can Do Next
With your Lovable project now in Workshop, you can extend it in ways that weren't possible before:
| Capability | Example Prompt |
| - | - |
| **Add AI models** | *"Add a Gemini connector so users can interact with Google's AI models"* |
| **Connect databases** | *"Set up a PostgreSQL database to store user data instead of local storage"* |
| **Build a backend** | *"Create a Python/FastAPI backend with authentication and API routes"* |
| **Add integrations** | *"Integrate Stripe for payment processing"* |
| **Custom deployment** | *"Help me set up deployment to Netlify with automatic deploys from GitHub"* |
## Deployment
Workshop's one-click publish is designed for projects built natively in Workshop. For your imported Lovable project, ask the agent to set up deployment to a hosting provider that suits your stack:
```text Netlify Deployment theme={null}
Help me set up deployment for my project to Netlify. I want automatic deploys
when I push to the main branch on GitHub.
```
```text Vercel Deployment theme={null}
Help me deploy this React/Vite project to Vercel and configure it for
production builds.
```
Download Workshop Desktop to import your Lovable project with the best experience.
# Import from Replit
Source: https://docs.workshop.ai/import/from-replit
Connect your Replit project to GitHub and import it into Workshop for local development, custom backends, and more.
You can bring your Replit project into Workshop and continue building with full local development, custom backends, database connectors, and multi-model AI support.
**Workshop Desktop is recommended** for the best import experience, but Workshop Cloud works too.
## Step 1: Push Your Replit Project to GitHub
Replit has built-in Git and GitHub integration:
Navigate to the Repl you want to export.
Click the **Git** icon in the left sidebar (or go to **Tools** > **Git**) to open the version control panel.
Click **Connect to GitHub**. If prompted, authorize Replit to access your GitHub account. Create a new repository or connect to an existing one.
Commit any uncommitted changes and push to GitHub. Verify that all your project files appear in the GitHub repository.
Copy the GitHub repository URL -- you'll need it in the next step. It looks like `https://github.com/your-username/your-project`.
Replit projects may include Replit-specific configuration files (`.replit`, `replit.nix`). These won't cause problems in Workshop -- the agent will focus on the standard project files and package manager configuration.
## Step 2: Connect GitHub in Workshop
If you haven't already connected your GitHub account to Workshop:
1. Open Workshop Desktop and navigate to **Hub** > **Connectors**
2. Click **Connect** on the GitHub connector
3. Authorize the Workshop GitHub App and select which repositories to grant access to
4. Confirm the connection
See [GitHub Integration (Desktop)](/workshop-desktop/github-integration) for detailed instructions.
1. Open Workshop Cloud and navigate to **Hub** > **Connectors**
2. Click **Connect** on the GitHub connector
3. Authorize the Workshop GitHub App
4. Confirm the connection
See [GitHub Integration (Cloud)](/workshop-cloud/github-integration) for detailed instructions.
## Step 3: Create a Project from Your Replit Repository
1. Click **New Project** from the Projects page
2. Select **Import from Git**
3. Choose your Replit repository from the list, or paste the repository URL
4. Workshop clones the repository and creates your project
1. Create a new blank project (select **None** as the template)
2. Open the project settings and navigate to the **GitHub** section
3. Click **Link GitHub Repository** and select your Replit repository
4. Pull the code from GitHub into your project
## Step 4: Set Up and Run Your Project
Once the project is created, open a conversation and ask the agent to get your project running:
```text Recommended Prompt theme={null}
Please set up and run my Replit project so I can begin extending it with new features.
This project was built in Replit -- detect the language and framework, install
dependencies, and start the development server. You can ignore any .replit or
replit.nix configuration files.
```
The agent will:
* Detect the language and framework (Node.js, Python, or whatever your Repl uses)
* Install dependencies using the appropriate package manager
* Start the development server
* Ignore Replit-specific config files that aren't needed locally
## What You Can Do Next
With your Replit project now in Workshop, you can extend it beyond Replit's capabilities:
| Capability | Example Prompt |
| - | - |
| **Add AI models** | *"Add Claude and Gemini support for multi-model AI features"* |
| **Connect databases** | *"Set up a PostgreSQL database to replace the SQLite file"* |
| **Build a backend** | *"Add a FastAPI backend with proper authentication"* |
| **Local models** | *"Configure a local LLM so I can develop with AI features offline"* |
| **Custom deployment** | *"Help me deploy this to Railway with a PostgreSQL database"* |
## Deployment
Workshop's one-click publish is designed for projects built natively in Workshop. For your imported Replit project, ask the agent to set up deployment:
```text Railway Deployment theme={null}
Help me set up deployment to Railway for this project. Include a PostgreSQL
database and configure environment variables.
```
```text Netlify/Vercel Deployment theme={null}
Help me deploy the frontend to Netlify and the backend to Railway.
```
Download Workshop Desktop to import your Replit project with the best experience.
# Import & Migrate
Source: https://docs.workshop.ai/import/index
Bring your existing projects from other AI builders into Workshop and keep building with full-stack capabilities.
Already have a project in another tool? You can bring it into Workshop and continue building -- adding backends, databases, AI connectors, and more.
Workshop supports importing projects from any tool that can export code to GitHub. Choose your source tool below to get started.
## Import Guides
Bring your Lovable project into Workshop via GitHub sync. Keep your React frontend and add backends, databases, and new AI models.
Export your Bolt project to GitHub and continue building in Workshop with full-stack tools and local development.
Connect your Replit project to GitHub and import it into Workshop for local development, custom backends, and more.
Push your FlutterFlow project to GitHub and continue developing in Workshop with full Flutter/Dart toolchain support.
Bubble projects can't be exported as code, but Workshop can help you rebuild with more flexibility and full ownership.
## How It Works
The import process follows the same pattern for all tools:
Use your current tool's GitHub integration to sync or export your project code to a GitHub repository.
Link your GitHub account in Workshop via the Hub connectors panel.
Import the GitHub repository as a new Workshop project.
Workshop's AI agent will configure the development environment, install dependencies, and get your project running.
## Workshop Desktop vs Workshop Cloud
Both Workshop Desktop and Workshop Cloud support importing projects from GitHub, but **Workshop Desktop is recommended** for imported projects because it gives you:
* **Full local development environment** with terminal access and file system control
* **Local model support** for privacy-sensitive work
* **More flexibility** for custom build tools, runtimes, and deployment targets
* **Direct "Import from Git"** in the new project flow
Workshop Cloud works too -- you create a project, link the GitHub repository, and pull the code. See [Cloud vs Desktop](/getting-started/cloud-vs-desktop) for a detailed comparison.
## After Importing
Once your project is running in Workshop, you can ask the agent to extend it in ways your original tool may not support:
* Add AI capabilities with **Claude, GPT, or Gemini** connectors
* Connect to **PostgreSQL, MySQL, MongoDB**, or other databases
* Build a **Python/FastAPI backend** alongside your frontend
* Integrate with **Salesforce, Stripe, Twilio**, or other APIs
* Set up deployment to **Netlify, Vercel, Railway**, or your own infrastructure
Workshop's one-click publish is designed for projects built within Workshop. For imported projects, ask the agent to help you set up deployment to your preferred hosting provider (Netlify, Vercel, etc.).
# Welcome to Workshop
Source: https://docs.workshop.ai/index
Agentic coding for builders who don't code. Turn your expertise into working software.
AI has crossed a threshold — for many teams, it's writing a meaningful share of production code.
But most people's experience still looks the same: you get a draft, and then the real work begins. The wiring, the environment, the connections, the guardrails. How do you actually ship this?
The bottleneck isn't the models anymore. It's the system around them.
Workshop is that system. Build, connect, and ship — in the cloud from your browser, or on your desktop with full local access.
## What You Can Build
Describe the site you want and watch it come to life. Responsive, accessible, and ready to deploy.
Build real AI-powered applications with Anthropic, OpenAI, and Google models built in.
Connect your databases, build interactive dashboards with natural language, and share with confidence.
Connect databases and APIs, describe the tool you need, and deploy with built-in authentication.
Build cross-platform mobile apps with Expo and React Native using Workshop Desktop.
Build native utilities and apps that run directly on your machine — from niche tools to ad hoc tasks. Workshop Desktop only.
## Two Ways to Build
**Workshop Cloud** — Get started instantly in your browser. No downloads, no setup.
* Build web apps, dashboards, data apps, and internal tools
* One-click publish with built-in hosting — Workshop handles the compute
* Connect to databases, warehouses, APIs, and AI models
* Share publicly or privately with specific people or teams
**Workshop Desktop** — Full power on your local machine. Any language, any framework.
* Build anything: web apps, mobile apps, local utilities, and more
* Direct access to your local file system and existing tools
* Power the agent with local AI models — free, private, and offline
* Deploy to any platform
Not sure which to pick? See [Workshop Cloud vs Desktop](/getting-started/cloud-vs-desktop).
## Get Started
Build your first app in the browser in under 5 minutes.
Install Workshop Desktop and build your first project.
Learn how to get the best results from Workshop.
Patterns and strategies from thousands of successful projects.
**Join the community:** [Discord](https://discord.gg/ggqJkUN3vx)
**Need help?** Reach out to us at [help@workshop.ai](mailto:help@workshop.ai)
# Billing FAQs
Source: https://docs.workshop.ai/pricing/billing-faqs
Frequently asked questions about Workshop pricing, credits, and billing.
## What is a credit? How much is it worth?
A credit is an approximation of a typical turn in conversation with Workshop, which includes both your message and Workshop's response. The actual credit cost of each turn can vary above or below 1 credit, depending on the turn complexity and length.
Simple queries like "what's the time?" cost only a fraction of a credit. Complex or long messages may cost multiple credits.
You can track your credit usage in the conversation screens and on the billing page in the app.
Credits used per turn increase as the conversation progresses because each new message builds on the previous ones. While Workshop employs techniques to minimize this effect, identical messages will generally cost more credits later in a conversation than at the start. We recommend starting a new conversation for each new topic or build you explore.
## What are some strategies to manage my credit consumption?
Workshop has multiple features behind the scenes to minimize credit usage. On top of
them, the changes that make the biggest difference are:
* Start a fresh conversation for each new task, so the agent isn't re-reading a long history on every turn
* Choose [ARC](/core-concepts/settings#arc) in the model selector, so routine work doesn't run on the most expensive model
* Avoid switching to a premium model part-way through a long conversation — start a new one on that model instead
* Use Plan Mode to scope larger jobs before the agent starts editing files
[Using Credits Effectively](/best-practices/using-credits-effectively) covers each of
these in full, along with sub-agents and what to do when the agent goes in circles.
## What information do you store?
Your code is never stored anywhere other than your machine.
If you enable "Privacy Mode", your conversations are also never stored anywhere other than your machine. Otherwise, we may collect usage and telemetry data (including prompts, code snippets, or app activities) to help improve Workshop.
## Are there any usage limits? What happens if I reach them?
The Discover plan (free) has a limited amount of credits per month (250 AI Credits).
The Build, Scale, and Max plans do not have a hard monthly limit. The monthly subscription includes credits (1,500 for Build, 5,000 for Scale, 25,000 for Max), and you can purchase Credit Packs as needed.
## What are Credit Packs?
If you run out of the credits included in any paid plan (Build, Scale, or Max), you can buy Credit Packs of different volumes. Larger packs offer bonus credits and longer rollover periods.
| Price | Build Plan Credits | Scale Plan Credits | Rollover |
| - | - | - | - |
| \$25 | 2,500 | 2,750 (250 bonus) | 3 months |
| \$100 | 11,000 (1,000 bonus) | 12,000 (2,000 bonus) | 6 months |
| \$500 | 60,000 (10,000 bonus) | 65,000 (15,000 bonus) | 6 months |
## Do credits roll over?
Discover plan credits do not roll over from month to month.
Build, Scale, and Max plan credits roll over with the following structure:
* Credits included in your subscription expire 3 months after they are acquired
* Credits purchased from a Pack expire 3 or 6 months after the subscription renewal following the Pack purchase date, depending on pack size
You can see more details on your credit usage and expiration dates on the Usage page in Workshop.
**Example:** If your subscription renews on June 10th and you buy a pack for 5,000 credits on June 25:
* The 1,500 credits included in the subscription plan would expire on September 10th (3 months)
* The 5,000 credits from the Pack expire October 10th (3 months after the July 10th renewal)
## Can I upgrade or downgrade at any time?
You can upgrade from Discover to Build, Scale, or Max whenever you need more credits or features.
If you downgrade from a paid plan (Build, Scale, or Max) to Discover, the change takes effect at the start of your next billing cycle.
Any unused credits will expire when your subscription downgrades. We recommend using them before this date.
## What happens with my credits if I downgrade my plan?
When you cancel a subscription, you continue to have access to your credits and plan features until the end of your billing period.
Any unused credits expire when your subscription downgrades. If you are not sure you will be able to use your remaining credits in that time, we recommend waiting to cancel.
## Can I downgrade from Scale directly to Build?
Currently, Scale plans cannot be downgraded directly to Build plans. You have two options:
* **Two-step downgrade**: Downgrade from Scale to Discover, then upgrade from Discover to Build
* **Contact support**: Reach out to [help@workshop.ai](mailto:help@workshop.ai) and we will handle the direct Scale-to-Build downgrade manually
## Unsupported countries for purchases
We cannot accept payments from customers in the following countries: Central African Republic, Cuba, Democratic People's Republic of Korea, Democratic Republic of the Congo, Eritrea, Guinea-Bissau, Iran, Iraq, Lebanon, Libya, Mali, North Korea, Russian Federation, Somalia, South Sudan, Sudan, Syrian Arab Republic, and Yemen.
## Need More Help?
* **Email**: [help@workshop.ai](mailto:help@workshop.ai) for billing-specific issues
* **Community**: [Discord](https://discord.gg/ggqJkUN3vx) for general questions about usage
* **Account dashboard**: Self-service options for common tasks
# Plans and Credits
Source: https://docs.workshop.ai/pricing/plans
Understanding Workshop's pricing tiers, credit system, and billing.
Workshop uses a credit-based system that provides transparent pricing for AI development work. You only pay for actual AI and compute usage — when you are building actively, you use credits for powerful AI assistance. When you are not building, you are not charged.
## Plans
| | Discover | Build | Scale | Max |
| - | - | - | - | - |
| **Price** | Free | \$20/month | \$50/month | \$200/month |
| **AI Credits** | 250/month | 1,500/month | 5,000/month | 25,000/month |
| **Cloud Credits** | 0 (publish with rate limits) | 75/month | 250/month | 1,250/month |
| **File Storage** | — | 1 GB | 10 GB | 10 GB |
| **Private Apps** | — | 1 | Unlimited | Unlimited |
| **Viewers per App** | — | 5 | Unlimited | Unlimited |
| **Custom Domains** | — | Yes | Yes | Yes |
| **File Upload Size** | Standard | Standard | No limit | No limit |
| **Remove Workshop Badge** | — | Yes | Yes | Yes |
| **Credit Packs** | — | Available | 10% discount | Max discount |
| **Data Training Opt-out** | — | — | Yes | Yes |
| **Data Storage** | 10 days | Included | Included | Included |
All plans include Workshop Cloud, Workshop Desktop, and the full ecosystem of connectors (Anthropic Claude, OpenAI, Google Gemini, BigQuery, Snowflake, Supabase, PostgreSQL, MongoDB, MySQL, GitHub, Google Sheets, AWS S3).
No credit card required. Start building with 250 AI Credits on the Discover plan.
## Understanding Credits
### AI Credits
AI Credits are Workshop's unit of AI computation. Each interaction with the AI consumes credits based on:
* **Complexity of the request** — Simple questions use fewer credits than complex code generation
* **Context size** — Longer conversations require more context processing, increasing cost per message
* **Feature utilization** — Advanced features like Thinking Mode may use additional credits
### Real-Time Usage Tracking
Workshop provides transparent usage tracking:
* **Usage indicator** in the bottom-right corner shows credits used and percentage of the LLM context window
* **Credit balance** is always visible in your account dashboard and updates after each interaction
* **Usage page** shows detailed credit consumption history and expiration dates
### Cloud Credits
Cloud Credits measure your usage of Workshop's cloud compute features, such as running deployed applications. This is separate from AI Credits, which are consumed during conversations with the AI agent.
| Plan | Monthly Cloud Credits |
| - | - |
| Discover | 0 (publish with rate limits) |
| Build | 75 |
| Scale | 250 |
| Max | 1,250 |
Cloud Credits reset each billing period and do not roll over. For additional cloud compute capacity, contact [help@workshop.ai](mailto:help@workshop.ai).
## Credit Packs
If you run out of credits included in a paid plan (Build, Scale, or Max), you can purchase Credit Packs:
| Price | Build Plan Credits | Scale Plan Credits | Rollover |
| - | - | - | - |
| \$25 | 2,500 | 2,750 (250 bonus) | 3 months |
| \$100 | 11,000 (1,000 bonus) | 12,000 (2,000 bonus) | 6 months |
| \$500 | 60,000 (10,000 bonus) | 65,000 (15,000 bonus) | 6 months |
**Key features:**
* Available immediately upon purchase
* Stack with monthly plan allocations
* Volume discounts on larger packs (bonus credits start at \$100)
* Scale plan subscribers get 10% more credits; Max plan subscribers get the largest discount
### Credit Rollover
* **Discover plan** credits do not roll over
* **Build, Scale, and Max plan** subscription credits expire 3 months after acquisition
* **Credit Pack** credits expire 3 or 6 months after the subscription renewal following the pack purchase date, depending on pack size
View detailed credit usage and expiration dates on the Usage page: profile picture → Usage and billing → Usage.
## Usage Optimization
Every turn is charged against the whole conversation history, so the same request costs
more late in a long conversation than it did at the start. The changes that follow from
that — starting a fresh conversation per task, choosing the right model, and taking care
when switching models mid-conversation — are covered in
[Using Credits Effectively](/best-practices/using-credits-effectively).
The quickest win is choosing [ARC](/core-concepts/settings#arc) in the model selector,
so routine work doesn't run on the most expensive model.
## Enterprise
For large organizations that need custom integrations, dedicated support, or bring-your-own-key arrangements, contact our sales team.
Enterprise plans include:
* Forward-deployed engineer
* Bring your own API key
* Custom integrations
* Custom SLAs
* Security reviews
* Priority support
## Support
* **Email**: [help@workshop.ai](mailto:help@workshop.ai) for billing-specific issues
* **Community**: [Discord](https://discord.gg/ggqJkUN3vx) for general questions about usage
* **Account dashboard**: Self-service options for plan changes and billing history
# Unified GTM Analytics
Source: https://docs.workshop.ai/solutions/gtm-analytics
Unify sales, marketing, and product data in one place. Get answers and build dashboards in seconds — no SQL required.
## The Problem: Scattered Data, Slow Answers
Go-to-market teams depend on data from dozens of tools — CRM, marketing automation, product analytics, billing, ad platforms — yet getting a unified view requires BI tickets, SQL expertise, and weeks of waiting. Metrics conflict across spreadsheets, tribal knowledge replaces governed definitions, and operators spend more time requesting data than acting on it.
## How Workshop Solves It
Workshop gives marketing ops, revenue ops, and growth teams a self-serve analytics layer on top of their existing data warehouse and semantic layer. Connect your data, ask questions in natural language, and get trusted answers — no SQL required.
Plug in Snowflake, BigQuery, Postgres, or Redshift. Workshop reads your schema and dbt documentation automatically, so it understands your data from day one.
Workshop natively understands dbt metrics, dimensions, and relationships. Queries are governed from the start — everyone works from the same source of truth.
Type what you want to know. Workshop generates the SQL, runs it on your warehouse, and returns charts, tables, and explanations.
```
Show pipeline coverage ratio by quarter against quota targets,
broken down by sales team and deal stage.
```
Turn answers into live dashboards. Share with your team via built-in auth — everyone sees the same governed numbers.
## Why Workshop for GTM Analytics
Ask questions in natural language and get numbers, charts, and reasoning back. No BI tickets, no waiting.
Workshop reads your dbt models, metrics, and documentation natively. Queries run on your infrastructure and respect your metric definitions — governed by default.
Analytics engineers define the source of truth. Everyone else gets self-serve access to the same governed metrics — no conflicting spreadsheets, no tribal knowledge.
## Analytics Across Every Function
Multi-touch attribution, channel ROI, and funnel analysis across all your marketing platforms. Ask Workshop to compare spend, CPA, and ROAS across Google Ads, Meta, and LinkedIn with interactive date filtering.
Pipeline coverage, forecast accuracy, and deal velocity metrics your revenue team can trust. Build a unified view from first touch to closed-won.
Retention cohorts, feature adoption, and engagement metrics connected to your product database. Compare behavior between free and paid user segments.
Board-ready dashboards with KPIs across marketing, sales, product, and finance — always up to date and always governed.
End-to-end conversion funnels from first touch to revenue, with drop-off analysis at every stage.
MRR, churn, expansion, and cohort LTV analysis powered by your billing and CRM data.
## Example Prompts
These are the kinds of questions teams ask Workshop every day:
```
Show me pipeline coverage by quarter vs quota
```
```
Which marketing channels have the best LTV:CAC ratio?
```
```
Build a multi-touch attribution report showing how marketing
channels contribute to pipeline and closed revenue.
```
```
Create a cohort retention analysis showing weekly retention
rates by acquisition channel with trend comparison.
```
```
What drove the revenue dip last month?
```
## Who This Is For
* **Marketing Ops** — channel attribution, campaign performance, funnel conversion
* **Revenue Ops** — pipeline forecasting, quota attainment, deal velocity
* **Growth Teams** — cohort analysis, retention metrics, feature adoption
* **Data Teams** — governed self-serve analytics that reduce BI ticket volume
* **Executives** — real-time dashboards with metrics they can trust
## dbt Integration
Workshop reads your dbt project natively:
* **Models and metrics** are understood as first-class objects
* **Documentation and descriptions** provide context for natural language queries
* **Tests and constraints** ensure data quality at query time
* **Relationships** between models inform how Workshop joins data
If your analytics engineering team already maintains a dbt project, Workshop becomes the self-serve layer on top — no additional modeling required.
### Compile your dbt project into an agent skill
For teams that want the deepest integration, [dbt-skillz](https://github.com/atlasfutures/dbt-skillz) is an open-source compiler that converts your entire dbt project into a structured skill the agent can consume. This goes beyond schema reading — it includes metric definitions, test constraints, column documentation, and the full lineage graph.
```bash theme={null}
pip install dbt-skillz
dbt-skillz compile --project-dir ./analytics --output ./skills/data
```
Import the compiled skill into Workshop from a GitHub repo. See [Skills](/core-concepts/skills) for setup instructions.
Start building with Workshop for free. Connect your warehouse and ask your first question in minutes.
Learn how the dbt-skillz compiler powers a full lifecycle for keeping dashboards accurate — from grounded creation through automated review and maintenance.
Our white-glove team sets up your analytics stack, builds the first dashboards, and trains your team to self-serve.
# Prototyping for Product Managers
Source: https://docs.workshop.ai/solutions/prototyping
Go from idea to clickable prototype in minutes. Real code, not mockups — instantly shareable with your team.
## Bring Ideas to Life Before Writing a PRD
Product managers, designers, and founders spend weeks on static mockups and written specifications. By the time a prototype reaches engineering, assumptions have already calcified. Workshop flips this: describe what you want, and get a working, clickable prototype you can share and iterate on — in minutes, not sprints.
Every prototype Workshop builds is real code (HTML, CSS, JavaScript), not a static image. Stakeholders can click through it, test interactions, and provide meaningful feedback on something tangible.
## Two Ways to Prototype
### Workshop Cloud: Rapid UI Prototyping
Best for starting from scratch or exploring new concepts. Describe your idea in plain language and Workshop builds a working prototype you can share via URL.
```
Build a dashboard prototype for our investor meeting with:
- Revenue chart showing monthly MRR growth
- Customer acquisition funnel with conversion rates
- Churn analysis with cohort breakdown
- KPI cards for ARR, NRR, and active users
```
Workshop generates a complete, interactive prototype and gives you a shareable link. Your investors, co-founders, or leadership team can interact with it immediately.
### Workshop Desktop: Prototype Within Your Codebase
Best for product managers who want to prototype changes to an existing product. Use the GitHub connector to pull in your codebase, have Workshop set up the dev environment, then describe the changes you want as a clickable prototype with mocked data.
Use the GitHub connector to pull in your existing repository. Workshop reads the project structure, dependencies, and patterns automatically.
Ask Workshop to install dependencies and start the development server. It handles the technical setup so you can focus on the product.
```
Set up this project and start the dev server so I can preview changes.
```
Tell Workshop what you want to prototype. It navigates the codebase, understands the existing patterns, and builds the prototype using your project's real components.
```
I need to prototype the different user flows based on subscription tiers.
Create a demo mode with a plan selector that toggles between Pro and Max
tiers. Show how features and limits differ for each tier.
```
Review the working prototype in your browser, request changes, and share the result with stakeholders for feedback.
## Why Prototype with Workshop
Describe a change and see it live in seconds. No waiting for design handoffs or dev cycles.
Every prototype is a working application built with real HTML, CSS, and JavaScript — not a static image.
Get a live URL you can share with stakeholders, investors, or your team. Collect feedback on something real.
## What Teams Prototype with Workshop
Full-fidelity screen designs with real components, responsive layouts, and interactive states. Go beyond static wireframes with prototypes that feel like the final product.
Working product demos for investor meetings — show something real, not slides. Investors can click through your product concept and experience the vision firsthand.
Quickly explore implementation approaches with working code before committing to a sprint. Validate technical feasibility alongside product desirability.
Try multiple visual directions in minutes. Compare layouts, color schemes, and component patterns side-by-side.
Prototype mobile onboarding, checkout, and navigation flows that feel native. Test the experience on a real device before committing to development.
Build clickable prototypes for user research sessions with real interactions and sample data. Get higher-quality feedback than static mockups allow.
## Example Prompts
```
Generate 3 alternative onboarding flows (low friction, progressive
profiling, enterprise-ready) with clickable prototypes.
```
```
Prototype a "query builder" for non-technical users: filter chips,
saved views, and export. Create and connect to a mocked dataset.
```
```
Create a landing page mockup for the new product launch with hero
section, feature grid, pricing toggle, and email signup.
```
```
Build an interactive wireframe for the mobile onboarding flow
with 4 screens: welcome, permissions, personalization, home.
```
## Who This Is For
* **Product Managers** — validate feature ideas before they reach the engineering backlog
* **Designers** — explore visual directions and test interactions with real code
* **Founders** — turn a napkin sketch into a clickable demo for investor meetings
* **Solutions Engineers** — build customer-specific demos that show exactly how your product solves their problem
* **User Researchers** — create realistic prototypes for usability studies
## From Prototype to Production
The best part: Workshop prototypes are not throwaway work. Because they are built with real code, they can serve as a foundation for production development. When a prototype validates an idea, your engineering team can pick up where Workshop left off — or continue building with Workshop to take it all the way to production.
Start building with Workshop for free. Go from idea to clickable prototype in minutes.
# Trusted Dashboards
Source: https://docs.workshop.ai/solutions/trusted-dashboards
Build dashboards grounded in your semantic layer. The dbt-skillz compiler turns your dbt project into agent context — so dashboards are accurate from day one and stay accurate as your data evolves.
## The Problem: Dashboards That Drift
AI coding agents can build stunning dashboards in minutes. But without access to your semantic layer, they guess at metric definitions, aggregation grain, and join logic. The result looks right, runs fine, and is quietly wrong.
As your dbt models evolve — new product lines, updated attribution models, renamed columns — agent-built dashboards don't update themselves. They were correct at the time of creation and begin drifting immediately.
## The Solution: dbt-skillz + Workshop
[dbt-skillz](https://github.com/atlasfutures/dbt-skillz) is an open-source compiler (Apache 2.0) that converts your dbt project into a structured skill — a context document any coding agent can consume. Workshop is the runtime that ties it all together.
```mermaid theme={null}
flowchart LR
A[dbt project] --> B[dbt-skillz compile]
B --> C[Agent skill]
C --> D[Workshop agent]
D --> E[Grounded dashboard]
```
## Getting Started
Install from PyPI:
```bash theme={null}
pip install dbt-skillz
```
Point the compiler at your dbt project:
```bash theme={null}
dbt-skillz compile --project-dir ./analytics --output ./skills/data
```
This generates structured skill files:
* `SKILL.md` — entry point the agent reads first
* `ref/sources.md` — source definitions
* `ref/staging.md` — staging models
* `ref/marts.md` — mart models with metric definitions
* `ref/lineage.md` — full DAG
Push the compiled skill to a GitHub repository (private or public). In Workshop, import the skill from the repo. The agent now has full semantic context for your data.
See [Skills](/core-concepts/skills) for detailed import instructions.
Start a conversation in Workshop and reference your data. The agent uses the imported skill to write correct queries, use governed metric definitions, and respect the grain of each table.
## The Trusted Dashboards Lifecycle
The agent builds with full semantic context from your dbt project — correct metric definitions, proper grain, accurate join logic — from the first line of code.
When a new dashboard is pushed to GitHub, a review agent audits it against the data skill — verifying metric definitions, aggregation grain, join logic, and column references before it ships.
When a dbt model changes, the system identifies every dashboard that depends on the affected models. You see the blast radius before the change merges.
When dbt changes are merged, an agent reviews every affected dashboard, generates pull requests with updates, and notifies the owners. Metrics stay current without manual audits.
```mermaid theme={null}
flowchart TD
A[dbt changes merged] --> B[Dashboard registry]
B --> C[App A]
B --> D[App B]
B --> E[App C]
C --> F[Update PRs opened]
D --> F
E --> F
F --> G[Owners notified]
```
## CI/CD Integration
Use dbt-skillz in your CI pipeline to review changes to your dbt project automatically:
```yaml theme={null}
# .github/workflows/dbt-review.yml
on:
pull_request:
paths: ['analytics/**']
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: pip install dbt-skillz
- run: dbt-skillz compile --project-dir ./analytics
- run: |
dbt-skillz review --skill ./skills/data --diff $GITHUB_EVENT_PATH
```
The review agent uses the compiled skill as context to understand the full impact of changes and flag potential issues.
## Not Just dbt
The skill compiler pattern generalizes beyond dbt. Any system that defines "what this data means" — Looker semantic models, Cube.js schemas, well-documented SQL views — can be compiled into an agent skill. dbt is where we started because it's the most structured semantic layer in the ecosystem.
Workshop also supports [SQLMesh and Dagster](/connectors/data-warehouses) natively.
## Beyond Dashboards
With the compiled skill as context, product managers can describe events they want to track, have the agent instrument them in the codebase, update dbt models, and submit pull requests to the analytics team. The skill bridges domain expertise and implementation.
## Resources
Open-source compiler. Apache 2.0. Install with pip.
Project site with examples and documentation.
Step-by-step guide to building dashboards in Workshop.
How to import and manage skills in Workshop.
The Dashboard Trust Problem — the full story behind trusted dashboards.
Explore dashboard capabilities on the Workshop marketing site.
***
We work directly with teams to implement the full trusted dashboards lifecycle — from dbt skill compilation through automated review and maintenance. White-glove setup, training, and ongoing support.
# Debugging Strategies
Source: https://docs.workshop.ai/troubleshooting/debugging-strategies
Systematic approaches to debugging with Workshop when things go wrong.
When something is not working as expected, a systematic approach to debugging saves time and frustration. Here are three proven strategies, along with practical guidance on when to investigate yourself versus when to ask Workshop for help.
## Three Debugging Approaches
### 1. The Scientific Method
A structured, hypothesis-driven approach:
1. **Observe** — What exactly is happening? What did you expect to happen?
2. **Hypothesize** — What might be causing the issue?
3. **Test** — Make a small change to test your hypothesis
4. **Analyze** — Did the change fix it? If not, what did you learn?
5. **Repeat** — Form a new hypothesis based on what you learned
```
When I click the "Save" button, nothing happens. I expected the form
data to be saved and a confirmation message to appear. Let's check
if the button click event is being triggered at all.
```
### 2. Divide and Conquer
Isolate the problem by narrowing the search space:
1. **Isolate components** — Test parts of the system separately
2. **Binary search** — If you have a large codebase, test the middle to narrow down where the problem is
3. **Eliminate variables** — Simplify until you find the minimal case that reproduces the issue
```
Let's create a simple test page with just the form component to see
if it works in isolation. If it does, we know the issue is in how
it interacts with other components.
```
### 3. Logging and Monitoring
Add visibility into what the code is doing:
1. **Strategic console logs** — Add logs at key points in the code flow
2. **State tracking** — Log the state of important variables
3. **Input/output validation** — Verify data at entry and exit points
```
Can we add logs to track the form data at three points: when the
user inputs it, when the save button is clicked, and when we try
to send it to the server?
```
## When to Ask Workshop vs. Investigate Yourself
### Ask Workshop When:
* You have a clear error message and want an explanation
* The problem involves code Workshop generated and it has full context
* You need to search the codebase for related patterns
* You want help creating a minimal reproduction
* You need to try multiple potential fixes quickly
### Investigate Yourself When:
* The issue is environmental (wrong Node version, missing system dependency)
* You need to check browser DevTools, network requests, or server logs
* The issue involves external services you need to verify manually (API keys, database access)
* You want to understand the problem deeply before asking for a fix
## Common Debugging Scenarios
### Workshop Misunderstands Your Requirements
**Symptoms**: Generated code does not match what you described, features are missing, or the structure does not align with your vision.
**Strategies**:
* Be more specific with concrete examples
* Break down complex requests into smaller pieces
* Use the correction pattern: acknowledge what works, identify what needs to change, explain the desired outcome
```
The layout of the dashboard looks good, but the chart isn't showing
the data correctly. The x-axis should show months, not days, and we
need to display the cumulative total rather than daily values.
```
### Technical Errors in Generated Code
**Symptoms**: Error messages when running the application, features that do not work, console warnings.
**Strategies**:
* Copy and paste the exact error message to Workshop
* Ask for both an explanation and a step-by-step fix
* Use version control to revert if changes make things worse
* Test small pieces in isolation
```
When I click the submit button, I get this error in the console:
TypeError: Cannot read property 'value' of undefined
```
### Performance Issues
**Symptoms**: Application runs slowly, high memory usage, long loading times.
**Strategies**:
* Ask Workshop to identify the bottleneck
* Request specific optimizations for your use case
* Consider whether architecture changes are needed
```
The dashboard takes over 5 seconds to load. Can you help me identify
what's causing the delay?
```
### Integration Difficulties
**Symptoms**: Problems connecting to external services or APIs, authentication failures, data not flowing between systems.
**Strategies**:
* Verify API keys and permissions first
* Ask Workshop to log the request/response cycle
* Create a minimal test case before implementing full functionality
```
Let's create a simple test that just verifies we can connect to
the service before trying to implement the full functionality.
```
### Deployment Issues
**Symptoms**: Application works locally but fails when deployed.
**Strategies**:
* Identify differences between local and production environments
* Verify all environment variables are set
* Deploy a simplified version first
```
The app works on my computer but fails when deployed. What could
be different between these environments?
```
## Using Checkpoints as Safety Nets
Workshop's checkpointing system creates automatic snapshots of your project as you work. Use this to your advantage during debugging:
* **Before risky changes**: Know that you can restore to the current state if something goes wrong
* **After finding a working state**: If you have achieved partial progress, note the checkpoint so you can return to it
* **When trying multiple approaches**: Restore to the pre-attempt state between different debugging strategies
You can also use git branches for more permanent safety:
```
Let's create a new branch called "fix-login-bug" to try solving
this without affecting the main codebase.
```
## When Nothing Works
If you have tried multiple approaches without progress:
1. **Step back**: *"Stop. Let's reconsider our fundamental approach."*
2. **Simplify**: *"What's the absolute simplest version of this that could work?"*
3. **Get external input**: Search the web, check documentation, or ask in the [Discord community](https://discord.gg/ggqJkUN3vx)
4. **Start a fresh conversation**: Sometimes a clean context helps Workshop approach the problem differently (see [When to Start Fresh](/troubleshooting/when-to-start-fresh))
# Troubleshooting
Source: https://docs.workshop.ai/troubleshooting/index
Common issues and how to resolve them when building with Workshop.
Even with the power of AI, building software can sometimes be challenging. This guide helps you navigate common issues and provides strategies for getting back on track. Problem-solving is part of the building process, even with agentic coding.
## Quick Reference
| Issue | Description | Guide |
| - | - | - |
| **Network or connectivity problems** | Cannot start Workshop, send messages, or connect to services | [Network and Connectivity](/troubleshooting/network-connectivity) |
| **Workshop seems stuck or confused** | Circular suggestions, repeated failures, or inability to solve a problem | [Debugging Strategies](/troubleshooting/debugging-strategies) |
| **Project has gotten too complex** | Lost in complexity, too many changes without progress | [When to Start Fresh](/troubleshooting/when-to-start-fresh) |
| **Misunderstood requirements** | Generated code does not match what you described | [Debugging Strategies](/troubleshooting/debugging-strategies) |
| **Technical errors in generated code** | Error messages, features that do not work, console warnings | [Debugging Strategies](/troubleshooting/debugging-strategies) |
| **Performance issues** | Slow application, high memory usage, long loading times | [Debugging Strategies](/troubleshooting/debugging-strategies) |
| **Integration difficulties** | Problems connecting to APIs, authentication failures | [Debugging Strategies](/troubleshooting/debugging-strategies) |
| **Deployment issues** | Works locally but fails when deployed | [Debugging Strategies](/troubleshooting/debugging-strategies) |
## Common Challenges at a Glance
### Workshop Misunderstands Your Requirements
* Be more specific — provide concrete examples and analogies
* Break down complex requests into smaller pieces
* Use the correction pattern: acknowledge what works, identify what needs to change, explain the desired outcome
### Technical Errors in Generated Code
* Share the exact error message with Workshop
* Ask for both an explanation and a fix
* Use version control to revert if changes make things worse
* Test small pieces in isolation
### Performance Issues
* Ask Workshop to identify the bottleneck
* Request specific optimizations for your use case
* Be open to architecture changes if needed
### Integration Difficulties
* Verify API keys and permissions
* Examine request/response data to find formatting issues
* Create a minimal test case before implementing full functionality
### Workshop Seems Stuck
* Reset the approach: *"Let's step back. What's the simplest way to approach this?"*
* Provide examples of what you are trying to achieve
* Start a fresh conversation with key context
### Connectivity Issues
* Consult the [Network and Connectivity](/troubleshooting/network-connectivity) guide
* Ensure required domains are accessible on your network
* Upgrade to the latest version of Workshop
## Getting Help
If these guides do not resolve your issue:
* **Discord**: [Join our community](https://discord.gg/ggqJkUN3vx) for help from the team and other builders
* **Email**: Reach out to [help@workshop.ai](mailto:help@workshop.ai) for direct support
* **Documentation**: Browse the full docs at [docs.workshop.ai](https://docs.workshop.ai)
Troubleshooting is a natural part of the development process. By approaching problems methodically, communicating clearly with Workshop, and learning from each challenge, you will become more effective at resolving issues when they arise.
# Network and Connectivity
Source: https://docs.workshop.ai/troubleshooting/network-connectivity
Troubleshoot network, firewall, and connectivity issues with Workshop.
## Connection Issues
Experiencing connectivity issues with Workshop? This guide helps you troubleshoot and resolve network or firewall-related problems.
## Required Connections
To function correctly, Workshop needs access to several services. Ensure the following domains are accessible if you are on a restricted network:
| Domain/Service | Purpose | Port | Protocol |
| - | - | - | - |
| `*.workshop.ai` | Core services and updates | 443 | HTTPS |
| `*.googleapis.com` | Authentication and cloud services | 443 | HTTPS |
| `accounts.google.com` | Sign-in | 443 | HTTPS |
| `*.cloudfunctions.net` | Backend services | 443 | HTTPS |
| `*.firebaseio.com` | Real-time data sync | 443 | HTTPS / WSS |
| `api.github.com` | Template resources | 443 | HTTPS |
| `github.com` | Model downloads (local AI) | 443 | HTTPS |
| `huggingface.co` | Model downloads (local AI) | 443 | HTTPS |
| `us.i.posthog.com` | Analytics | 443 | HTTPS |
| `us-assets.i.posthog.com` | Analytics | 443 | HTTPS |
| `*.ingest.us.sentry.io` | Error reporting | 443 | HTTPS |
| `*.lemonsqueezy.com` | Payment processing | 443 | HTTPS |
## Identifying Connectivity Issues
You may have network issues if:
* You cannot start or send messages in Workshop
* You encounter error messages about connection failures
* You experience delayed responses or timeouts
## Troubleshooting Steps
Verify your device is online by visiting other websites in your browser.
If you are behind a corporate firewall, request IT to allowlist the domains listed above. For personal firewalls, check settings to allow Workshop access.
Verify your proxy allows connections to the required services.
Temporarily disable your VPN to test connectivity. If that resolves the issue, adjust VPN settings to allow traffic to the necessary domains.
Try alternative DNS servers such as `8.8.8.8` (Google) or `1.1.1.1` (Cloudflare). Flush your DNS cache to update records.
## Testing Your Connection
Verify network access from a terminal:
```bash theme={null}
# Ping the main Workshop domain
ping workshop.ai
# Test HTTPS connection
curl -I https://workshop.ai
```
Repeat for other required domains if needed.
## SSL Intercept Issues (Proxy)
If you see an error like:
```
ConnectError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify
failed: self-signed certificate in certificate chain
```
This typically means a corporate proxy is intercepting SSL traffic. To resolve:
1. **Obtain the proxy's CA certificate** — this is usually a `.pem` or `.crt` file from your IT department
2. **Install the CA certificate system-wide:**
* **macOS**: Add it to the "System" keychain in Keychain Access and set trust to "Always Trust" for SSL
* **Windows**: Import into the "Trusted Root Certification Authorities" store for "Local Computer"
* **Linux**: Place the `.crt` file in `/usr/local/share/ca-certificates/` and run `sudo update-ca-certificates`
## Upgrading Workshop
Many connectivity issues are resolved by upgrading to the latest version. Visit [workshop.ai](https://workshop.ai) to download the latest release, or check the announcements section within the application.
## Need More Help?
If issues persist:
1. Document your network setup details (firewall type, proxy configuration, VPN provider)
2. Capture any error messages you see
3. Contact Workshop support with this information:
* **Email**: [help@workshop.ai](mailto:help@workshop.ai)
* **Discord**: [Join our community](https://discord.gg/ggqJkUN3vx)
Network configurations vary widely between organizations. Your IT department may need to implement specific solutions for your environment.
# When to Start Fresh vs. Persist
Source: https://docs.workshop.ai/troubleshooting/when-to-start-fresh
A decision framework for knowing when to continue a conversation versus starting a new one.
One of the most important judgment calls in agentic coding is knowing when to keep working in the current conversation versus starting fresh. Both choices have trade-offs, and the right answer depends on your situation.
## Consider Starting Fresh When:
* You have made multiple major changes without progress
* The codebase has become overly complex due to accumulated fixes and workarounds
* You have gained insights that suggest a fundamentally different approach
* The conversation has grown very long and credit cost per message is increasing
* Workshop seems confused by conflicting instructions from earlier in the conversation
```
We've tried patching this approach several times, but I think we
need to reconsider our basic architecture. Let's start fresh with
what we've learned.
```
**When starting a new conversation for an existing project**, bring key context forward:
```
This is an existing [type of project] that does [main functionality].
Look around the project directory to understand the current
implementation, then help me add [new feature].
```
## Persist When:
* You are making incremental progress, even if it is slow
* The issues are specific and isolated rather than systemic
* You have a clear debugging path to follow
* Workshop has built up useful context about your project that would be expensive to recreate
* You are close to a solution and just need a few more iterations
```
We're getting closer. The authentication flow is almost working,
and I think we just need to fix the token refresh logic.
```
## The `/compact` Command: A Middle Ground
When your conversation is getting long but you are not ready to start fresh, the `/compact` command offers a middle ground. It summarizes the conversation to reduce context size while preserving key information.
Use `/compact` when:
* The conversation is long and you notice credit costs increasing
* You want to continue the current line of work but shed irrelevant earlier context
* You have completed one phase of work and are moving to a new phase within the same project
## Decision Framework
Ask yourself these questions:
**Approach problems** (wrong architecture, wrong library, wrong pattern) are better solved by starting fresh with a new plan. **Execution problems** (a specific bug, a missing feature, a configuration issue) are better solved by persisting.
If Workshop has built up significant understanding of your codebase, starting fresh means it has to re-learn that context. If the conversation is mostly failed attempts, starting fresh costs you very little.
Credit cost per message increases with conversation length. If you are spending more credits on context than on useful work, it is time to start fresh or use `/compact`.
If Workshop is making suggestions that contradict earlier decisions or referencing files that no longer exist in their current form, the conversation context may be doing more harm than good.
## Signs You Should Start Fresh
* Workshop keeps suggesting the same fix you have already tried
* The conversation has accumulated contradictory instructions
* You realize the initial approach was wrong and need to go in a different direction
* You are spending more time explaining the conversation history than making progress
* Error messages are piling up and Workshop seems to be going in circles
## How to Start Fresh Effectively
1. **Save your progress** — Commit any working code before starting a new conversation
2. **Note what you learned** — Write down the key insights and failed approaches
3. **Update `.workshop/rules.md`** — Add any new constraints or decisions to your project rules
4. **Start with context** — Give the new conversation a concise summary of the project and what you want to accomplish
5. **Reference specific files** — Point Workshop to the relevant parts of your codebase rather than expecting it to discover everything
```
I'm building a task management app with React and Supabase.
The authentication is working but I'm having trouble with
real-time subscriptions. Check src/hooks/useRealtimeSync.ts
for the current implementation. The issue is that updates
from other users aren't appearing without a page refresh.
```
## Best Practices for Multi-Conversation Projects
For projects that span many conversations:
* **Keep `.workshop/rules.md` up to date** — This is the persistent memory across conversations
* **Commit at milestones** — Every working state should be a git commit
* **Use descriptive commit messages** — They help Workshop (and you) understand project history
* **Document decisions** — Add notes about why you chose certain approaches, not just what you built
* **Start each conversation with orientation** — Give Workshop a brief tour of the current state before diving in
# Workshop Arena
Source: https://docs.workshop.ai/workshop-cloud/arena
Create four versions of the same idea for free in Arena, compare the working apps, and choose your favorite.
# Build four versions for free. Pick the best.
Workshop Arena turns one brief into four free builds, created in parallel by four different AI models. Try each result, compare them without knowing which model made which app, and open your favorite as a regular Workshop project.
Arena builds are free. You can run one battle at a time.
Describe the app once instead of rebuilding the same idea model by model.
Explore different implementations and design directions side by side.
Choose your preferred result and continue building it in Agent Mode.
Rayline, the creator of Workshop Arena, uses Arena prompts, uploads, generated apps, and votes to benchmark and improve ARC, its AI model. Do not include personal or confidential information. See the [Workshop Terms of Use](https://workshop.ai/termsandconditions) and [Privacy Policy](https://workshop.ai/privacypolicy).
## When to use Arena
Arena is most useful when you are starting a new app and want to explore several strong first versions before committing to one direction.
Use Arena when you want to:
* Compare different layouts, visual styles, or product approaches
* Get several interpretations of an idea without repeating your prompt
* Judge models by the apps they produce instead of choosing a model first
* Find a strong starting point, then refine it in Workshop
Arena is designed for new frontend apps such as websites, prototypes, dashboards, and interactive tools. If you want to modify an existing project, or your app needs a backend, database, authentication, or integrations, use **Agent Mode**. You can also choose an Arena result first and add those capabilities after opening it in Agent Mode.
Arena is currently available in Workshop Cloud. It is not available in Workshop Desktop.
## Build and compare
Go to [app.workshop.ai](https://app.workshop.ai) and select **Arena** from the mode control on the Home screen.
Write one clear brief for all four models. Include the audience, the main job the app should accomplish, essential interactions, and any visual direction that matters.
You can also attach reference images or other supporting files.
```
Build an interactive trip planner for a week in Kyoto. Let travelers
organize activities by day, save places from a searchable list, and see
the route on a map. Use a calm editorial style inspired by Japanese
travel magazines, and make it work well on phones.
```
Click **Build** to start the battle.
Arena gives the same brief and starting point to four models. Each model works independently and produces its own app.
You can watch their progress, choose **Notify me when ready**, or leave and return later through **Projects → Arena**. If you stay on the page, select **Play while you wait** to open the Arena Arcade.
When the builds are ready, select **Review apps**. Try each app and answer **Does this build get the essentials right?**
Focus on whether the important interactions work and whether the result fulfills your brief. If something is missing or broken, you can optionally add a reason.
Arena shows the apps in a series of head-to-head comparisons. The model names stay hidden so you can judge the results without brand bias.
For each pair, choose:
* **Works better** — which app is more useful, complete, and reliable
* **Looks better** — which app has the stronger design and presentation
You can choose a tie when the apps are equally strong.
After the comparisons, Arena ranks the completed apps and reveals which model made each one.
Preview the results, choose the version you want, and select **Open in Agent Mode**. Workshop creates an editable project from that build so you can continue the conversation, change the code, add features, connect services, and publish it normally.
## Write a strong Arena brief
All four models receive the same instructions, so the brief is the foundation of the comparison. Describe the outcome you care about without prescribing every implementation detail.
```
Build a mobile-friendly inventory dashboard for a small vintage clothing
store. The owner should be able to see low-stock items and upcoming
restocks at a glance.
```
```
Users need to filter by category and supplier, update an item's stock
count, and open a detail view with its sales history.
```
```
Use a warm editorial style with cream backgrounds, dark green accents,
large product photography, and clear typography. Avoid a generic admin
dashboard look.
```
Specify what the app must accomplish, but avoid dictating every component or layout. Arena is most valuable when the models have room to propose different strong approaches.
## Find and resume your battles
Arena battles appear alongside your other work under **Projects**. Use the **Arena** filter to see only Arena battles.
You can return to a battle while it is building, when it is ready for review, or after its ranking is complete. Before starting another battle, finish comparing the completed apps from your current one.
## If a build does not complete
Arena waits for all four build slots to finish or report a problem before opening the review. If at least two apps complete, you can compare and rank the successful results. An unsuccessful candidate is left out of the comparison.
If fewer than two apps complete, Arena saves your brief and any completed result. Start a new battle when you are ready to try again.
## Frequently asked questions
Arena uses four AI models selected by Workshop. The lineup can change as new models become available. Model names remain hidden during review and are revealed with the final ranking.
Blind comparison keeps the focus on the working apps. It helps you choose based on what each result actually does and how it feels to use, rather than your expectations about a model or provider.
Arena's four initial builds do not use Workshop credits. After you open your chosen version in Agent Mode, continued building uses credits normally. You can have one battle building or waiting for comparison at a time.
An Arena battle becomes one Workshop project. Review the ranked apps, then open the version you want to continue building in Agent Mode.
Arena starts a fresh app from your brief so every model begins from the same place. Use Agent Mode to work on an existing project.
Yes. First open your chosen result in Agent Mode. From there, you can continue refining it and publish it like any other Workshop Cloud project. See [Publishing and custom domains](/workshop-cloud/publishing).
## Next steps
* [Start building in Workshop Cloud](https://app.workshop.ai/arena)
* [Learn how to work with the agent](/core-concepts/working-with-the-agent)
* [Publish and share your chosen app](/workshop-cloud/publishing)
# GitHub Integration
Source: https://docs.workshop.ai/workshop-cloud/github-integration
Connect Workshop Cloud projects to GitHub for version control, backup, and collaboration.
Workshop Cloud integrates with GitHub so you can back up your projects, collaborate with others, and maintain version history — all without leaving the browser.
Workshop Desktop also has GitHub integration with the same push/pull mechanics and the added ability to import directly from a repository URL. See [GitHub Integration](/workshop-desktop/github-integration) in the Desktop section.
## Connecting GitHub
Before linking projects, you need to connect your GitHub account to Workshop.
Navigate to **Hub** and select the **Connectors** tab (or go directly to `/hub?tab=connectors`).
Click **Connect** on the GitHub connector. This starts a GitHub App OAuth flow where you authorize Workshop to access your repositories.
During installation, you choose which repositories Workshop can access — either **all repositories** or **selected repositories** in your account or organization.
After authorizing, you're redirected back to Workshop. Your GitHub username and avatar appear in the Connectors panel, confirming the connection is active.
If you belong to multiple GitHub organizations, you can install the GitHub App on each one. Use the installation selector in the Connectors panel to switch between them.
## Linking a Project to a Repository
Once GitHub is connected, you can link any Workshop Cloud project to a GitHub repository.
1. Open your project and navigate to the **GitHub** section in the project settings
2. Click **Link GitHub Repository**
3. In the modal that appears, search for or select the repository you want to link
4. Choose the branch (defaults to the repository's default branch)
5. Confirm the link
After linking, the GitHub section shows the repository name, branch, sync status, and timestamps for the last push and pull.
## Push and Pull Workflow
Once linked, you can sync changes between your Workshop Cloud project and GitHub:
### Pushing to GitHub
Click the **push** button (up arrow) to send your local project changes to the linked GitHub repository. This creates a commit on the linked branch with your latest changes.
### Pulling from GitHub
Click the **pull** button (down arrow) to fetch the latest changes from GitHub into your Workshop Cloud project. This is useful when collaborators push changes directly to the repository.
## Sync Status Indicators
The GitHub section displays a real-time sync status icon:
| Status | Icon | Meaning |
| - | - | - |
| **In sync** | Green checkmark | Your local project matches the remote repository |
| **Local ahead** | Yellow up arrow | You have unpushed local changes (shows count, e.g., "3 ahead") |
| **Remote ahead** | Yellow down arrow | The remote has changes you haven't pulled yet (shows count, e.g., "2 behind") |
| **Diverged** | Red warning | Both local and remote have independent changes that conflict |
## Handling Diverged Histories
When the sync status shows **Diverged**, it means both your Workshop Cloud project and the GitHub repository have changes that the other doesn't. You have two options:
* **Force push** — Overwrites the remote repository with your local state. Use this when your local version is the one you want to keep. Workshop will prompt you to confirm before force pushing.
* **Force pull** — Overwrites your local project with the remote state. Use this when the GitHub version is the one you want to keep. Workshop will prompt you to confirm before force pulling.
Force push and force pull are destructive operations. The overwritten changes cannot be recovered. Make sure you know which version you want to keep before confirming.
## Importing a Repository as a New Project
To start a Workshop Cloud project from an existing GitHub repository:
1. Create a new project and select **Import from GitHub** as the template
2. Choose the repository from your connected GitHub account
3. Workshop pulls the code into your project — you're ready to build from there
Alternatively, create any new project, [link it to an existing repository](#linking-a-project-to-a-repository), and pull the code.
## Unlinking a Repository
To disconnect a project from its GitHub repository:
1. Open the GitHub section in your project
2. Click the **three dots** menu
3. Select **Unlink**
4. Confirm the action
Unlinking does not delete any code — your Workshop Cloud project and the GitHub repository both remain intact. You can re-link the same or a different repository at any time.
## Refreshing Status
If you suspect the sync status is stale (for example, after someone else pushes to the repository), click the **three dots** menu and select **Refresh** to fetch the latest status from GitHub.
## Use Cases
Push regularly to maintain a commit history of your project's evolution. If something breaks, you can always pull a previous state from GitHub.
Multiple people can work on the same project — one person builds in Workshop Cloud and pushes, while others pull the latest changes from GitHub and continue building.
GitHub acts as an automatic backup for your Workshop Cloud projects. Even if you delete a project in Workshop, the code remains in your GitHub repository.
Since your code lives in GitHub, you can set up GitHub Actions or other CI/CD pipelines to run tests, linting, or deploy to additional environments when changes are pushed.
# Workshop Cloud
Source: https://docs.workshop.ai/workshop-cloud/index
Build, preview, and publish apps from your browser — no downloads, no local setup.
Workshop Cloud is the browser-based version of Workshop. Start building from any device — nothing to install, nothing to configure.
It's designed for building **data apps** — interactive dashboards, internal tools, reports, and prototypes — with an integrated live preview and one-click publishing.
## Key Capabilities
Describe what you want in plain language. Workshop writes the code, runs it, and shows you the result.
See your app running in real time on the right side of the screen as Workshop builds it. No switching tabs or hunting for a local URL.
Link databases, warehouses, Google Sheets, and file uploads. Use them across conversations with the @ mention selector.
Deploy your app to a shareable URL with a single click. Control whether it's public or limited to specific people — Workshop handles hosting and access.
## How It Works
Workshop writes and executes code in the cloud, not in your browser.
* You own everything you create and can download project files at any time
* Start a project on one device, pick it up from another
* No dependency management, no environment setup, no "works on my machine" issues
### The live preview pane
The preview pane on the right-hand side automatically shows your running app as you build. When Workshop detects you're building something visual — a dashboard, a form, a chart — it opens the preview and keeps it synced with your latest code. You see exactly what your users will see, updated in real time, without leaving the conversation.
## Supported Tech Stacks
When you create a new project, you choose a starting template:
| Template | Best For |
| - | - |
| **Dynamic React App** (default) | Fullstack apps with a React frontend and a Python backend. The most extensible option — supports a wide range of libraries and frameworks. |
| **Static React App** | React frontend with no backend. Best when you don't need a server, database, or logins. |
| **Dynamic HTML App** | Plain HTML/CSS/JavaScript frontend with a Python backend. Best when your tools don't support React. |
| **Streamlit App** | Python-native data apps with charts, tables, and interactivity built in. Great for data exploration, KPI trackers, and chart-heavy applications. |
| **Anything** | Custom web apps or ad-hoc tasks in the cloud. Use this for projects that don't fit a preset stack. |
| **Import from GitHub** | Start from an existing repository. |
Not sure which to pick? **Dynamic React App** is the most versatile starting point.
## Who It's For
Workshop Cloud is ideal when you want to:
* **Prototype quickly** — Go from idea to working app in minutes, not days
* **Build data apps** — Dashboards, explorers, reports, and internal tools
* **Share instantly** — Publish with one click and send a link to stakeholders
* **Work from anywhere** — Build from any browser on any device, with no local setup
## Workshop Cloud vs Desktop
Workshop Cloud is optimized for data apps with a streamlined build-preview-publish workflow. If you need full-stack flexibility — different programming languages, local file system access, custom frameworks, or local AI models — use [Workshop Desktop](/getting-started/desktop-quickstart).
You can sync projects between Workshop Cloud and Desktop using [Web ↔ Desktop Sync](/core-concepts/web-desktop-sync). See [Cloud vs Desktop](/getting-started/cloud-vs-desktop) for a detailed comparison.
## Next Steps
Build your first app in the browser in under 5 minutes.
Understand the template options and when to use each.
Deploy and share your apps.
Back up and collaborate via GitHub.
# One-Click Publishing
Source: https://docs.workshop.ai/workshop-cloud/publishing
Deploy your Workshop Cloud app to a shareable URL with a single click.
Workshop Cloud includes built-in publishing. Click **Publish**, and your app is deployed to serverless infrastructure with a unique URL that anyone can access.
## Preview Pane
The preview pane shows your running application as Workshop builds it. It appears in the right sidebar and updates live as Workshop writes code.
### Start App
For templates that include a dev server (Dynamic React App, Static React App, Dynamic HTML App, Streamlit App), Workshop automatically starts your application and displays it in the preview pane. You can also control the dev server manually:
* **Start App** — Click the play button in the preview pane header to start or restart the dev server
* **Stop** — Click the stop button to shut down the running server
* **Restart** — If your app gets into a bad state, stop and restart to get a fresh server process
The preview URL is a proxied localhost address unique to your cloud environment. You can open it in a new tab for a full-screen view.
If the preview pane shows a blank screen or error, try clicking **Start App** to restart the dev server. Workshop creates a startup script tailored to your project's tech stack.
## How Publishing Works
Click the **Publish** button in the top-right corner of the Workshop Cloud interface. A popover opens showing your deployment settings and the URL your app will be available at.
Choose who can access your published app:
* **Public** — Anyone with the URL can use your app. No sign-in required.
* **Private** — Only people you explicitly invite by email can access it. Requires a paid plan.
Click **Publish** in the popover. Workshop packages your project files, injects any required secrets and connector credentials, and deploys everything to serverless infrastructure.
Deployment typically takes 30 seconds to 2 minutes depending on project size and dependencies. The maximum timeout is **5 minutes**.
Once deployed, copy the shareable URL and send it to anyone. They can start using your app immediately.
## Custom Project URLs
Every published app gets a unique URL based on your project's **slug** — an auto-generated identifier like `gentle-elephant-alice`. The resulting URL follows the pattern:
```
https://{your-project-slug}.workshop.build
```
On a paid plan (Build, Scale, or Max), you can **rename the slug** to something more meaningful. Renaming is only available when the app is stopped — stop the app first, rename, then republish.
Slug names must be 3-50 characters, lowercase letters, numbers, and hyphens only. No leading, trailing, or consecutive hyphens. Each slug must be globally unique.
## Custom Domains
On any paid plan — **Build**, **Scale**, or **Max** — you can serve your published app from your own domain (e.g. `app.yourcompany.com`) instead of the default `workshop.build` URL. Workshop issues and renews the SSL certificate for your domain automatically once DNS is pointed at the Workshop origin.
**Prerequisite:** you must already own the domain (or subdomain) you want to use, and have access to edit DNS records at your registrar or DNS provider (Namecheap, GoDaddy, Route 53, etc.). Workshop does not sell or register domains on your behalf.
Click **Publish** on a project you've already deployed, and locate the **Custom Domain** section.
Click **Add custom domain**, enter the hostname you own (for example `app.yourcompany.com`), and click **Add**. Workshop enables routing for that hostname and shows you the CNAME target to add at your DNS provider.
In your registrar or DNS provider's control panel, add a CNAME record for your hostname pointing to `origin.workshop.build`:
```
CNAME app.yourcompany.com → origin.workshop.build
```
This is the step that actually connects your domain to your Workshop app — until this record is in place and propagates, your domain won't serve the app.
The Custom Domain section shows **Pending** until Workshop sees the CNAME and finishes issuing the SSL certificate. Once verified, the status turns **Active** and visitors of your hostname start receiving the app over HTTPS. Click **Check status** to refresh manually — propagation and SSL provisioning typically complete within a few minutes.
Custom domains require a paid plan — **Build**, **Scale**, or **Max**. Free (Discover) subscribers see an upgrade prompt instead of the domain input field.
**Notes and limits:**
* One custom domain per app. To switch domains, remove the existing one first, then add the new hostname.
* Subdomains (`app.yourcompany.com`, `www.yourcompany.com`) are the recommended choice — they point to Workshop via a standard CNAME record.
* Apex domains (`yourcompany.com` with no subdomain) are supported via A/AAAA records to Workshop's anycast IPs after a one-time TXT ownership check. Workshop classifies apex vs subdomain automatically from the hostname you enter; see [Apex domains](#apex-domains) below for the steps.
* The default `{slug}.workshop.build` URL continues to work alongside your custom domain.
## Apex Domains
To serve your app from an apex (root) domain like `yourcompany.com` instead of `www.yourcompany.com`, Workshop uses A/AAAA records pointed at our global anycast IPs. Because the DNS standard forbids a CNAME at the apex, Workshop cannot infer ownership from your DNS the way it does for subdomains, so you add a one-time TXT record first, then the A/AAAA records.
Open the Publish popover, click **Add custom domain**, enter your apex (e.g. `yourcompany.com`), and click **Add**. Workshop returns a one-time verification token along with DNS instructions.
Add a TXT record at the host `_workshop-verify` with the token from the popover as its value:
```
TXT _workshop-verify →
```
Most registrars want the host as the relative label `_workshop-verify` (not the full `_workshop-verify.yourcompany.com.`). The popover shows the exact label and token, with copy buttons for both.
Once the TXT record is in place (typically under five minutes), click **Verify domain** in the popover. Workshop confirms the TXT and reveals two records to add next:
```
A @ → 34.8.221.48
AAAA @ → 2600:1901:0:be48::
```
These are Workshop's stable anycast addresses. The popover shows them with copy buttons, so you don't need to memorize them.
Add both records at the apex (`@` host) at your DNS provider. Once they propagate, the popover flips from **Pending** to **Active** and Workshop's edge issues a Let's Encrypt SSL certificate on the first request. Click **Check status** to refresh manually.
Workshop classifies apex vs subdomain automatically from the hostname you enter; there's no separate setting. Subdomains (`www.yourcompany.com`, `app.yourcompany.com`) continue to use the simpler CNAME flow above.
If your registrar locks the apex `@` row or charges to add A records there, use `www.yourcompany.com` as your Workshop hostname instead and configure a URL redirect from the apex to `www` at your registrar. The CNAME at `www` works on every registrar.
## Public vs Private Apps
### Public Apps
* Select **"Anyone on the internet"** in the Visibility dropdown
* No sign-in required for visitors
* Available on all plans including the free Discover tier
### Private Apps
* Select **"Only people invited"** in the Visibility dropdown
* Invite specific people by email in the **"Who can access"** section
* Visitors who aren't invited see an "Access Restricted" page
**How private app authentication works:**
1. A visitor opens your private app URL
2. If they're not signed in, they're redirected to a sign-in page showing your app name and your identity as the owner
3. They sign in with Google or request an email magic link
4. After signing in, they're redirected back to your app automatically
Private apps require a paid plan. On the **Build** plan, you can invite up to **5 viewers** and publish **1 private app**. The **Scale** and **Max** plans offer **unlimited** viewers and private apps.
## What Happens During Deployment
When you click Publish, Workshop performs these steps:
1. **File packaging** — Your project files are collected and uploaded to the deployment infrastructure
2. **Resource validation** — Workshop scans your code for references to secrets and connectors that aren't included in the project context. If any are found, deployment pauses and shows you which resources are missing (see [Resource Validation](#resource-validation) below)
3. **Secret injection** — Any secrets you've configured (API keys, database credentials) are securely injected into the deployment environment
4. **Connector credentials** — If your project uses managed connectors (Workshop-provided AI connectors), fresh API keys are auto-generated for the deployment
5. **App startup** — Your app's start command is auto-detected and executed (Streamlit run command or FastAPI server)
6. **URL routing** — Traffic is routed to your app through the project slug URL
## Resource Validation
Before deploying, Workshop scans your code for references to secrets and connectors that aren't included in the project context. If any are found, deployment pauses and shows you which resources are missing so you can fix the issue before your app goes live with broken credentials.
You can add the missing resources to your project context directly from the prompt, skip validation and publish anyway, or dismiss and fix the code first.
Secrets defined in a `.env` file in your project root are automatically included in your deployment. You don't need to add them separately — Workshop picks them up during the publish process. To leave a specific env file out, see [Choosing Which Configuration Files Ship](#choosing-which-configuration-files-ship).
## Choosing Which Configuration Files Ship
Your project root's `.env` file is treated specially: its values are applied to the published app as environment variables, and the file itself is not uploaded. This is how your configured secrets reach the deployment.
Other environment files in your project root (`prod.env`, `.env.local`, and similar) are included in the deployment. For apps whose deployment packages the source, they ship as files; for apps with a frontend build (static/React), they are build inputs rather than shipped assets — only the built output is served. Either way, if you keep a local-only env file in the project (for example, one holding development database credentials you don't want in production), you can choose to leave it out.
When your project has one or more root-level configuration files, the Publish dialog shows a **Configuration files included in deployment** section (under **Advanced**). It lists each file with a checkbox:
* **Checked** — the file is included in the deployment, as described above.
* **Unchecked** — the file is excluded from the deployment. It is not uploaded, and for `.env` its values are not picked up as deployment secrets.
Unchecking a file affects only that publish; your local project files are never modified.
Selection is available for cloud apps. It isn't offered on the desktop app, where all root-level configuration files are included — keep local-only secret files outside the project directory if you don't want them published.
For apps with a frontend build (React and other Vite-based frontends), a build reads values your code references from `.env` and compiles them into the built assets. If you uncheck that file, those values are left out of the build; if you keep it checked, they are baked into the published frontend, so treat any `VITE_`-prefixed value as publicly visible.
## Updating a Published App
After making changes to your project, click **Update** in the Publish popover to push the latest version. The deployment URL stays the same — visitors see the new version once the update completes.
## Stopping a Published App
To take your app offline:
1. Open the Publish popover
2. Click **Stop**
3. Confirm the action
Stopped apps show a friendly "App Temporarily Unavailable" page to visitors instead of a technical error. You can republish at any time.
## Viewing Published Apps
On the Projects page, published apps display a green **Live** indicator with the deployment URL. You can filter your projects by the **Live** tag to see only published apps. Clicking the URL opens the app in a new tab.
## Hide Workshop Branding
On paid plans, you can remove the Workshop badge from your published apps. Toggle the **Hide branding** option in the Publish popover's advanced settings. Private apps can always hide branding regardless of plan.
## Plan Limits
| Feature | Discover (Free) | Build | Scale | Max |
| - | - | - | - | - |
| Public apps | Unlimited\* | Unlimited | Unlimited | Unlimited |
| Private apps | Not available | 1 | Unlimited | Unlimited |
| Invited viewers (per private app) | N/A | 5 | Unlimited | Unlimited |
| Custom slug rename | No | Yes | Yes | Yes |
| Custom domains | No | Yes | Yes | Yes |
| Hide branding | No | Yes | Yes | Yes |
\* To optimize cloud resources, we automatically unpublish Discover-tier apps after 24h.
## Troubleshooting
Workshop detected that your code references secrets or connectors not included in the project context. Click **Add to Context** to include them and retry, or **Publish Anyway** if you're certain the references are safe to ignore. You can also add connectors and secrets manually from the project's Context tab before publishing.
Deployments have a 5-minute timeout. If your app has many large dependencies, it may take longer to install them. Try simplifying your requirements or breaking the project into smaller pieces.
This means the deployment has stopped. Open your project in Workshop Cloud and click **Publish** again to redeploy. If the app keeps stopping, check your app's startup logic for errors.
To optimize cloud resources, we automatically unpublish Discover-tier apps after 24h. If you need apps that stay live for longer than 24 hours, you can upgrade to one of our paid plans.
Private visibility requires a paid plan. On the Build plan, you're limited to 1 private app — if you already have one, you'll need to upgrade to Scale or Max, or make the existing private app public first.
You can only rename a slug when the app is stopped. Stop the app first, rename the slug, then republish.
Workshop verifies your CNAME record before issuing the SSL certificate. Confirm the CNAME at your DNS provider points to `origin.workshop.build` exactly, and allow a few minutes for DNS propagation. Click **Check status** to re-check. If the status stays pending for more than \~15 minutes, use `dig` or `nslookup` to verify the CNAME resolves correctly, and that no conflicting A/AAAA records exist for the same hostname.
Custom domains are available on the Build, Scale, and Max plans. On the Free (Discover) plan the section shows an upgrade prompt. Upgrade to a paid plan from the [Plans page](/pricing/plans) to enable it.
Workshop polls public DNS resolvers for the `_workshop-verify` TXT record. Propagation typically takes under five minutes but can occasionally run longer. Click **Verify domain** again, or run `dig _workshop-verify.yourcompany.com TXT` from your terminal to confirm the record is visible. If the value is correct but verification still fails, double-check that the host label is the relative `_workshop-verify` rather than the FQDN form (`_workshop-verify.yourcompany.com.`); some registrars accept both, others reject the FQDN form.
The status flips to Active once Workshop sees your apex resolving to its anycast IPs. Verify with `dig yourcompany.com A` (expect `34.8.221.48`) and `dig yourcompany.com AAAA` (expect `2600:1901:0:be48::`). Two common gotchas:
* **Registrar URL forwarding overrides A records.** If your registrar has a "domain forwarding" or "URL redirect" rule pointing the apex elsewhere, that takes precedence; disable it before adding the A/AAAA records.
* **Stale records at `@`.** Some registrars keep parking-page A records at the apex; remove them so only Workshop's anycast IPs are returned.
SSL provisioning then takes another 30–60 seconds on the first request after the records resolve correctly.
A few registrars (and some entry-level shared-hosting bundles) lock the apex `@` row or charge extra to edit it. If you can't unlock it, use `www.yourcompany.com` as your Workshop hostname instead, and set up a URL redirect from the apex to `www` at your registrar. The subdomain CNAME flow described above works on every registrar.
# Sharing and Teams
Source: https://docs.workshop.ai/workshop-cloud/sharing-and-teams
Share conversations with links and collaborate with your team through shared credits and centralized billing.
Workshop makes it easy to share your work — from individual conversations to full team collaboration with shared resources.
## Sharing Conversations
You can share any conversation via a private link, whether to show someone an insight, demonstrate a concept, or get support.
### How to Share
Sharing always applies to the conversation you currently have open, so open it first.
Open the project that contains the conversation you want to share.
In the **Conversations** panel, click the conversation. It becomes the current conversation.
Click the project name with the caret (⌄) in the top-left of the window to expand the menu. The menu shows the current conversation name at the top.
Under the **CONVERSATION** section, click **Share**.
In the **Share Conversation Privately** dialog, click **Share**. Workshop creates a private link — anyone with the link can view the conversation, but it won't appear in search or public indexes.
Click **Copy link and close** (or the copy icon next to the URL) and send the link to your audience.
The link looks like `https://threads.workshop.ai/c/` and renders your conversation in a clean, readable format so recipients experience it just as you did.
**Share** is disabled until the conversation has at least one message.
### Best Practices Before Sharing
Before sharing, check your conversation for:
* Accidentally included secrets, credentials, or API keys
* Internal data that shouldn't be visible externally
* File contents or code that may be confidential
Remove or redact anything sensitive before generating the link.
* Will the technical level match the intended readers?
* Are there assumptions that need additional context?
* Would someone unfamiliar with your project understand the goals?
Open the shared link in a private/incognito browser window to verify:
* The conversation displays correctly
* All important context is included
* Code examples and media render properly
## Sharing Published Apps with Teams
If your project is linked to a **team subscription** (Scale or Max plan), you can share published apps with your entire team at once using the **Team sharing** toggle in the Publish popover. When enabled, all team members automatically get access to the app without individual invitations.
## Team Management
Teams let you collaborate with shared credit pools, centralized billing, and organization-wide settings.
Team management features require a **Scale** or **Max** plan subscription.
### What Teams Include
* **Shared credit pool** — All team members draw from a common credit allocation
* **Centralized billing** — A single subscription covers all team members
* **Privacy controls** — Enforce privacy mode across all team members
* **Credit Pack bonuses** — 10% more credits on Scale; the largest discount on Max
* **Dedicated support** — Priority support through shared team channels
### Setting Up a Team
Team features are available on the Scale and Max plans. Upgrade from your account settings.
Set your team name, default member credit limits, and privacy enforcement preferences.
Go to your team management dashboard, click **Invite Team Member**, and enter their email. You can optionally set individual credit limits.
Invited users receive an email with a link to join. Once they accept, they inherit team privacy settings and their credit limits take effect immediately.
### Member Roles
| Role | Capabilities |
| - | - |
| **Team Owner** | Full admin control: billing, invitations, member management, privacy enforcement, credit limit adjustments |
| **Team Member** | Access to shared credits, subject to team policies and individual credit limits |
### Seat Management
Both active team members and pending invitations count toward your seat limit.
**Occupied seats** = Active members + Pending invitations
If all seats are occupied, you can free up capacity by:
* Removing an existing team member
* Revoking a pending invitation
* Upgrading your subscription to add more seats
Pending invitations reserve a seat until accepted, revoked, or expired (after 30 days).
### Revoking Invitations
To cancel a pending invitation and free up the seat:
1. Open the **Invite Team Members** modal
2. Find the invitation in the **Pending Invitations** section
3. Click **Revoke**
The invitation link is immediately invalidated and the seat becomes available. The recipient is not notified.
Only team owners can revoke invitations. Once revoked, you'll need to send a new invitation to re-invite the same person.
## Team Credit Management
### How Credits Work
* All team members draw from a **shared credit pool** set by the team owner's subscription
* Team owners can set **individual credit limits** per member (default: 1,000 credits)
* Members cannot exceed their individual limit even if team credits remain
* Credit Pack purchases receive a **10% bonus** for team accounts
### Usage Monitoring
Team owners have real-time visibility into:
* Team-wide credit consumption
* Individual member usage
* Usage patterns and trends
## Privacy and Security
### Team Privacy Controls
* Team owners can **enforce privacy mode** for all members — individual members cannot disable it
* Team members' individual work remains private within the team structure
* Shared resources are accessible based on permissions
* Teams can optionally sync projects to the team's GitHub organization
## Plan Comparison for Sharing
| Feature | Discover (Free) | Build | Scale | Max |
| - | - | - | - | - |
| Share conversations via link | Yes | Yes | Yes | Yes |
| Published app viewers | Public only | 5 per private app | Unlimited | Unlimited |
| Team management | No | No | Yes | Yes |
| Shared credit pool | No | No | Yes | Yes |
| Privacy enforcement | No | No | Yes | Yes |
| Credit Pack bonus | No | No | 10% | Max discount |
| Remove Workshop badge | No | Yes | Yes | Yes |
## Getting Help
* **Email:** [help@workshop.ai](mailto:help@workshop.ai)
* **Community:** [Discord](https://discord.gg/ggqJkUN3vx)
* Scale and Max plan teams have access to **priority support** channels
# Project Templates
Source: https://docs.workshop.ai/workshop-cloud/templates
Choose a starting template when creating a new Workshop Cloud project — Dynamic React App, Static React App, Dynamic HTML App, Streamlit App, Anything, or Import from GitHub.
When you create a new project in Workshop Cloud, you choose one of six starting templates. Each sets up a different tech stack and project structure that Workshop uses as a foundation when building your app.
The three web templates vary on two things: whether they include a Python backend, and whether the frontend is React or plain HTML.
| | React frontend | HTML frontend |
| - | - | - |
| **Python backend** | Dynamic React App | Dynamic HTML App |
| **No backend** | Static React App | — |
## Template Options
### Dynamic React App
A **React** frontend with a **Python (FastAPI)** backend. The best choice for custom, design-rich applications where you want full control over the UI.
**Best for:**
* Custom-designed dashboards and data apps
* Interactive single-page applications
* Projects requiring specific React component libraries or design systems
* Apps with complex frontend state management
**What you get:**
* React frontend with full component architecture
* FastAPI Python backend for APIs and business logic
* Built-in frontend build pipeline
* One-click publish support
### Static React App
The same **React** frontend as above, with **no backend**. The whole project builds to static files, so there's no server to run.
**Best for:**
* Marketing sites, landing pages, and portfolios
* Client-side apps that don't store data or sign users in
* Projects that talk only to third-party APIs from the browser
**What you get:**
* React frontend with full component architecture
* No server, database, or secrets to manage
* One-click publish support
Choose this over **Dynamic React App** when you don't need a server, a database, or secrets. If you're unsure, start with **Dynamic React App** — it can do everything this template can, plus server-side work.
### Dynamic HTML App
A **Python (FastAPI)** backend with a plain **HTML/CSS/JavaScript** frontend. Pick this when your tools don't support React — otherwise **Dynamic React App** is the better choice, since it does the same server-side work with a richer frontend.
**Best for:**
* Libraries or tools that don't have React bindings
* API-first applications with minimal frontend
* Projects using vanilla JavaScript or lightweight libraries
* Quick prototypes that need server-side logic
**What you get:**
* FastAPI backend for building Python APIs
* Full control over HTML, CSS, and JavaScript — no framework overhead
* Flexible architecture for straightforward applications
* One-click publish support
### Streamlit App
A **Streamlit** application — a Python-native framework optimized for data apps. Streamlit handles UI rendering automatically — you write Python, and it generates interactive widgets, charts, and layouts.
**Best for:**
* Rapid analytics and data exploration tools
* KPI dashboards and chart-heavy applications
* Interactive data tools with sliders, dropdowns, and forms
* Quick prototypes that need a polished UI fast
**What you get:**
* Built-in UI components (buttons, charts, tables, forms, sliders)
* Automatic state management and caching
* Native data connector integrations
* Less code needed for interactive interfaces
* One-click publish support
### Anything
An empty project with no preset stack. You start with a clean slate and tell Workshop exactly what to build. Use this for desktop apps, working with files on your computer, custom web apps, or ad-hoc tasks — anything that doesn't fit the other templates, or when you want to experiment with a specific framework or approach.
Desktop apps and working with files on your computer are only possible in [Workshop Desktop](/workshop-desktop/index) — the cloud sandbox can build custom web apps and run ad-hoc tasks, but it has no access to your machine.
**Anything** projects don't support one-click publishing because there's no predefined tech stack for Workshop to detect and deploy automatically. If you need one-click publish, start with **Dynamic React App**, **Static React App**, **Dynamic HTML App**, or **Streamlit App**.
### Import from GitHub
Start from an existing repository. Workshop clones the repo into a new project so you can continue building on top of existing code.
**Best for:**
* Continuing work from an existing codebase
* Collaborating on a project that lives in GitHub
* Migrating a project into Workshop Cloud
## How to Select a Template
From the Projects page, click the **New Project** button.
In the project creation dialog, you'll see six options: **Dynamic React App**, **Static React App**, **Dynamic HTML App**, **Streamlit App**, **Anything**, and **Import from GitHub**. Click the one you want.
Enter a project name and click **Create Project**. Workshop remembers your last template selection, so it will be pre-selected next time.
## Add-Ons
When creating a project, you can enable **Add-Ons** — AI Providers and Database Providers — that Workshop provisions automatically alongside your project.
* **Dynamic React App**, **Static React App**, and **Dynamic HTML App** templates auto-enable **Gemini** (AI Provider) and **Neon** (Database Provider with Neon Auth) by default. You can toggle these on or off before creating the project.
* **Streamlit App** and **Anything** templates start with no Add-Ons enabled.
You can change Add-Ons at any time in **Settings** → **Resources** → **Add-Ons**.
**AI Providers** provision managed connectors for Anthropic, OpenAI, or Gemini — no API keys or setup required. Usage is billed to your Workshop credits.
**Database Providers** provision a managed Neon serverless Postgres database with built-in authentication (Neon Auth). Workshop handles credentials, auth domain syncing, and cleanup automatically.
## When to Use Each Template
Start with **Dynamic React App** if you care about design and layout. Use **Streamlit App** if you want to move fast and the built-in components are sufficient.
**Streamlit App** is the best choice. Its built-in widgets (date pickers, dropdowns, sliders) and charting libraries let you create interactive data exploration tools with very little frontend code.
Choose **Dynamic React App** for component-based architecture with a design system, or **Dynamic HTML App** for lightweight HTML/CSS/JavaScript without framework overhead.
Start with **Anything**. You can install any packages, use any framework, and structure the project however you want. Keep in mind that one-click publishing won't be available.
Go with **Dynamic React App** — it's the most flexible default for anything interactive, or **Dynamic HTML App** for simple sites.
Use **Static React App**. It builds to static files with no backend, which makes it faster to publish and cheaper to run. If you later need to store data or sign users in, switch to **Dynamic React App**.
## Template and Preview Behavior
The **Dynamic React App**, **Static React App**, **Dynamic HTML App**, and **Streamlit App** templates all work seamlessly with the preview pane and one-click publishing:
* **Preview** — Your app automatically appears in the preview pane as Workshop builds it, regardless of which template you chose
* **Publish** — All of them support one-click deployment to a shareable URL
If you outgrow what Workshop Cloud supports, you can sync your project to [Workshop Desktop](/workshop-desktop/index) and continue with full-stack flexibility.
# Checkpoints
Source: https://docs.workshop.ai/workshop-desktop/checkpoints
Automatic project snapshots that let you experiment freely and revert changes with confidence.
## What are checkpoints?
Checkpoints are automatic snapshots of your project files, captured at key moments during your conversation with Workshop. Think of them as a "time machine" for your project — they let you experiment freely, knowing you can always go back.
Whenever you send a message, or whenever Workshop modifies files or runs code, a checkpoint is automatically created. This captures the exact state of all your project files at that moment, without you needing to do anything.
## Why checkpoints matter
Try new approaches without fear. If a change doesn't work out, revert to the previous state in seconds.
No need to manually save or commit after every AI interaction. Checkpoints handle it seamlessly in the background.
See exactly when file changes occurred in the context of your conversation history.
Revert your entire project to any earlier state in your conversation — both files and chat history stay in sync.
## How checkpoints appear
Small icons appear next to certain messages in your conversation thread, indicating that a checkpoint was saved at that point:
* **Next to your messages:** A checkpoint was saved *before* Workshop started working on your request.
Hover over these icons to see quick details about the saved checkpoint.
## Restoring a checkpoint
Locate the message in your chat history that corresponds to the state you want to restore. Look for the checkpoint icon.
Click the action menu on that message (where you find options like "Copy").
Select the **Restore** button. A confirmation dialog appears.
Restoring will:
* Revert all project files to their state at that checkpoint
* Remove messages that came *after* the restored checkpoint from the chat view
This keeps your chat and project files in sync — like rewinding both simultaneously.
## When to use checkpoints
Checkpoints are designed for rolling back small or recent changes, typically within a few turns of your conversation.
**Checkpoints are great for:**
* Undoing a change that broke something
* Reverting an approach that didn't work out
* Recovering from an unintended file deletion
* Exploring multiple solutions and picking the best one
**For larger-scale version control, use Git:**
* Long-term project history
* Collaboration with others
* Branching workflows
* Projects with many files where snapshot size matters
Each checkpoint captures the full state of your project files. For large projects, checkpoints can grow in size and become slower to restore. Git is the better choice for structured, long-term version control.
## Checkpoints and Git
If you already use Git for your project, checkpoints work alongside it without interference:
* Checkpoints **do not** create `.git` files or folders in your project directory
* Checkpoints **respect** your `.gitignore` file automatically
* Your commits and Git history remain completely separate and unaffected
* Checkpoints are a complementary safety layer specifically for changes within your Workshop session
You can set up Git for your project through the Control Center or by asking Workshop directly. See [Settings](/core-concepts/settings) for more on version control setup.
# File System and Terminals
Source: https://docs.workshop.ai/workshop-desktop/file-system-and-terminals
How Workshop Desktop interacts with your local files and manages terminal sessions.
Workshop Desktop runs directly on your machine, giving the agent full access to your local file system. There are no restrictions on which files the agent can read, write, or execute — your project is a real directory you can open in any editor or terminal.
## Real-Time File Watching
Workshop Desktop monitors your project directory for changes. When you edit a file in an external editor, create new files, or delete something — Workshop detects it immediately and updates the file tree in the sidebar.
The file watcher is `.gitignore`-aware — files and directories listed in your `.gitignore` are excluded from the file tree by default, keeping the view focused on the files that matter.
## File Tree
The sidebar displays your project's file structure as an expandable tree. It mirrors your actual directory layout on disk.
Key behaviors:
* **Expand on demand** — Click a folder to load and display its contents. Subdirectories are fetched lazily to keep the interface responsive.
* **Automatic updates** — When the file watcher detects changes (new files, deletions, renames), the affected directories refresh automatically.
* **Drag and drop** — Drag files from your system into the chat to add their path to your message, giving the agent context about specific files.
### Opening the project folder
The **Files** tab toolbar has a terminal button, **Open project directory in terminal**, which opens your own shell already positioned in the project directory. This is a Workshop Desktop feature — it is not available in Workshop Cloud.
You can also navigate to the folder directly — see [where projects live on disk](/core-concepts/conversations-and-projects#working-across-environments) for the Workspace location on each platform.
**Copying the folder copies your project files, not your conversation history.** Workshop Desktop keeps project records and conversations in its own application data directory, separate from the project folder, so they do not travel with a copy.
You can copy a project directory to external storage or onto a second computer, and open it there with **New Project → Select existing folder** — Workshop only lists projects it knows about locally. That gives you your code and files, in a new project with no past conversations.
Treat a folder copy as a backup of your work, not of your whole Workshop project. For keeping two machines in sync as you work, [GitHub integration](/workshop-desktop/github-integration) is the better route.
## Terminal Sessions
Workshop manages its own **headless terminal sessions** — full PTY-backed shells that the agent can create, use, and destroy as needed. These aren't embedded terminal UIs; they're real shell processes that the agent drives programmatically, reading output and sending input (including key presses) just like a human would.
These are the agent's sessions, separate from [Open project directory in terminal](#opening-the-project-folder), which opens your own terminal application for you to use.
Terminal sessions work on both **Workshop Desktop** (running on your local machine) and **Workshop Cloud** (running in the cloud backend). On Desktop, the session uses your default shell. On Cloud, sessions run in the cloud environment.
### How the agent uses terminals
The agent has three core terminal operations:
* **Create / close sessions** — Spin up or tear down independent shell sessions on demand.
* **Execute commands** — Run a command and wait for output, with optional timeouts.
* **Send keystrokes** — Type text or press keys (`Enter`, `Ctrl+C`, arrow keys, etc.) into a running session, enabling interaction with prompts, TUIs, and long-running processes.
The agent can run **multiple sessions concurrently**. For example, you can tell it:
> "Run my app in one terminal, and use a different terminal for dependency management and git."
Each session is independent — stopping one doesn't affect the others.
### Supported shells
Sessions use your system's default shell. Commonly used shells include:
| Shell | Platform |
| - | - |
| **zsh** | macOS (default), Linux |
| **bash** | Linux (default), macOS |
| **fish** | macOS, Linux |
| **PowerShell** | Windows |
### Viewing terminal activity
You can view active terminal sessions in the **Terminals** tab of the side panel. When the agent is running a long command, a "View activity in terminal →" link appears in the status bar to jump directly there.
### Built on ht
Workshop's terminal sessions are powered by [ht](https://github.com/andyk/ht) (headless terminal), an open-source library that wraps any shell process with a VT100 terminal interface for programmatic access. We also maintain [ht-mcp](https://github.com/memextech/ht-mcp), an open-source MCP server that lets other AI agents embed the same headless terminal capability.
Because Workshop Desktop has full file system access, treat it like any other development tool — keep important files under version control and use [Checkpoints](/workshop-desktop/checkpoints) to snapshot your project state before major changes.
# GitHub Integration
Source: https://docs.workshop.ai/workshop-desktop/github-integration
Connect Workshop Desktop projects to GitHub for version control, collaboration, and syncing codebases.
Workshop Desktop integrates with GitHub so you can import existing repositories, link projects to repos, and push/pull changes — all from within the Workshop interface.
Workshop Cloud has the same push/pull mechanics. See [GitHub Integration](/workshop-cloud/github-integration) in the Cloud section. The key Desktop difference is the ability to import directly from a repository URL when creating a new project.
## Connecting Your GitHub Account
Before linking projects, connect your GitHub account through the GitHub App OAuth flow.
Navigate to **Hub** and select the **Connectors** tab.
Click **Connect** on the GitHub connector. This starts a GitHub App OAuth flow where you authorize Workshop to access your repositories.
During installation, you choose which repositories Workshop can access — either **all repositories** or **selected repositories** in your account or organization.
After authorizing, you're redirected back to Workshop. Your GitHub username and avatar appear in the Connectors panel, confirming the connection is active.
If you belong to multiple GitHub organizations, you can install the GitHub App on each one. Use the installation selector in the Connectors panel to switch between them.
## Importing a Repository as a New Project
You can create a new Workshop Desktop project from an existing GitHub repository:
1. Click **New Project** from the Projects page
2. Select **Import from Git** and choose a repository from your connected GitHub account
3. Workshop clones the repository and creates a project with the repo contents
This is useful for pulling in an external codebase for prototyping — make changes in Workshop, then push them back when ready.
## Linking an Existing Project to a Repository
If you already have a Workshop project and want to connect it to a GitHub repo:
1. Open your project and navigate to the **GitHub** section in the project settings panel
2. Click **Link GitHub Repository**
3. Search for or select the repository you want to link
4. Choose the branch (defaults to the repository's default branch)
5. Confirm the link
After linking, the GitHub section shows the repository name, branch, sync status, and timestamps for the last push and pull.
## Push and Pull Workflow
Once a project is linked to a GitHub repository, you can sync changes in either direction.
### Pushing to GitHub
Click the **push** button (up arrow) to send your local project changes to the linked GitHub repository. This creates a commit on the linked branch with your latest changes.
### Pulling from GitHub
Click the **pull** button (down arrow) to fetch the latest changes from GitHub into your Workshop Desktop project. This is useful when collaborators push changes directly to the repository, or when you've made edits in another environment.
## Sync Status Indicators
The GitHub section displays a real-time sync status:
| Status | Meaning |
| - | - |
| **In sync** | Your local project matches the remote repository |
| **Local ahead** | You have unpushed local changes (shows count, e.g., "3 ahead") |
| **Remote ahead** | The remote has changes you haven't pulled (shows count, e.g., "2 behind") |
| **Diverged** | Both local and remote have independent changes that conflict |
## Handling Diverged Histories
When the sync status shows **Diverged**, both your Workshop Desktop project and the GitHub repository have changes the other doesn't. You have two options:
* **Force push** — Overwrites the remote repository with your local state. Workshop prompts for confirmation before proceeding.
* **Force pull** — Overwrites your local project with the remote state. Workshop prompts for confirmation before proceeding.
Force push and force pull are destructive operations. The overwritten changes cannot be recovered. Make sure you know which version you want to keep before confirming.
## Unlinking a Repository
To disconnect a project from its GitHub repository:
1. Click the **three dots** menu in the GitHub section
2. Select **Unlink**
3. Confirm the action
Unlinking does not delete any code — your Workshop Desktop project and the GitHub repository both remain intact. You can re-link the same or a different repository at any time.
## Use Cases
Import a production repository into Workshop Desktop, use the agent to prototype changes or new features, then push back when ready. Great for exploring ideas without switching to a different IDE.
Push regularly to maintain a commit history of your project's evolution. Your Workshop Desktop projects are backed up on GitHub alongside everything else.
One person builds in Workshop Desktop and pushes. Others can pull the latest changes from GitHub into their own Workshop instance, or work directly in their preferred editor and push back.
Since your code lives in GitHub, you can set up GitHub Actions or other CI/CD pipelines to run tests, linting, or deploy to additional environments when changes are pushed.
# Workshop Desktop
Source: https://docs.workshop.ai/workshop-desktop/index
Full-stack development on your machine — any language, any framework, local AI models, and direct file system access.
Workshop Desktop is the locally installed version of Workshop. It runs on your machine, works with your file system, and supports any programming language or framework. There are no stack constraints — if it runs on your computer, Workshop Desktop can build it.
## Key Capabilities
Python, JavaScript, Rust, Go, Swift, C++ — whatever your project needs. Workshop Desktop doesn't limit you to a preset list of languages or frameworks.
Run open-weight models on your own hardware to power the Workshop agent — free, private, and offline. No API costs while building and iterating.
Extend the agent with Model Context Protocol servers — connect to databases, APIs, and custom tools through a standardized interface.
Deploy apps to Workshop's hosting infrastructure with a single click — same as Cloud. Or deploy to your own platform (Vercel, AWS, Docker) if you prefer.
## How It Works
When you open Workshop Desktop, describe what you want to build in plain language. Workshop creates the project structure, writes code, installs dependencies, and runs your application — all on your machine.
Your project files live in a standard directory you choose. You can open them in any editor, run them from any terminal, and use them with any other tool in your workflow.
### Preview while you build
Workshop Desktop includes a live preview pane that shows your running app as it's being built — the same experience as Workshop Cloud. When Workshop detects you're building something visual, the preview opens automatically and stays synced with your latest code.
## Privacy and Security
Your code never leaves your machine. All file operations, code execution, and project management happen locally. When you use cloud AI models (Claude, GPT, Gemini), your prompts go to those providers — but your project files stay local.
With local AI models, even your prompts stay on your machine. Nothing is transmitted anywhere.
## What Makes Desktop Different from Cloud
| | Workshop Cloud | Workshop Desktop |
| - | - | - |
| **Environment** | Runs in the cloud | Installed on your machine |
| **Tech stacks** | Dynamic React App, Static React App, Dynamic HTML App, Streamlit App, Anything | Any language, any framework |
| **File access** | Cloud project files | Full local file system |
| **AI models** | Cloud models | Cloud models + local models |
| **MCP servers** | Not available | Full MCP support |
| **Publishing** | One-click to Workshop hosting | One-click to Workshop hosting, or deploy anywhere |
| **Setup** | Zero — open browser and start | Download and install |
Workshop Cloud is optimized for data apps with a fast build-preview-publish loop. Workshop Desktop is for projects that need full-stack flexibility, local file system access, or local AI models.
## Download Workshop Desktop
Workshop Desktop is available for macOS, Windows, and Linux.
Apple Silicon and Intel supported.
Windows 10 and later.
AppImage and .deb packages.
## Next Steps
Install Workshop Desktop and build your first project.
Power the agent with open-weight models on your own hardware.
Deploy and share your apps.
Extend your agent with Model Context Protocol servers.
Connect your projects to GitHub repositories.
Share conversations and collaborate as a team.
# Running Local AI Models
Source: https://docs.workshop.ai/workshop-desktop/local-models
Power the Workshop agent with local AI models on your own hardware — lower cost, more private, and offline-capable.
Workshop Desktop can use local AI models running on your own machine to power the Workshop agent — the same agent that plans, writes code, and builds your projects.
If you're new to local models, think of this as running inference on-device instead of sending requests to a hosted API.
Workshop supports two paths:
1. **Managed mode (recommended):** Download and run models directly inside Workshop Desktop from **Agent Settings → Local Models**.
2. **Manual mode (advanced):** Connect your own Anthropic Messages API-compatible server (like llama.cpp, LM Studio, or Ollama + adapter).
**Why use local models:**
* **Free** — No API costs while building and iterating
* **Private** — Your prompts, code, and context stay on your machine
* **Offline** — No internet connection required after setup/download
If you prefer cloud models, those work too — just pick from the model selector. Local and cloud models are interchangeable from Workshop's perspective.
Local models power the **Workshop agent** — the assistant you talk to while building. This is separate from [AI Providers](/connectors/managed-ai-connectors), which add AI features to the apps you build.
## Quick Start (Managed Local Models)
In Workshop Desktop, go to **Agent Settings → Local Models**.
Start in the **Guided** tab. Workshop detects your hardware and recommends **Fast**, **Balanced**, and **Genius** options at practical context lengths.
Click a recommendation card to download. Downloads happen in the background with progress indicators.
Once downloaded, click to activate. Workshop automatically starts the local runtime and routes the **Local** model option to your selected model.
Use the model picker to switch between local and cloud models whenever you want.
*Guided view in Agent Settings → Local Models, showing hardware-aware recommendations and context presets.*
The tab also includes:
* **All Models** — browse the full supported model catalog
* **Downloaded** — start/stop active model, re-activate, and delete local model files
*All Models view for browsing the full supported catalog and selecting a specific model family.*
## Advanced: Connect Your Own Local Server
If you prefer to run your own inference server, Workshop can connect to any server that implements the **Anthropic Messages API** (`/v1/messages`).
The most common option is `llama-server` from [llama.cpp](https://github.com/ggml-org/llama.cpp). Other compatible servers include [LM Studio](https://lmstudio.ai/) and [Ollama](https://ollama.com/) (with an Anthropic adapter).
In **Agent Settings → Local Models**, expand **Advanced: Connect your own server**, enter your base URL, and click **Test Connection**.
*Advanced connection panel for attaching Workshop Desktop to an external Anthropic-compatible local server.*
### Starting llama-server
You can ask Workshop itself to help you set it up:
Try these prompts in a Workshop Desktop conversation:
* *"Help me install llama-server and download the Qwen3-Coder-Next Q4\_K\_M GGUF model"*
* *"Set up a local model server on port 8080 for coding"*
* *"Download and run the Step 3.5 Flash Q4\_K\_M model with llama-server"*
Workshop can install llama.cpp, download model files from HuggingFace, and start the server — all within a single conversation.
If you prefer to set it up manually, here's the typical workflow:
```bash theme={null}
# Build llama.cpp (macOS/Linux with Metal/CUDA support)
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build
cmake --build build --config Release
# Download a GGUF model (example: Qwen3-Coder-Next Q4_K_M)
# Get the URL from https://huggingface.co/unsloth/Qwen3-Coder-Next-GGUF
# Start llama-server
./build/bin/llama-server \
-m /path/to/Qwen3-Coder-Next-Q4_K_M.gguf \
--port 8080 \
--ctx-size 32768 \
--temp 1.0 \
--top-p 0.95 \
--top-k 40 \
--min-p 0.01
```
The server is ready when you see output indicating it's listening on port 8080. Workshop connects to it at `http://127.0.0.1:8080`.
***
## Recommended Models
The following three models are well-suited for agentic coding tasks with Workshop Desktop. All are available in GGUF format for local deployment.
Hardware requirements listed below are estimates based on model size, quantization level, and context window. Actual requirements vary by system configuration, other running processes, and llama.cpp version. Always leave headroom beyond the minimum.
### Qwen3-Coder-Next (80B MoE, 3B active)
The top recommendation for local coding. Qwen3-Coder-Next is an 80-billion parameter Mixture-of-Experts model with only **3 billion parameters active per token**. This means it delivers large-model quality at small-model speed. Released February 2026 by Alibaba.
* **Native context window:** 256K tokens
* **Architecture:** MoE with selective activation — only a small fraction of the model processes each token
* **Strengths:** Long-horizon reasoning, complex tool use, recovery from execution failures
| Quantization | Model Size | Min. Memory | Best For |
| - | - | - | - |
| **Q3\_K** (3-bit) | \~30 GB | \~34 GB | Machines with 36–48 GB available memory |
| **Q4\_K\_M** (4-bit) | \~42 GB | \~46 GB | Recommended default — best quality/speed tradeoff |
| **Q8\_0** (8-bit) | \~80 GB | \~85 GB | Maximum quality, requires high-end hardware |
Context window impact on memory (Q4\_K\_M):
| Context Length | Total Memory |
| - | - |
| 4K tokens | \~47 GB |
| 32K tokens | \~48 GB |
| 64K tokens | \~49 GB |
| 256K tokens (full) | \~54 GB |
The MoE architecture keeps KV cache growth minimal — going from 4K to 256K context adds only \~7 GB.
**Performance:** Expect 20+ tokens/second when the model fits entirely on your device. On high-end NVIDIA GPUs (RTX PRO 6000), prompt processing reaches 1,400–2,900 tokens/second with generation at 60–85 tokens/second.
GGUF files are available from [unsloth/Qwen3-Coder-Next-GGUF](https://huggingface.co/unsloth/Qwen3-Coder-Next-GGUF) on HuggingFace. Use the Dynamic GGUF variants from Unsloth for the best quality-per-bit.
### Step 3.5 Flash (196B MoE, 11B active)
A larger model from StepFun with frontier-level coding capability and impressive speed. Step 3.5 Flash has **196 billion total parameters** with **11 billion active per token**, using a sophisticated MoE architecture with 288 experts per layer.
* **Native context window:** 256K tokens
* **Architecture:** 45 transformer layers (3 dense + 42 MoE), hybrid sliding-window/full attention (3:1 ratio), Multi-Token Prediction for faster generation
* **Strengths:** Complex multi-step tasks, high throughput (100–350 tokens/second on server hardware), strong general-purpose coding
| Quantization | Model Size | Min. Memory | Best For |
| - | - | - | - |
| **Q4\_K\_S** (4-bit) | \~105 GB | \~112 GB | 128 GB systems with tight memory budget |
| **Q4\_K\_M** (4-bit) | \~110 GB | \~118 GB | Recommended default on 128 GB+ systems |
| **Q8\_0** (8-bit) | \~200 GB | \~210 GB | Multi-GPU setups or very high RAM systems |
Step 3.5 Flash is a significantly larger model than Qwen3-Coder-Next and requires more memory. It's best suited for machines with 128 GB+ unified memory or multi-GPU configurations.
**Performance:** On consumer hardware with sufficient memory, expect 10–20 tokens/second at Q4 quantization. The model's Multi-Token Prediction architecture can produce bursts of faster throughput depending on the inference engine.
GGUF files are available from [stepfun-ai on HuggingFace](https://huggingface.co/stepfun-ai/Step-3.5-Flash-GGUF-Q4_K_S). Third-party quantizations (including lower-bit options) are also available from community contributors.
### MiniMax M2.5 (230B MoE, \~10B active)
A strong general-purpose model with excellent coding ability and a massive 1M token native context. MiniMax M2.5 has **230 billion total parameters** with approximately **10 billion active per token**.
* **Native context window:** 1M tokens (one of the largest available for local deployment)
* **Architecture:** MoE with lightning attention
* **Strengths:** Very long context windows, broad capability across coding and reasoning tasks
| Quantization | Model Size | Min. Memory | Best For |
| - | - | - | - |
| **UD-Q3\_K\_XL** (3-bit) | \~101 GB | \~110 GB | 128 GB systems; best quality at this memory tier |
| **Q3\_K\_L** (3-bit) | \~110 GB | \~128 GB | 128 GB Apple Silicon (runs without swap) |
| **Q8\_0** (8-bit) | \~243 GB | \~256 GB | Multi-GPU or high-RAM server setups |
**Performance on Apple Silicon:** On an M3 Max with 128 GB unified memory, the Q3\_K\_L quantization runs at \~29 tokens/second for generation and \~99 tokens/second for prompt processing, supporting context windows up to 196K tokens without swap.
Unsloth provides Dynamic GGUF quantizations for MiniMax M2.5 with improved quality-per-bit. Available at [unsloth on HuggingFace](https://huggingface.co/collections/unsloth). Also check [ox-ox/MiniMax-M2.5-GGUF](https://huggingface.co/ox-ox/MiniMax-M2.5-GGUF) for additional quantization options.
***
## Hardware Guide
### Apple Silicon (Unified Memory)
Apple Silicon Macs share memory between the CPU and GPU, making them efficient for running local models. The entire model must fit in unified memory.
| Unified Memory | What You Can Run |
| - | - |
| **32 GB** | Qwen3-Coder-Next Q3\_K only (tight fit, short context). Marginal for agentic coding. |
| **64 GB** | Qwen3-Coder-Next Q4\_K\_M comfortably with 32K context. The recommended entry point for local model coding. |
| **96 GB** | Qwen3-Coder-Next Q8\_0, or Step 3.5 Flash/MiniMax M2.5 at aggressive 2-bit quantization (experimental). |
| **128 GB** | Step 3.5 Flash Q4\_K\_M, MiniMax M2.5 Q3\_K\_L, or Qwen3-Coder-Next Q8\_0 with full 256K context. |
### NVIDIA GPUs
NVIDIA GPUs with CUDA are the fastest option for local inference. The model must fit in VRAM for best performance (partial offloading to system RAM is possible but much slower).
| GPU | VRAM | What Fits |
| - | - | - |
| **RTX 3090 / 4090** | 24 GB | Too small for the recommended models at useful quantization levels. Consider smaller models (7B–14B) for these GPUs. |
| **RTX A6000 / RTX 6000 Ada** | 48 GB | Qwen3-Coder-Next Q4\_K\_M with moderate context. The sweet spot for single-GPU coding agents. |
| **RTX PRO 6000** | 96 GB | Qwen3-Coder-Next at any quantization with full 256K context. Excellent performance. |
| **2x RTX 3090/4090** | 48 GB total | Qwen3-Coder-Next Q4\_K\_M with split-GPU inference. Requires multi-GPU support in llama.cpp. |
### AMD GPUs
AMD GPUs are supported through ROCm. Support has improved significantly but remains less mature than CUDA. If you have an AMD GPU with 24+ GB VRAM, build llama.cpp with ROCm support and follow the same sizing guidelines as NVIDIA GPUs.
### CPU-Only
Running models on CPU alone (system RAM) is possible but slow — expect 1–5 tokens/second depending on the model and quantization. Useful for testing and experimentation but not practical for interactive agentic coding sessions. Apple Silicon is the exception, since its unified memory architecture means "CPU-only" still benefits from the GPU's memory bandwidth.
***
## Approval Mode Recommendation
**Strongly recommended:** Enable **Approval Mode** (Code Execution set to Manual) in Agent Settings when using local models. This requires you to approve each code execution before it runs.
This is especially critical for models outside the three recommended above.
Local models are less reliable than cloud-hosted frontier models at following tool-use contracts and respecting safety boundaries. They may:
* Execute commands you didn't intend
* Misinterpret tool schemas and call tools incorrectly
* Generate code that modifies files or system state unexpectedly
Approval Mode adds a confirmation step before any code runs, giving you the chance to review what the agent wants to execute. You can toggle this in **Agent Settings → Code Execution → Manual**.
For the three recommended models (Qwen3-Coder-Next, Step 3.5 Flash, MiniMax M2.5) at their recommended quantizations, tool-use reliability is generally good. For other models — especially smaller or more aggressively quantized ones — Approval Mode is essential.
***
## Compatible Servers
Workshop Desktop connects to any server that exposes an Anthropic Messages API-compatible endpoint at `/v1/messages`. The following servers are known to work:
| Server | Notes |
| - | - |
| **[llama-server](https://github.com/ggml-org/llama.cpp)** (llama.cpp) | Native Anthropic Messages API support. Recommended. Supports streaming, tool use, and vision. |
| **[LM Studio](https://lmstudio.ai/)** | GUI application for running local models. Check documentation for Anthropic API compatibility settings. |
| **[Ollama](https://ollama.com/)** | Requires an Anthropic adapter (e.g., [local-openai2anthropic](https://pypi.org/project/local-openai2anthropic/)) since Ollama natively serves an OpenAI-compatible API. |
| **[vLLM](https://docs.vllm.ai/)** | High-throughput inference engine with Anthropic endpoint support. Better suited for server-class hardware. |
***
## Ecosystem and Resources
The local model ecosystem is evolving rapidly. New models with better quality at smaller sizes are released frequently. If the recommended models above don't fit your hardware, check back — options for 16 GB and 32 GB machines improve with each new model release.
**Useful links:**
* [Unsloth Documentation — Local Models](https://unsloth.ai/docs/) — Guides for running Qwen3, MiniMax, and other models locally with optimized quantizations
* [llama.cpp — Anthropic Messages API](https://huggingface.co/blog/ggml-org/anthropic-messages-api-in-llamacpp) — Setup guide for llama-server with Anthropic API support
* [HuggingFace GGUF Models](https://huggingface.co/models?library=gguf\&sort=trending) — Browse trending GGUF models available for download
* [LM Studio](https://lmstudio.ai/) — GUI-based model runner with model discovery and download built in
* [Unsloth Tool Calling Guide](https://unsloth.ai/docs/basics/inference-and-deployment/tool-calling) — Guide for tool calling with local models (relevant for agentic use)
***
## Troubleshooting
The local model server isn't running, or it's on a different port than the URL you entered. Verify the server is started and check the port number.
The server is running but doesn't have an Anthropic Messages API endpoint at `/v1/messages`. This usually means the server uses an OpenAI-compatible API instead. Use an adapter like `local-openai2anthropic`, or switch to llama-server which has native support.
The model likely doesn't fit entirely in your GPU VRAM or unified memory, causing parts to be offloaded to system RAM. Try a more aggressive quantization (e.g., Q3\_K instead of Q4\_K\_M) or reduce the context window with the `--ctx-size` flag.
Check your sampling parameters. The recommended settings for coding models are: `temperature=1.0`, `top_p=0.95`, `top_k=40`, `min_p=0.01`. Also verify you're using a model intended for instruction following, not a base (pre-trained) model.
The model plus context window exceeds your available memory. Reduce `--ctx-size` (e.g., from 32768 to 8192) or use a smaller quantization. On macOS, check Activity Monitor to see actual memory pressure.
# MCP Server Configuration
Source: https://docs.workshop.ai/workshop-desktop/mcp-servers
Extend Workshop Desktop with Model Context Protocol servers for databases, APIs, and custom tools.
Model Context Protocol (MCP) servers let you give Workshop's agent access to external tools and data sources — databases, APIs, file systems, and custom integrations — through a standardized interface. MCP is an open protocol that defines how AI agents communicate with tool servers.
MCP is a **Workshop Desktop-only feature**. It requires the local backend to manage server processes and connections.
## What MCP Servers Do
When you connect an MCP server, its tools become available to the Workshop agent during conversations. For example:
* A **database MCP server** lets the agent query your PostgreSQL or SQLite database directly
* A **filesystem MCP server** gives access to files outside the project directory
* A **web search MCP server** lets the agent search the internet during conversations
* A **custom MCP server** can expose any API or service you build
The agent sees available tools and calls them when relevant to your request — no manual invocation needed.
## Adding MCP Servers
Workshop Desktop provides three ways to add MCP servers. Open **Settings** and navigate to the **MCP Servers** tab to get started.
### Server Directory
The **Server Directory** tab lists popular, pre-configured MCP servers that you can install with one click.
Open Settings, go to the MCP Servers tab, and click **Server Directory**.
Find the server you want and click **Install**. Workshop handles downloading the package and configuring the connection.
Some servers require setup values (API keys, database URLs, etc.). Workshop prompts you to provide these during installation.
### Custom Server
The **Add Custom Server** tab lets you manually configure any MCP server by specifying its runtime command and arguments.
In the MCP Servers settings, click **Add Custom Server**.
Provide:
* **Server name** — A display name for the server
* **Runtime** — The command to run the server (e.g., `npx`, `uvx`, `node`, `python`)
* **Arguments** — Command-line arguments for the server process
* **Environment variables** — Any environment variables the server needs (API keys, config values)
Click **Add Server**. Workshop starts the server process and validates the connection. The server appears in your **Configured Servers** list.
### Deep Links
Third-party websites and documentation can provide deep links that automatically configure an MCP server in Workshop Desktop. When you click a deep link, Workshop opens with the server configuration pre-populated — you just confirm the installation.
Deep links use the format:
```
workshop://deeplink/v1/mcp/install?config=&name=
```
Deep links only work when Workshop Desktop is installed. They use the `workshop://` protocol handler registered by the desktop app.
## Managing Configured Servers
The **Configured Servers** tab shows all MCP servers you've added.
### Enabling and Disabling Servers
Each server has an enable/disable toggle. Disabling a server stops its process and removes its tools from the agent's available tools — but keeps the configuration saved so you can re-enable it later.
When you enable a server, Workshop starts the server process and waits for initialization. The status indicator shows:
| Status | Meaning |
| - | - |
| **Pending** | Server is starting up |
| **Connected** | Server is running and tools are available |
| **Error** | Server failed to start (expand for error details) |
### Enabling and Disabling Individual Tools
Expand a server to see its available tools. Each tool has its own toggle — disable specific tools you don't want the agent to use while keeping the server running.
This is useful when a server exposes many tools but you only need a few, or when you want to prevent the agent from using a particular tool during a conversation.
### Connection Monitoring
Workshop Desktop polls MCP servers periodically to verify they're still running and responsive. If a server becomes unresponsive, the status updates automatically. You can also manually refresh the status from the three-dots menu.
## Configuration Storage
MCP server configurations are stored in a `mcp.json` file within your Workshop Desktop data directory. You can edit this file directly if you prefer, then use **Reload Configuration** in the settings to pick up changes.
## Troubleshooting
Expand the server entry to see the error message. Common issues:
* **Runtime not found** — The command (e.g., `npx`, `uvx`) isn't installed or not in your PATH. Install the required runtime and try again.
* **Connection refused** — The server process started but crashed. Check the error message for details.
* **Authentication failed** — The server requires credentials. Update the environment variables in the server configuration.
Make sure the server is enabled (toggle is on) and the status shows **Connected**. If individual tools are disabled, they won't appear even when the server is connected.
Deep links require Workshop Desktop to be installed and the `workshop://` protocol handler to be registered. Try reinstalling Workshop Desktop if deep links aren't being recognized by your OS.
# Publishing
Source: https://docs.workshop.ai/workshop-desktop/publishing
Deploy Workshop Desktop apps to a shareable URL with one click, or to any platform you choose.
Workshop Desktop supports the same one-click publishing as Workshop Cloud. When you're ready to share your app, Workshop handles hosting and compute — nothing to provision, no server to manage.
## One-Click Publish to Workshop
Click **Publish** in the top-right corner of the interface. Workshop packages your project, injects secrets and connector credentials, and deploys to Workshop's hosting infrastructure. Your app gets a public URL you can share immediately.
Click the **Publish** button in the Workshop Desktop interface. A popover opens showing your deployment settings and the URL your app will be available at.
Choose who can access your published app:
* **Public** — Anyone with the URL can use your app. No sign-in required.
* **Private** — Only people you explicitly invite by email can access it. Requires a paid plan.
Click **Publish** in the popover. Workshop validates that all secrets and connectors your code references are included, packages your project files, injects credentials, and deploys to hosting infrastructure. If any resources are missing, you'll be prompted to fix the issue before deploying (see [Resource Validation](/workshop-cloud/publishing#resource-validation)).
Once deployed, copy the shareable URL and send it to anyone. They can use your app immediately — no install, no setup on their end.
## App URLs
Every published app gets a unique URL based on your project's **slug**:
```
https://{your-project-slug}.workshop.build
```
On a paid plan (Build, Scale, or Max), you can rename the slug to something more meaningful. Rename while the app is stopped — stop it first, rename, then republish.
## Custom Domains
On any paid plan — **Build**, **Scale**, or **Max** — you can serve your published app from your own domain (e.g. `app.yourcompany.com`) instead of the default `workshop.build` URL. You'll need a domain you already own and access to its DNS settings — Workshop doesn't register domains on your behalf.
Open the Publish popover on a deployed app, click **Add custom domain**, enter your hostname, then add a CNAME record at your registrar or DNS provider pointing it to `origin.workshop.build`:
```
CNAME app.yourcompany.com → origin.workshop.build
```
Once the CNAME propagates, Workshop verifies it and provisions the SSL certificate automatically. The Custom Domain section shows **Pending** until verification completes, then flips to **Active**. One custom domain per app; the default `{slug}.workshop.build` URL stays live alongside it.
For the full walkthrough, troubleshooting, and limits, see [Custom Domains in Workshop Cloud publishing](/workshop-cloud/publishing#custom-domains) — the flow is identical for desktop-published apps.
## Redirects and Custom Status Codes
By default, published apps answer every URL with your app shell and a `200` "success" status — great for client-side routing, but a problem for search engines: when a page moves or is removed, crawlers keep seeing "this page exists," so a moved page never passes its search ranking to its new address and a deleted page stays in search results. Getting this right is a core part of SEO (search engine optimization) — see [Google's guidance on redirects](https://developers.google.com/search/docs/crawling-indexing/301-redirects).
To return real HTTP status codes on specific URLs, add a `public/_redirects` file to your project and republish. It uses the same `_redirects` format as [Netlify](https://docs.netlify.com/manage/routing/redirects/redirect-options/) and [Cloudflare Pages](https://developers.cloudflare.com/pages/configuration/redirects/) — Workshop supports a compatible subset (the rules below), so files that stick to these features carry over unchanged, and anything outside the subset fails the publish with a clear error rather than behaving differently:
```
# source destination status
/old-pricing /pricing 301
/discontinued /gone.html 410
/app/* /index.html 200
/* /404.html 404
```
Each line is `source destination status`, whitespace-separated; `#` starts a comment and the status defaults to `301` when omitted.
* **`301` / `302`** redirect the browser (and search engines) to the destination — a path on your app or a full `https://` URL. The request's query string is passed through unless the destination declares its own.
* **`410` / `404`** serve the destination file's *content* with that status code, so you can ship your own not-found page (e.g. `public/404.html`) and search engines de-index removed pages properly.
* **`200`** serves the destination in place of the requested URL (a rewrite) — use it to keep client-side routes working ahead of a `/*` catch-all.
Rules are checked top to bottom and the **first match wins**, so list your app's real routes as `200` rewrites *before* a `/*` catch-all. Sources are exact paths or a trailing `/*` wildcard. A real file at the requested URL always wins over a rule — append `!` to the status (e.g. `301!`) to force the rule instead.
Plain HTML projects published as-is (no build step) should place `_redirects` at the project root — and the same goes for any files your rules serve, like `404.html`: the project root is the publish directory, so a rule target `/404.html` means a root-level `404.html`, not `public/404.html`.
If the file contains something unsupported, publishing fails with an error naming the line, so a typo can never silently change your live routing. Removing the file (and republishing) restores the default behavior. On apps with a Python backend, note that `/api/*` always goes to your backend — rules apply to everything else.
## Search Engines and AI Crawlers
Your app's `robots.txt` is served exactly as written. Workshop and its hosting layer add nothing to it, so the file in your project is the whole policy.
Projects created from the Dynamic React App and Static React App templates ship a `public/robots.txt`; the Dynamic HTML App template ships it at `static/robots.txt`. The default allows regular search engines and blocks the common AI training crawlers (GPTBot, ClaudeBot, Google-Extended, CCBot, and others). To change that, edit the file, or ask the agent to, and republish. Deleting the file makes the app fully open to all crawlers.
Apps published from a project without a `robots.txt` return a 404 for it, which crawlers treat as no restrictions. Add the file at the path above and republish to set a policy.
## Public vs Private Apps
### Public Apps
Anyone with the URL can access the app. No sign-in required. Available on all plans.
### Private Apps
Only people you invite by email can access it. Visitors who aren't invited see an "Access Restricted" page. Private apps require a paid plan.
| Feature | Discover (Free) | Build | Scale | Max |
| - | - | - | - | - |
| Public apps | Unlimited | Unlimited | Unlimited | Unlimited |
| Private apps | Not available | 1 | Unlimited | Unlimited |
| Invited viewers (per private app) | N/A | 5 | Unlimited | Unlimited |
| Custom slug rename | No | Yes | Yes | Yes |
| Custom domains | No | Yes | Yes | Yes |
| Hide branding | No | Yes | Yes | Yes |
## Updating a Published App
After making changes to your project, click **Update** in the Publish popover to push the latest version. The URL stays the same — visitors see the new version once the update completes.
## Stopping a Published App
Open the Publish popover and click **Stop**. Stopped apps show a friendly "App Temporarily Unavailable" page instead of a technical error. You can republish at any time.
## Deploying to External Platforms
Because Workshop Desktop projects are standard files on your local machine, you can also deploy to any external platform — Vercel, AWS, Railway, Fly.io, your own server, or anywhere else.
This is entirely optional. If Workshop's built-in hosting meets your needs, there's no reason to set up external infrastructure. External deployment makes sense when you need:
* Custom domains on your own infrastructure
* Integration with an existing CI/CD pipeline
* Compliance requirements around where your app runs
* A platform you're already using for other services
For external deployment, ask Workshop directly — describe your target platform and it will configure the deployment for you.
```
Deploy this app to Vercel and set up a custom domain.
```
```
Set up a GitHub Actions pipeline that deploys to AWS on push to main.
```
```
Dockerize this app and write a docker-compose file for self-hosting.
```
## Sharing and Access Control
Published apps support granular access control — share publicly or limit to specific people. For team-level sharing and managing access across your organization, see [Sharing and Teams](/workshop-desktop/sharing-and-teams).
# Sharing and Teams
Source: https://docs.workshop.ai/workshop-desktop/sharing-and-teams
Share conversations with links and collaborate with your team through shared credits and centralized billing.
Workshop Desktop supports the same sharing and team features as Workshop Cloud — share conversations via link, publish apps with access control, and manage team billing and credits on a Scale or Max plan.
## Sharing Conversations
You can share any conversation via a private link — useful for showing someone a working prototype, demonstrating a concept, or getting support.
### How to Share
Sharing always applies to the conversation you currently have open, so open it first.
Open the project that contains the conversation you want to share.
In the **Conversations** panel, click the conversation. It becomes the current conversation.
Click the project name with the caret (⌄) in the top-left of the window to expand the menu. The menu shows the current conversation name at the top.
Under the **CONVERSATION** section, click **Share**.
In the **Share Conversation Privately** dialog, click **Share**. Workshop creates a private link — anyone with the link can view the conversation, but it won't appear in search or public indexes.
Click **Copy link and close** (or the copy icon next to the URL) and send the link to your audience.
The link looks like `https://threads.workshop.ai/c/` and renders your conversation in a clean, readable format so recipients experience it just as you did.
**Share** is disabled until the conversation has at least one message.
### Before Sharing
* Check for accidentally included secrets, credentials, or API keys
* Confirm that any internal data is appropriate to share externally
* Open the link in a private browser window to verify it renders correctly
## Sharing Published Apps
When you publish an app from Workshop Desktop, you control who can access it:
* **Public** — Anyone with the URL. No sign-in required.
* **Private** — Only people you invite by email. Requires a paid plan.
If your project is linked to a **team subscription** (Scale or Max plan), you can use the **Team sharing** toggle in the Publish popover to grant access to all team members at once — no individual invitations needed.
For full details on publishing mechanics, see [Publishing](/workshop-desktop/publishing).
## Team Management
Teams let you collaborate with shared credit pools, centralized billing, and organization-wide settings.
Team management features require a **Scale** or **Max** plan subscription.
### What Teams Include
* **Shared credit pool** — All team members draw from a common credit allocation
* **Centralized billing** — A single subscription covers all team members
* **Privacy controls** — Enforce privacy mode across all team members
* **Credit Pack bonuses** — 10% more credits on Scale; the largest discount on Max
* **Dedicated support** — Priority support through shared team channels
### Setting Up a Team
Team features are available on the Scale and Max plans. Upgrade from your account settings.
Set your team name, default member credit limits, and privacy enforcement preferences.
Go to your team management dashboard, click **Invite Team Member**, and enter their email. You can optionally set individual credit limits.
Invited users receive an email with a link to join. Once they accept, they inherit team privacy settings and their credit limits take effect immediately.
### Member Roles
| Role | Capabilities |
| - | - |
| **Team Owner** | Full admin control: billing, invitations, member management, privacy enforcement, credit limit adjustments |
| **Team Member** | Access to shared credits, subject to team policies and individual credit limits |
### Seat Management
Both active team members and pending invitations count toward your seat limit. Free up capacity by removing a member, revoking a pending invitation, or upgrading your subscription.
Pending invitations reserve a seat until accepted, revoked, or expired (after 30 days).
## Team Credit Management
* All team members draw from a **shared credit pool** set by the team owner's subscription
* Team owners can set **individual credit limits** per member (default: 1,000 credits)
* Members cannot exceed their individual limit even if team credits remain
* Credit Pack purchases receive a **10% bonus** for team accounts
Team owners have real-time visibility into team-wide and per-member credit usage from the team management dashboard.
## Privacy and Security
Team owners can **enforce privacy mode** for all members — ensuring conversations are never stored externally across your entire organization. Individual members cannot override this setting.
## Plan Comparison
| Feature | Discover (Free) | Build | Scale | Max |
| - | - | - | - | - |
| Share conversations via link | Yes | Yes | Yes | Yes |
| Published app viewers | Public only | 5 per private app | Unlimited | Unlimited |
| Team management | No | No | Yes | Yes |
| Shared credit pool | No | No | Yes | Yes |
| Privacy enforcement | No | No | Yes | Yes |
| Credit Pack bonus | No | No | 10% | Max discount |
| Remove Workshop badge | No | Yes | Yes | Yes |
## Getting Help
* **Email:** [help@workshop.ai](mailto:help@workshop.ai)
* **Community:** [Discord](https://discord.gg/ggqJkUN3vx)
* Scale and Max plan teams have access to **priority support** channels