Run hosted mode
This guide runs Speccy for a team. Hosted mode adds accounts, roles, visibility, share links, review requests and approvals to local mode. It stores everything in Postgres.
What you need
Section titled “What you need”- A Postgres database that Speccy can own.
- A public HTTPS address, such as
https://speccy.example.com. - A master key: 32 random bytes in base64, from
openssl rand -base64 32.
Start the server
Section titled “Start the server”The image ghcr.io/alternayte/speccy runs speccy serve --hosted as a non-root user on port 8080. It needs no volume. Each release has a tag with its version, such as 0.18.0.
Make the master key once, and keep it in your secret store. A new key on each start makes the stored API keys unreadable.
openssl rand -base64 32 > speccy-master-keydocker run -p 8080:8080 \ -e SPECCY_DATABASE_URL=postgres://speccy:secret@db:5432/speccy \ -e SPECCY_MASTER_KEY="$(cat speccy-master-key)" \ -e SPECCY_BASE_URL=https://speccy.example.com \ ghcr.io/alternayte/speccy:0.18.0The master key explains the key. Configuration lists every variable, with the optional ones for sign-in, the address and the log level.
At start, Speccy applies its database migrations. Then it prints one line:
Speccy (hosted) is listening on [::]:8080 for https://speccy.example.comA missing or bad variable stops the start, and the message names each problem at once. Hosted mode writes JSON logs to standard error.
Serve Speccy behind TLS. With an http:// base URL, the cookies lose the Secure flag. Use that for development only.
GET /healthz answers 200 with ok, with no sign-in. GET /readyz answers 200 only when Speccy reaches Postgres and its job workers run. Otherwise it answers 503.
Make the first admin
Section titled “Make the first admin”Speccy has no open sign-up, and it sends no mail. Every account comes from an invite link. Setup makes the first one.
-
Make a setup token, and give it to the server as
SPECCY_SETUP_TOKEN:Terminal window openssl rand -hex 16 -
Open
<SPECCY_BASE_URL>/setup. Type the setup token, and select Next. -
On Join Speccy, type your name, email and a password of at least 12 characters. Select Make my account. Speccy signs you in as an admin.
-
On Connect GitHub, connect the workspace to GitHub, or select Done to do it later. Connect GitHub has the steps.
When an admin exists, /setup closes and the setup token stops working. You can remove the variable.
Without a setup token, run the invite command with the same environment as the server. In the container:
docker exec <container> /usr/local/bin/speccy admin invite --role adminIt prints a link that works once, for 7 days by default. The command also gives a new admin link when no admin can sign in.
The email is the sign-in name. Speccy does not check it by mail.
Invite people
Section titled “Invite people”-
Open Admin. The People part has Accounts and Invite links.
-
Under Invite links, choose Member or Admin, and select Make an invite link.
-
Copy the link. Speccy shows it one time.
-
Send the link to the person yourself, for example in a direct message.
Revoke ends an open invite link. speccy admin invite --role member makes a member link from the command line.
Under Accounts, an admin changes the role of a person, and selects Disable to stop an account. Reset link makes a password reset link. It works once, for 24 hours, and the new password signs the person out everywhere. speccy admin reset-link <email> makes the same link from the command line.
Connect GitHub
Section titled “Connect GitHub”A workspace connects to GitHub in one of two ways: a GitHub App, or a fine-grained token. It never uses both.
With a GitHub App
Section titled “With a GitHub App”Speccy makes a private GitHub App for the workspace. Only the account that owns the App can install it.
-
Open Admin → GitHub.
-
Under GitHub App, type the org that owns the repos. Leave the field empty to make the App on your personal account. For GitHub Enterprise Server, type its API address.
-
Select Create the App on GitHub. GitHub shows the App. Select Create GitHub App. GitHub sends you back to Admin → GitHub.
-
Select Install the App. Choose the repos that Speccy may read, and select Install.
GitHub must reach <SPECCY_BASE_URL>/api/github/webhook. A push then syncs its source at once. When GitHub cannot reach the server, Speccy still reads each source every 5 minutes.
With the App:
- Speccy reads sources and makes breakdown issues as the App.
- A pull request that a person publishes goes to GitHub with that person as its author. The first time, Speccy asks the person to connect their GitHub account.
- A member of the org that owns the App signs in with GitHub, with no invite, as a member. On a personal account, only its owner signs in with GitHub.
- The App reviews the pull requests of a repo with
mode: appin.speccy.yaml. Review pull requests with the App has the details.
Disconnect makes Speccy forget the App’s keys and each person’s GitHub link. The App stays on GitHub. App settings on GitHub opens the page that deletes it.
To make the App yourself, set the SPECCY_GITHUB_APP_ variables in Configuration. They lock the App in Admin → GitHub.
With a token
Section titled “With a token”Use a token when the org cannot add a GitHub App. Under Admin → GitHub, paste a fine-grained personal access token with read and write access to Contents and Pull requests. Speccy then reads each source every 5 minutes. Every pull request goes to GitHub as the owner of the token, and sign-in with GitHub is off.
Review pull requests with the App
Section titled “Review pull requests with the App”The GitHub App reviews the pull requests of each repo that it can read. The repo needs no workflow and no secret.
-
Install the App on the repo, as With a GitHub App says.
-
Add
.speccy.yamlto the repo withmode: app.speccy init --github --reviewer appwrites it. .speccy.yaml has the key. -
In the branch protection of the repo, mark each
speccy: <bundle slug>check as required. Set the App as the expected source of the checks.
A repo with no mode key gets a review from the App and from the Action, if the repo has the workflow. With mode: action, the App skips the repo.
What starts a review
Section titled “What starts a review”The App queues a review of the head commit when:
- A person opens, reopens or pushes to a pull request, or marks it ready for review.
- A comment on the pull request, or a reply on a review comment, has a line that starts with
/speccy.
A reply command thus acts at once, with no push. A new push cancels the review of the older commit.
What the review does
Section titled “What the review does”- It reviews the spec docs that the pull request changes. It uses the workspace profiles and the workspace models.
- It posts the summary comment and the inline comments, and one check for each bundle, named
speccy: <bundle slug>. - It commits a sidecar or
.speccy.yamlchange that a reply asked for to the branch of the pull request. It never commits to a fork. Reply commands lists the commands. - With no model on the
reviewerrole, it runs the lint checks only. - It keeps the report of each review for 90 days. The summary comment links to it.
The App reads enforcement, adoption.relaxed and mode from the base branch, so a pull request cannot change its own gate. It reads map, size, the link rules and the sidecars from the head commit. A pull request that adds .speccy.yaml for the first time uses its own file.
The App ignores a .speccy/profiles folder in the repo. The summary comment says so once. Change the profiles in Admin → Profiles.
A .speccy.yaml that is not valid gives one failed check, named speccy, with the problem.
When the monthly budget of pull request reviews is spent, the review stops. In blocking mode, the check fails and names the budget. Budget and model cost explains the two budgets.
An App that lacks permissions
Section titled “An App that lacks permissions”The App needs Checks: write and the events issue_comment and pull_request_review_comment. An App that an older Speccy made does not have them. Admin → GitHub then says The App lacks and names each missing item. GitHub does not let Speccy change an App.
-
Under Admin → GitHub, select App settings on GitHub.
-
Under Permissions & events, set Checks to Read and write. Select the events Issue comment and Pull request review comment. Save the changes.
-
On the installation of the App, accept the new permissions.
Sign in with OIDC
Section titled “Sign in with OIDC”A provider signs in a person who has an account already. It never makes an account. Speccy does not match a provider account to a Speccy account by email.
-
Register Speccy at the provider, such as Entra ID, with the callback URL
<SPECCY_BASE_URL>/api/auth/oauth/oidc/callback. -
Set
SPECCY_OIDC_ISSUER,SPECCY_OIDC_CLIENT_IDandSPECCY_OIDC_CLIENT_SECRET, and restart Speccy. -
Each person signs in with their password once. Under Account → Sign-in providers, they select Link next to the provider.
From then on, the sign-in page shows Sign in with single sign-on. A person with an invite account links GitHub the same way.
| Role | Can |
|---|---|
| Admin | Everything. Only an admin sees Admin: the models, the budget, the people, GitHub and the workspace settings. An admin also creates and deletes profiles. |
| Member | Create bundles, and edit the bundles they author. Read the internal bundles and the bundles they review. Run reviews, ask for waivers, approve, and take build packets. |
| Guest | Read one shared bundle, and write in its threads. A guest cannot edit, run a review, ask the AI, waive or approve. |
An admin names the maintainers of each profile on the profile page. A maintainer edits that profile, and sees Insights.
Choose who sees a bundle
Section titled “Choose who sees a bundle”An author or an admin selects Share on the bundle page.
| Visibility | Who sees the bundle |
|---|---|
| Private | Its authors, its named reviewers, and admins. |
| Internal | Every member. A new bundle starts here. |
| Link | Every member, and anyone with the share link, as a guest. |
Make a share link sets the visibility to Link and shows the link one time. Make a new link replaces the old link. Revoke the link ends every guest’s access at once. A move away from Link also revokes the link.
A guest opens the link, types a name, and selects Open the spec. Speccy then keeps the guest signed in with a cookie for 30 days, while the link stays live.
Reviewer mode
Section titled “Reviewer mode”A person who cannot edit a bundle sees it in reviewer mode. Members who are not authors, and guests, get it. Reviewer mode shows the spec doc, its assets, one status line, and the threads. It hides the findings, the score and every author tool. An author can see the same screen with ?as=reviewer at the end of the bundle URL.
Ask for a review and approve
Section titled “Ask for a review and approve”The author selects Request review and names the reviewers. The bundle moves from Draft to In review, and the reviewers see it in their Inbox. A reviewer selects Approve on the current version.
- Approval needs a current Build Ready verdict.
- An author cannot approve their own bundle.
- A change to the doc after approval revokes the approvals.
The profile sets how many approvals a bundle needs, and who approves a waiver. Ask for and approve a waiver covers waivers.
API tokens and MCP
Section titled “API tokens and MCP”Each person makes personal API tokens under Account → API tokens, with Make a token. A token starts with spy_ and has the role of its owner. It stops working when the owner loses the role.
speccy review --server https://speccy.example.comreads the token fromSPECCY_TOKEN. It waits until the review on the server ends.- MCP clients reach the Speccy tools at
/mcpover streamable HTTP, withAuthorization: Bearer <token>. A tool can do what the owner of the token can do in the app, and nothing more. Thereview_contentandreview_urltools wait for the review to end, and they send progress notifications.
POST /api/v1/reviews and POST /api/v1/reviews/url queue the review and answer 202 with a review request: its id, its kind and its status. GET /api/v1/reviews/{reviewId} gives the status, queued, running, complete or failed, the stage, and then the result. A proxy timeout thus never cuts a review.
Models and GitHub
Section titled “Models and GitHub”An admin adds the model backends and assigns the roles under Admin. Add a model backend has the steps. The image holds no agent CLI, so use API backends.
Admin → Models has one monthly token limit for each queue: Reviews a person waits for and Pull request reviews of the GitHub App. It shows the spend of this month by queue, by person and by repo. Budget and model cost explains the budget.
An admin connects GitHub under Admin → GitHub, as Connect GitHub says. Adopt a repo covers sources.
Queues and jobs
Section titled “Queues and jobs”Speccy runs each review as a job in a queue in Postgres. There are two queues:
| Queue | Its jobs | Setting in Admin → Workspace settings |
|---|---|---|
interactive |
The reviews from the app, the CLI and MCP, the AI answers in threads, the verification runs, the review requests and the channel messages. | Reviews at a time, 3 by default. |
pr |
The pull request reviews of the GitHub App. | Pull request reviews at a time, 2 by default. |
Each setting takes 1 to 20. A change waits for the running reviews of its queue to finish. Thus a burst of pushes does not make people wait, and people do not hold up the pull request checks. Model calls at a time applies to each running review, 8 by default.
After a 429 or a 5xx answer from a model provider, Speccy waits and tries the call again. It waits for the retry-after time when the answer gives one. It tries again while the review has time left.
An admin opens the queue view at /admin/queues. It shows the jobs of each queue, with the failed and the cancelled ones. Only an admin sees it, and only in hosted mode.
A daily job deletes the model cache entries that no review read for 90 days.
Send notifications to a channel
Section titled “Send notifications to a channel”Speccy can post to one Slack or Teams channel. It sends no mail.
-
Make an incoming webhook for the channel. For Teams, use a Workflows webhook.
-
Open Admin → Notifications. Under Kind, choose Slack or Teams.
-
Paste the URL under Webhook URL, and select Save. The URL must start with
https://. -
Select Send a test message. Speccy shows the HTTP status of the answer.
Speccy stores the URL encrypted with the master key. The page shows only its last 4 characters. Remove deletes it. SPECCY_NOTIFY_WEBHOOK_URL and SPECCY_NOTIFY_WEBHOOK_KIND set the webhook instead, and lock it on the page.
Speccy posts one message when:
- An author asks for a review. The message names the reviewers.
- A person asks for a waiver. When the profile’s policy is
maintainer, the message names the profile maintainers. - A blocking thread opens. The message names the authors.
- A spec becomes Build Ready. The message names the authors.
- A monthly token budget reaches 80%.
A message holds the bundle title, one sentence, the names and one link. It holds no doc text and no finding text. A Private bundle posts nothing. Pull request reviews post nothing, because GitHub notifies those. Each message is a job that tries 3 more times when the webhook fails. A failed message never stops the action that caused it.
Run on Kubernetes
Section titled “Run on Kubernetes”Run one replica. Model throughput limits Speccy, not the process, so a second replica adds no speed. Use the Recreate strategy, so an old and a new version never run at once. When a deploy stops a review, the job queue runs the review again on the new version. When a process dies during a review, the queue gives the review to a worker again after 20 minutes.
apiVersion: apps/v1kind: Deploymentmetadata: name: speccyspec: replicas: 1 strategy: type: Recreate selector: matchLabels: { app: speccy } template: metadata: labels: { app: speccy } spec: containers: - name: speccy image: ghcr.io/alternayte/speccy:0.18.0 ports: - containerPort: 8080 envFrom: - secretRef: name: speccy-env # SPECCY_DATABASE_URL, SPECCY_MASTER_KEY, SPECCY_BASE_URL, SPECCY_SETUP_TOKEN readinessProbe: httpGet: { path: /readyz, port: 8080 } livenessProbe: httpGet: { path: /healthz, port: 8080 }/readyz checks Postgres and the job workers, so a pod that cannot reach Postgres gets no traffic. /healthz says only that the process serves HTTP, so the liveness probe does not restart a pod when Postgres is down.
Speccy opens at most 20 Postgres connections, and the job queue uses the same pool. SPECCY_DB_MAX_CONNS changes the number. Keep it below the max_connections of Postgres.
Put SPECCY_SETUP_TOKEN in the Secret, and make the first admin at /setup.
Limits and rate limits
Section titled “Limits and rate limits”Under Admin → Workspace settings, an admin sets six limits. Three are the largest file, the largest bundle and the life of an invite link. Three are the model calls at a time, the reviews at a time, and the pull request reviews at a time. Configuration has the defaults.
Speccy limits sign-in, invite links, reset links and password changes for each client address. It keeps the counts in the database. A refused request gets 429.