Talk to your Laravel project. Approve what ships.

1. The domain. You type it, for example dev.example.com. The script shows the one DNS record to create: *.dev.example.com → A → your server's IP.
2. The check. It resolves a random name under the wildcard and studio.<domain> through a public resolver and waits until both point at the server. You can skip and fix DNS later; certificates are issued on demand when hosts resolve.
3. The first administrator. Name and email. The password is generated: the summary shows it, with the dashboard's address and the email, in a yellow box before anything is installed, and again at the end. Save it then; nothing shows it later. Studio has no public sign-up and no social login: accounts are created here and in the dashboard, and people sign in with a password.
4. The git provider. GitHub, GitLab (gitlab.com or your own), Bitbucket Cloud or Azure DevOps (with its organization): one for the whole Studio, the same forges Larapilot integrates with. See The git provider.
5. Your token there. With the instructions on screen you create it; the script verifies it with the provider and stores it for your account. It clones and deploys project sites and creates new repositories. Every other person adds their own later.

Then it installs the newest release of Studio, the latest published vX.Y.Z tag (the head of the main branch only while no release is published; the first release then replaces it), with what it needs: Caddy, PHP 8.3, 8.4 and 8.5 (8.5 alone on Ubuntu 26.04, see below), Composer, Node, Claude Code, the provider's CLI (gh, glab or the Azure CLI), MariaDB, PostgreSQL and redis. Ten minutes later:

Sign in, turn on two-factor authentication, add your Claude credential in Settings → Connections, create the first project in Administration → Projects, invite the team. From then on Studio updates itself every night to the newest release; see Updates.

