Team collaboration for Vercel Hobby — self-hosted, open source, zero ToS conflict.
Vercel's Hobby plan is genuinely great. But it's strictly personal: no team members, no shared deployment dashboard, no audit trail. Upgrading to Pro costs $20/month per person.
Matrioshka is a thin collaboration layer that sits on top of your existing Vercel Hobby account. One person owns the account. Everyone else gets a clean dashboard to monitor projects, trigger deploys, and track activity — without touching Vercel's infrastructure or violating their terms.
Your team ──► Matrioshka ──► Vercel API ──► your Vercel Hobby account
Matrioshka uses your Vercel API token to proxy read operations (project list, deployment status) and deploy hooks to trigger deploys. It adds its own auth layer on top, so you control who sees what. Nothing runs inside Vercel — Matrioshka lives on any $5/month VPS.
- Project dashboard — live deployment status for all your Vercel projects, with one-click redeploy via deploy hooks
- Team members — invite collaborators by email with role-based access (admin / member / viewer)
- Audit log — full record of who triggered what and when
- Setup wizard — connect your Vercel token and create the admin account in two steps
- Self-hosted — your data never leaves your infrastructure
- Docker-first — single
docker compose upto run
Requirements: Docker, a Vercel API token, a server or local machine.
# 1. Clone
git clone https://github.com/your-org/Matrioshka
cd Matrioshka
# 2. Configure
cp .env.example .env
# Edit .env — set BETTER_AUTH_SECRET to a long random string
# 3. Run
docker compose up -d
# 4. Open http://localhost:3000
# The setup wizard connects your Vercel token and creates the admin account.Generate a Vercel API token at vercel.com/account/tokens. Use a full-access token scoped to your personal account.
- Go to Members in the sidebar
- Enter their email and choose a role
- Copy the invite link and send it
- They click the link, set a password, and get access
Invite links expire after 7 days. You can revoke them at any time.
| Role | View projects | Trigger deploys | Manage members |
|---|---|---|---|
| Admin | ✓ | ✓ | ✓ |
| Member | ✓ | ✓ | — |
| Viewer | ✓ | — | — |
To enable one-click deploys from Matrioshka, configure a deploy hook for each project in Vercel:
- Go to your project in Vercel → Settings → Git → Deploy Hooks
- Create a hook (name it anything, select the branch)
- In Matrioshka, go to the project and paste the hook URL
Without a deploy hook, the project is read-only (status is still visible).
| Variable | Required | Description |
|---|---|---|
BETTER_AUTH_SECRET |
Yes | Random secret for session signing (min 32 chars) |
BETTER_AUTH_URL |
Yes | Public URL of your Matrioshka instance |
NEXT_PUBLIC_APP_URL |
Yes | Same as above (used client-side for invite links) |
DATABASE_PATH |
No | Path to the SQLite file (default: ./data/matrioshka.db) |
Generate a secret:
openssl rand -base64 32The Docker image is published to GitHub Container Registry on every release:
docker pull ghcr.io/your-org/Matrioshka:latestOr pin to a specific version:
docker pull ghcr.io/your-org/Matrioshka:0.1.0The docker-compose.yml mounts a named volume at /app/data for the SQLite database. Backing up Matrioshka is as simple as copying that file.
# Install dependencies
npm install
# Push the database schema
npm run db:push
# Start dev server
npm run devCopy .env.example to .env.local and fill in the values before running.
Stack:
- Next.js 16 — framework
- Drizzle ORM + SQLite — database
- better-auth — authentication
- Framer Motion — animations
- Phosphor Icons — icons
- Tailwind CSS v4 — styles
Matrioshka uses Changesets for versioning.
# After making changes, describe what changed:
npm run changeset
# Choose the bump type:
# patch — bug fixes, minor tweaks
# minor — new features, backwards-compatible
# major — breaking changes
# Commit the generated .changeset file with your PR.When changeset files land on main, CI opens a "Version Packages" PR automatically. Merging it bumps the version, updates CHANGELOG.md, and publishes a new Docker image to GHCR.
Steps to contribute:
- Fork the repo
- Create a branch:
git checkout -b feat/your-feature - Make your changes
- Run
npm run changesetand commit the generated file - Open a PR against
main
src/
├── app/
│ ├── (app)/ # Authenticated routes (sidebar layout)
│ │ ├── projects/ # Project list + deploy
│ │ ├── members/ # Team management + invites
│ │ └── activity/ # Audit log
│ ├── api/
│ │ ├── auth/ # better-auth handler
│ │ ├── projects/ # Vercel API proxy
│ │ ├── invites/ # Invite CRUD
│ │ ├── members/ # Member list
│ │ └── activity/ # Audit log entries
│ ├── invite/[token]/ # Public invite acceptance page
│ ├── setup/ # First-run wizard
│ └── login/
├── components/
│ ├── layout/ # Sidebar navigation
│ ├── projects/ # Project list
│ ├── members/ # Members panel + invite form
│ └── activity/ # Activity feed
└── lib/
├── auth.ts # better-auth configuration
├── db/ # Drizzle schema + SQLite client
├── vercel.ts # Vercel REST API client
└── setup.ts # First-run detection
Does this violate Vercel's ToS? No. Matrioshka is a self-hosted tool that calls Vercel's public API with your own token. It doesn't circumvent rate limits or resource caps. What you deploy on Vercel is your responsibility — Matrioshka only changes who can see and trigger it.
Can I connect multiple Vercel accounts? Not in v0.1. One Vercel account per Matrioshka instance. Multi-account support is planned.
Where is data stored?
A single SQLite file at data/matrioshka.db. The Vercel API token is stored there — secure your server and restrict access to the volume.
Can members see the Vercel API token? No. The token is server-side only. Members interact with Matrioshka's API, which proxies requests to Vercel without exposing credentials.
What if the Vercel API is down? The dashboard won't load project data. Deploy hooks go directly to Vercel's infrastructure, so they may still work independently.
MIT