Deploying

crab --context cloud deploy

crab deploy uses the published image in crab.toml, or builds source when no image is declared. --build explicitly selects local source. The instance belongs to the selected account and is named after the image's service component, or the Cargo package when no image is declared. It takes an owner of the account, signed in or with an API key for that account, and the account needs Go or Pro, Hobby verified on GitHub with available execution entitlement, or an org's paid plan.

• Pass a service directory or a directory containing services. An image manifest in that directory is selected directly; groups select Cargo workspace services at or below it. The directory defaults to .; repeatable -p <name> selects instance names across the workspace instead. --force works as on the local host. More than one deploys together; see Projects.
• On a first source deployment, it uploads the seed its crab.toml names.
• It names each secret the service declares that is not set. See Secrets.
• A source deployment sets each tool's price from its price under [tools], in place of the prices the service had. A tool's price shows on the service's page and in crab inspect.

Before deploying source, measure and check tool budgets against the destination host. A successful build does not establish that they fit.

Approval

CLI sessions, including device logins, require browser approval. crab deploy prints the approval URL and waits for up to 15 minutes, even with stdin redirected or no terminal. --yes skips approval only with an API key that has deployments:write; service configuration changes also require services:write. Passing --yes with a CLI session is refused with E0022.

The image

Source builds upload to the selected host by default: CrabTalk Cloud or a local node. A context's registry, or crab deploy --build --registry localhost:5001, pushes a source build to an OCI registry instead. Published-image deployment uses the declared address independently of that registry. The node deploys the resolved image digest.

New deployments use the image's declared database size unless a size is supplied. Redeployments keep their existing reservation unless explicitly resized. Images built without a database-size default use 1 GiB.

public = true makes a source deployment public. Published-image copies start private. Publication is a separate crab publish operation, controlled by template and the image address. See Publishing.

Its name and data stay across deploys. Image-only upgrades that omit publication settings preserve them.

What a deploy refuses

A refused deploy leaves the running version serving. It is refused when:

• the name or a cron expression is invalid, or a migration fails;
• the image is on a registry other than ghcr.io, cannot be pulled without credentials, was not uploaded, or is not a service;
• the account is on Hobby and not verified or out of trial credit, or is an org with no plan;
• it breaks a tool or event a caller used in the last 30 days, naming each caller and its last use;
• it names a seed for a service that has a database, or a seed that is not uploaded or does not hold to the migrations;
• the service uses a host function Cloud does not serve;
• a tool's budget exceeds a host ceiling (E0013);
• size is past 10 GiB, or below what the database holds;
• its database reservation, retained images and pending uploads would exceed the account's storage allowance;
• no node has room for the service's size, or its node has no room for a larger one.

--force goes past the broken caller check.

Projects

A service is deployed in a project: the workspace it came from, named after the workspace's directory. The project is a label; the service's address stays {owner}/{name}, and a name is the account's once. Deploying a name that is in another project is refused, naming that project; --force moves it.

crab deploy deploys selected services together, on Cloud and on the local host alike. Every service is checked first: its image, crons, seed, size, room on a node, and its migrations, applied and rolled back. One refused refuses them all and nothing switches, naming each service's reasons. Recorded caller use still counts when the caller is deployed in the same set.

They then switch in name order. If one fails to switch, those switched before it go back to what they ran, and one deployed for the first time is removed. Migrations they applied stay applied.

Deploying a template

crab deploy --from crabtalk/foo creates a private service from the selected version of a published template, with your credentials, data and bill. A name already in use is refused. Deploy in the template page's Template card opens the confirmation and secrets flow in a new tab. Its deployment count includes existing copies across all versions, including stopped services; upgrades and retries do not add to it.

A source repository can declare image = "connect/tinyfish" in crab.toml. crab deploy selects its Cargo package version and creates your private tinyfish instance without compiling or installing Rust. The connect account identifies the source; your context identifies the destination account. --version 1.2.3 selects another exact release. An unavailable or yanked release fails without building source.

A standalone file needs an exact version:

image = "connect/tinyfish:1.2.3"

The published image supplies its tools, permissions, credentials, vars, migrations and schedules. Local source declarations, seed, prices, public and template settings do not apply to the copy. crab push creates it stopped. Workspace groups can mix published images and source-only services; group discovery still uses Cargo. Published Cloud images cannot deploy directly to the local host; use --build with local source for local development.

Copies stay pinned by default. Select an exact retained version with crab deploy --from connect/github --version 1.2.3, or choose it from the template’s Versions tab. Without --version, deployment uses the latest non-yanked stable release (or latest non-yanked prerelease when no stable release is retained). The copy’s page offers Upgrade to that version, showing migrations and breaks before applying it. Withdrawing a template prevents new deployments from it; existing copies keep working.

Automatic patch updates

Choose Automatically install patch updates on the deployment request’s approval page when deploying a template. crab deploy --from connect/github --auto-upgrade requests it by default; the owner can change the choice before approving. Redeploying from history disables automatic updates; switching template sources also requires a fresh opt-in.

Cloud checks for non-yanked patches each minute. Only newer stable patches in the same major and minor version qualify: 1.2.3 can update to 1.2.4, not 1.3.0, 2.0.0, or a prerelease. Changes to permissions, credentials, setup declarations, schedules, tool exposure or incompatible contracts require manual review. Database migrations also require manual review, and ordinary funding, storage and host-limit checks still apply.

A refusal or failed deployment leaves the previous deployment serving. Stopped services stay stopped. The Deployment card shows the latest automatic-upgrade error and its explanation; unsuccessful targets are retried after an hour. SemVer is the publisher’s compatibility declaration, not a proof of behavior.

Owners can read GET /services/{owner}/{name}/upgrades and set PUT /services/{owner}/{name}/upgrades with {"enabled":true}. API keys require deployments:read or deployments:write, respectively. Enabling is available only for template copies.

Deploy history

crab deploys <service> shows pending approval links and progress even before the service exists, then lists its last 100 deploys, newest first, refused and failed ones with their reason: how each ended, its version, what it was deployed from, the migrations it applied, whether it was seeded. A deploy refused before the service existed is not kept. A deploy of several services shows on each one's deploys with its project and the others named. The service's Deploys tab shows recorded attempts and redeploys a past one, under the same refusals.

Pending requests are separate from deployment attempts. Until approval and installation finish, no service is callable; owners receive E0046 when calling a name awaiting deployment. Uploaded images count toward storage while retained for a pending request or awaiting cleanup. GET /services/{owner}/{name}/deploys/status returns approvals and deploys; the existing /deploys endpoint returns recorded attempts only.

Each service retains its current image and two previous successful images. Older history records remain, but an uploaded image that has been pruned cannot be redeployed (E0043). This does not delete the running service or its data.

Starting and stopping

crab stop stops a service: it takes no calls and fires no wakes, and calls in flight finish. Its data, secrets and crons stay, and so does the storage it reserves. crab start serves it again, and wakes that came due meanwhile fire. crab push deploys a version stopped.

Removing a service

crab rm removes a service with its calls, logs, crons, wakes and secrets. Usage already metered stays on the account.