Requires: Ubuntu 24.04 or 26.04 LTS (with sudo or Ubuntu 26.04's sudo-rs), amd64 or arm64, 4 GB of memory or more · a domain with a wildcard record · an account per person on the git provider · a Claude subscription or an Anthropic API key per person who chats · Laravel projects with Larapilot (Studio installs it, with Laravel Boost, in the repositories it creates).

What it installs

installer/install.sh turns a bare Ubuntu into the whole thing, and the same steps (in installer/lib/system.sh) run again at every update, so a release can bring what it needs. What apt prints goes to /var/log/studio-install.log; when a package fails, the installer shows the end of it. Run on a server where Studio is installed, the script starts the updater instead of asking questions; after an installation that stopped halfway it starts again from the questions. Beta testers install the head of the main branch instead of the newest release, and keep following it (see Updates):

Where things land

DNS and certificates

One wildcard record is enough: *.<domain> → the server. When a browser asks for maria-shop.<domain> for the first time, Caddy calls http://127.0.0.1:8081/api/tls/ask?domain=…; Studio answers 200 for its own host, a project slug or a workspace preview it knows, 404 for anything else, and Caddy issues the certificate. A host nobody created is never issued a certificate, which also keeps the rate limits quiet.

Where things live

When the story is reviewed and merged on the deploy branch, the git provider calls Studio's webhook and the project site at shop-acme.<domain> pulls, builds and migrates. The Board reflects it at the next refresh.

What happened underneath

Presets map to Claude Code's --permission-mode and are set per role in config/studio.php. A conversation starts with its role's preset; Model & mode switches it among the modes the role may use (all four for administrators, PMs and developers). Custom skills the repository ships become buttons for everyone who can chat; see Buttons & custom skills.

The installer asks for the provider, the address of a self-managed GitLab or the Azure DevOps organization, checks the administrator's token there and installs the provider's CLI. In every workspace the person's token is in the environment three ways: for git, through the askpass helper and with the user name the provider expects (x-access-token, oauth2, x-bitbucket-api-token-auth); for the CLI; and for Larapilot's integration. A repository Studio creates gets that integration turned on in its first commit (larapilot:settings-set --gitlab=YES and so on); in an existing repository the team turns it on once and commits .larapilot/config.yaml.

GitHub

Organizations. A new repository goes to your account or to an organization you belong to; the form lists the organizations your token can see, and creating a repository there needs the right to do so in that organization. Organizations that restrict fine-grained tokens approve them in Organization settings → Personal access tokens. With SAML single sign-on, a classic token must be authorized for the organization (Configure SSO next to the token).

1. Where. GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.
2. Resource owner. The organization that owns the projects, or your account. A fine-grained token reaches one owner: when projects live in several organizations, use a classic token with repo, read:org and admin:repo_hook.
3. Repository access. The repositories of the projects, or all of them; administrators who create repositories need all of them.
4. Permissions, everyone. Contents read and write, Pull requests read and write, Metadata read.
5. Permissions, administrators. Also Administration read and write (new repositories) and Webhooks read and write (the deploy webhook).

GitLab

Groups. A new repository goes to your personal namespace or to a group or subgroup where you are at least Developer and the group lets that role create projects; the form lists those groups by their full path. A self-managed GitLab is set once, in the installer (STUDIO_GIT_URL=https://git.example.com), and the agent's glab gets it as GITLAB_HOST. Registering the deploy webhook needs the Maintainer role on the repository.

1. Where. On your GitLab: avatar → Edit profile → Access tokens → Add new token.
2. Scope. api: clone and push, merge requests through glab and Larapilot, and for administrators the new repositories and the webhook. read_repository and write_repository alone let git work, not merge requests.
3. Expiration. GitLab asks for a date. Replace the token in Studio before it expires.
4. Copy it into Settings → Connections. It starts with glpat-.

Bitbucket Cloud

Workspaces and projects. A Bitbucket repository belongs to a workspace and to one of its projects. The form lists the workspaces you belong to and their projects: a workspace alone puts the repository in its oldest project, a project puts it there. Creating repositories needs a workspace role that allows it; registering the webhook needs admin rights on the repository.

1. Where. id.atlassian.com → Account settings → Security → Create and manage API tokens → Create API token with scopes → Bitbucket. API tokens replace app passwords: git signs in with the token as x-bitbucket-api-token-auth, the REST API with the token as a bearer.
2. Scopes, everyone. read:user, read:workspace, read:repository, write:repository, read:pullrequest, write:pullrequest (each ends in :bitbucket).
3. Scopes, administrators. Also read:project, admin:repository (new repositories), read:webhook, write:webhook and delete:webhook (the deploy webhook).
4. Expiration. Up to a year. Replace the token in Studio before it expires.

Azure DevOps

Organization and projects. One Studio works with one Azure DevOps organization, set in the installer (STUDIO_GIT_URL=https://dev.azure.com/acme; acme.visualstudio.com addresses work too). Repositories live in the organization's projects: the form lists them, and a new repository follows the visibility of its project. Addresses of another organization are refused. Creating repositories needs the Create repository permission on the project; registering the push service hook needs Project Administrator.

1. Where. https://dev.azure.com/<organization> → User settings → Personal access tokens → New Token.
2. Organization. This Studio's, or all accessible organizations.
3. Scopes, everyone. Custom defined → Code → Read & write.
4. Scopes, administrators. Code → Read, write & manage, and Project and Team → Read.
5. Expiration. At most a year, or less when the organization's policy says so.

The login on Azure DevOps is the account's e-mail address; the handle is its first part (maria.rossi@acme.com → maria-rossi).

Or let Studio create the repository

Where a new repository can go depends on the provider: your account or one of your organizations on GitHub, your namespace or a group on GitLab, a workspace or one of its projects on Bitbucket, a project of the organization on Azure DevOps. Your token needs the right to create repositories there; the scopes are in The git provider. What lands in the new repository: composer create-project laravel/laravel at its current release; laravel/boost and andreapollastri/larapilot as dev dependencies, with larapilot:install and boost:install run (Boost is always there: if its install fails, the project stops with the reason instead of going on without it); Larapilot's integration for the provider turned on in .larapilot/config.yaml; and one commit on the deploy branch (plus main when the deploy branch is another name).

What an existing repository must have

• Larapilot installed and larapilot:install run, so the skills, the .larapilot/ workspace, the dashboard and the API exist; Larapilot brings Laravel Boost with it, and boost:install gives the agent Boost's guidelines and MCP server. Without Larapilot the site still deploys, but there is no Board and the chat has no skills to call.
• A .env.example. The server copies it and sets the application URL, the database, redis and the Larapilot API token; everything else you put there is kept.
• Optionally a .mcp.json at the root for MCP servers every workspace should have, with secrets as ${ENV} references, and custom skills under .larapilot/skills/.

1. Create the account. Name, email, role. Studio shows a one-time initial password; share it once, it is never shown again.
2. They sign in with email and password, change it, and turn on two-factor in Settings → Security: an authenticator app or a passkey.
3. They connect the git provider and Claude in Settings → Connections. Until both are there, a project opens on a page that says so instead of a chat.
4. They open a project. Studio shows the projects they are members of. The first open builds the workspace.

The git provider

A personal token on the provider of this Studio, with the scopes in The git provider. Studio verifies it there, reads the login, and uses it as the person's handle: their previews are <login>-<project>.<domain>, their Linux user on the server is ws-<login> (on Azure DevOps the login is the e-mail address, and the handle its first part). Inside the workspace git pushes and the provider's CLI opens pull requests as that person. The token never sits in a file git can read: an askpass helper hands it to git from the environment, with the user name the provider expects.

Claude

Either a subscription or an API key. With Claude Pro or Max: on your own computer, signed in to Claude Code, run claude setup-token and paste the long-lived token. With an Anthropic Console account: paste the API key. The workspace exports CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY accordingly, and Claude Code's login files live in that person's home on the server, denied to the agent itself.

1. Creation. When the project is saved, the helper creates a Linux user, clones the deploy branch with the administrator's token, creates the database, writes the .env with APP_ENV=staging and a fresh LARAPILOT_API_TOKEN, runs Composer (dev dependencies included: the site is a staging environment, and Larapilot and Boost are dev dependencies whose dashboard and API it serves), npm, migrations, a PHP-FPM pool, a Caddy host and a queue worker. Studio registers a push webhook on the repository.
2. Every push to the deploy branch reaches /api/git/webhook/<slug> with the project's secret: an HMAC signature from GitHub and Bitbucket, the secret token in a header from GitLab and Azure DevOps. Studio queues a deploy: fetch, reset to the branch, build, migrate, restart the worker. Deploy in the admin page does the same by hand.
3. The Board reads https://<slug>.<domain>/larapilot/api/specs with the token the helper generated. The PM's bookmark is /larapilot on that host.
4. New workspaces copy the site's database (a dump and a restore, MariaDB or PostgreSQL), so a person starts from realistic data. Without a site database, migrations run instead.

Deploys are a reset to the branch and a rebuild in place, not atomic releases: a failed migration leaves the site on the previous code, a failed build may leave it mid-way for a moment. It is a staging site, kept simple on purpose. For production use the pipeline your project already has.

Server features

Who can open the hosts

Each project has a rule for its site and one for its previews, plus overrides for single branches. A rule is a mode and an IP whitelist:

How it works: when a project has any rule, its hosts get a Caddy forward_auth to Studio's /api/site-auth, which answers 204 (go on), a redirect, or 403. Hosts without rules are served directly, with no extra hop.

Studio's own session cookie never reaches a project host: the apps there run code the team writes, and must not see a cookie that opens Studio. A visitor without a pass is sent to studio.<domain>, logs in there if needed, and comes back with a one-time token valid for two minutes. The gatekeeper swaps it for a pass cookie bound to that host alone, good for twelve hours; it is useless on any other host and in Studio.

Remote here, commands in the repository

Studio only adds remote servers (the streamable HTTP transport). A server that runs as a command belongs in the repository's .mcp.json: Claude Code loads it in every workspace, as the person's own Linux user, with secrets as ${ENV} references. Both kinds end up in the same chat.

The bridge hands Studio's servers to Claude Code through a file only the workspace user can read, never on the command line, so a token does not show in the server's process list. It accepts nothing but {"type": "http", "url"} entries from Studio.

Channels

The channel is a switch in Administration → System; the installer can start on beta (STUDIO_CHANNEL=beta, see What it installs). Neither channel goes backwards: a build is installed only when it contains the installed commit, which the updater checks on a blob-less mirror of the repository. Back on stable after beta, Studio keeps its main build, newer than the last release, until a release contains it; when a release is tagged on that very commit, it moves to the release's name.

When

• Every night, between 04:00 and 05:00, from a systemd timer, while automatic updates are on (the default).
• From Administration → System: Check now, then Update to ….
• Force update, in the same place: builds the newest build of the channel and installs it now, even when it is the one already installed (a broken build, a failed system step, a server changed by hand). The new build goes next to the live one as <build>@<time>, with the same dump and rollback. It never goes back to an older build: that is what studio-update rollback is for.
• On the server: sudo studio-update apply (--force for the same as the button). Running the installer again does the same as apply.

What an update does

1. Clone the build into /opt/studio/releases/<build>. A tag's VERSION file must say the same as the tag. With /etc/studio/update-signers in place, the tag (or, on beta, the commit) must carry a valid SSH signature by one of those keys.
2. System step, as root, from the new build: its installer/requirements.env names the PHP versions, the PHP that runs Studio and the Node major; installer/lib/system.sh installs what is missing, refreshes Composer and Claude Code, and the provider's CLI. Nothing is removed.
3. Upgrade scripts, phase before: installer/upgrades/<version>.sh of every version after the installed one up to the new one, in order, as root, for what a release needs beyond packages. On beta, where several builds share a version, a script that changed since it ran runs again.
4. Build next to the running release, on the shared .env and storage: Composer without dev dependencies, the assets.
5. Database: a dump to /var/backups/studio/, maintenance mode, migrations with the new code. Caddy's certificate question, the access check of protected hosts and the bridges' callbacks keep answering meanwhile.
6. Switch: the new build's helper, templates, services, PHP-FPM pool and Caddyfile, then /opt/studio/current points at it; upgrade scripts, phase after; caches, restarts, maintenance off.
7. Health check: Studio must answer /up. If it does not, or any step from the dump on fails, the previous release, its root files and the database dump come back, and the System page shows the log.

Project sites and workspaces are not touched: they are your projects. Bridges move to the new code when they restart (a workspace stopped and started, a changed token); a release that changes the bridge protocol restarts them in its upgrade script. Three releases and five database dumps stay on disk.

Releasing

For whoever maintains Studio: set VERSION (1.0.0 today), commit, and push a vX.Y.Z tag on a commit that passed the tests. Every stable server installs it at its next run; beta servers already run that commit. The release workflow refuses a tag whose VERSION says otherwise, and so does the updater. To sign releases, tag with git tag -s and an SSH key (gpg.format=ssh), sign the commits of main too if beta servers check signatures, and put the allowed signers, in ssh-keygen's allowed-signers format, in /etc/studio/update-signers on each server. What a release needs on the server goes in installer/requirements.env, or in an upgrade script (installer/upgrades/README.md).

The card names the tool, shows the command or the file, and the reason when Claude gives one. Allow runs it with the input shown; Deny tells Claude the person declined, and the turn continues from there. While a question is open the conversation is marked waiting for permission in the sidebar, so a teammate glancing at the list sees who is blocked on whom.

Bypass mode is disabled in every workspace by the managed settings. A question left unanswered when a turn ends is closed as denied. The decision, who took it and when, is stored with the conversation.

Which modes a role may pick is modes_by_role in config/studio.php; the role's starting mode is permission_mode. Bypass mode, the one with no review at all, is not offered and is disabled in every workspace by the managed settings: autopilot is as far as it goes.

Labels and prompts live in config/studio.php; {project} is replaced with the project name. Change them, add your own, remove the ones your team does not use.

Custom skills become buttons

Larapilot projects keep their own skills in .larapilot/skills/<name>/SKILL.md, committed with the code; skills in Claude Code's own .claude/skills/ count too. The bridge reads their front matter and Studio shows each one as a button after the role's own, with the description as the tooltip, for example the acme-predeploy-gate in the screenshots. Add one from the chat with /larapilot-custom-skill, as you would in the editor; commit, and every workspace has it at the next start.

It is not a shell. The bridge takes the line, splits it into words, checks the binary and its first argument against a list, refuses anything that looks like shell syntax, and runs the binary directly in the workspace directory. Allowed today:

Output is kept to 200 KB and a command is killed after ten minutes. The shortcuts come from config/studio.php; the allowlist lives in the bridge (bridge/src/commands.js), so what the dashboard sends is checked where it runs. Clients have no terminal.

• Start / Stop start or stop the bridge and release the preview. Conversations and their sessions stay; a stopped workspace cannot receive a message, and the input says so.
• What persists: everything, it is a directory and a database on the server: the clone, the dependencies, the Claude login in the person's home.
• What does not: work that is not pushed, if the workspace is deleted. Keep branches short and pull requests small; the Larapilot loop wants that anyway.
• Memory: PHP-FPM pools are on demand and a stopped workspace costs nothing; the Claude Code process is released after ten idle minutes and resumed on the next message.

It is the role for the person who pays: they follow what is in review and what shipped without opening another tool, and without an email thread. If a client should also talk to the project, give them the PM role; from then on they have a workspace and a Claude plan of their own.

Events the bridge sends