Deploys and previews

A deploy turns the files in a server's repository into the server that answers at its address. Each deploy is built from one set of files, so the same commit always builds the same server.

Where a server lives

Every server has one address:

https://<slug>.sokie.cloud/mcp

The slug is chosen at random when the server is made, like majestic-lobster-123, and it never changes. Renaming the server in sokie.json doesn't move it, so an address you've shared keeps working.

What a deploy does

1. Checks the files the way sokie check does. Errors stop the deploy before anything is uploaded.
2. Uploads the definition files: sokie.json, the spec, and tools/, prompts/, resources/ and tests/, up to 16 MiB in all. The spec can be up to 14 MiB as JSON, or 2 MiB as YAML or GraphQL; every other file can be up to 1 MiB. YAML takes far more memory to read, so a larger YAML spec deploys once it's committed as JSON.
3. Builds the server from them, and checks that every secret it refers to is set.
4. Goes live. The new build takes over the address. For up to a minute, some calls may still reach the previous build while the change reaches every region; it stops answering five minutes later.
5. Runs its cases, when it has test cases that may run there. A failing case never takes the deploy back; on a preview, it fails the pull request's check.

Along the way a deploy is queued, then building, then live or failed. A deploy that a newer one overtakes before it goes live is superseded. sokie deploy waits and prints each step; --no-wait returns once it's queued. The server's Deploys tab in the app shows the history.

When a production deploy from GitHub fails or times out, Sokie emails the workspace's owner the reason and a link to the deploy. A run of failures sends one email; the next comes only after a deploy has gone live. A failed preview shows on the pull request's Sokie check instead, and a deploy you start yourself, with sokie deploy or in the app, fails in front of you, so neither sends email.

Telling deploys apart

Each deploy gets the server's next number, so you can say "deploy 12". The Deploys tab and the Overview show it with the code it ran: the commit and branch, a preview's pull request, or "uploaded from the CLI".

The server says which deploy is answering, which matters in the minute after a redeploy:

curl https://<slug>.sokie.cloud/health
{"status":"ok","runtime":"0.1.6","version":"12","commit":"1a2b3c4","deployment":"…"}

version is the deploy's number, and MCP clients get it as the server's version too. commit is there when the deploy came from GitHub. sokie deploy ends with Live: <address> (deploy #12), sokie call --production says which deploy answered, and sokie logs ends with the deploy production is on and when it went live.

What a deploy changed

Pick a deploy in the Deploys tab to see what agents see differently because of it, tool by tool:

• tools added, removed or renamed (the same operation under a new name)
• descriptions and titles
• effects raised or lowered, as clients see them: read-only, writes, or destructive
• input schemas, argument by argument
• response projections and the operation a tool calls
• the server's settings in sokie.json, prompts and resources, and the runtime version

Each changed tool links to its file on GitHub at the deploy's commit. A production deploy is compared with the production deploy that went live before it, and a preview with production as it is now, so you see what merging would change. A server's first deploy lists every tool it added. Compared with picks any other deploy. A failed deploy shows why it didn't build instead.

The same comparison from a terminal, by deploy number:

sokie deploys diff 12
sokie deploys diff 9 12 --json

Three ways to deploy

• From your machine, with sokie deploy. The first deploy takes --create for a new server, or --server <slug> for one you have.
• From GitHub, once the server is linked to a repository: every push to the default branch deploys.
• As a preview, for each pull request into the default branch.

Previews

A preview is a pull request's own build of the server, at its own address:

https://pr-<number>--<slug>.sokie.cloud/mcp

It rebuilds on every push to the pull request, and it's removed when the pull request closes. It's the same server under another address: it has the same access, the same secrets and the same connected clients, and it calls production's API. Pull requests from forks are only checked, never previewed, because a preview runs with the server's secrets.

Private and public

A server is private unless you make it public, with sokie deploy --create --public or later from the app. A private server answers only MCP clients its owner has approved; a public one answers anyone with the address. How clients sign in explains both.

A server whose API takes each caller's own key or sign-in has to stay private, because Sokie needs to know whose key to send. A public deploy of one fails with CALLER_KEYS_NEED_PRIVATE.

Switching later is a deploy too: the live source redeploys with the new setting, and the server changes when that deploy goes live. Change access, pause or delete a server shows how.