Hey folks and @insiders,
We’ve seen a recurring theme of confusion when working with newly created Speckle projects, particularly around the mysterious main model. This is our fault, not anyone else’s.
Let’s clear the fog.
The Backstory
Historically, Speckle v2 connectors pushed data into a model called main by default. People naturally assumed that:
Every project has a
mainbranch, just like Git.
But here’s the truth:
There is no main.
… there is, but it’s not what you think.
- When a new project is created:
- A default model is technically created, but…
- It has no name (
"") and won’t show up inGetModels()unless data is pushed to it. - If you try to create a model named
main, you might get an error, because this ghost model is already there.
This legacy behavior exists to support older workflows, but it’s no longer the recommended path.
The V3 Philosophy: Define Your Trunk
With modern Speckle (v3+), we’ve moved away from implied conventions. You should now:
- Explicitly create models with meaningful names (
design,baseline,coordination, etc.). - Push data to those models instead of assuming
mainexists or is usable. - Treat models as intentional containers for structured data — not branches or guessable defaults.
What You Should Do (Best Practice)
When creating a project:
- Use the API or UI to create a model explicitly.
- Push data to that model — don’t rely on
main. - If you’re inheriting older data:
- Look for a model with an empty name — that’s your ghost
main.
TL;DR
There is no
main.
Define your trunk. Use models intentionally.
And don’t let legacy ghosts haunt your pipeline
Also, I need to add a short note in the docs to make this official and easier to find.
In the meantime, feel free to reply if you’re running into related issues or want help updating your workflows.
— Jonathon @ Speckle