# CrabTalk

> CrabTalk hosts services: Rust programs compiled to WebAssembly, each with its own database, whose tools your agents, your apps and your other services call over HTTP.

Every docs page below in one file: https://crabtalk.ai/llms-full.txt
The Cloud API schema: https://api.crabtalk.ai/openapi.json

## Connect to CrabTalk

- [MCP setup](https://crabtalk.ai/docs/guides/mcp.md#connectors): If your host supports remote MCP, connect https://mcp.crabtalk.ai with OAuth, make its tools available in the conversation, and verify with an authenticated search call.
- [CLI setup](https://crabtalk.ai/docs/guides/contexts.md#agent-setup): If you have shell access, install the public crab CLI, sign in with device approval, and verify authenticated Cloud status.

CLI access and MCP connection are independent. Use the path needed for the task. Report which path you verified, or the exact blocked step and error. A configured URL or an unauthenticated HTTP 401 does not confirm a working connection. If neither path is available, name the missing host capability and the setup action the person needs to take.

## Guides


### Get started

- [Quickstart](https://crabtalk.ai/docs/guides/quickstart.md): Install crab, build and call a service locally without an account, then deploy to Cloud when ready.
- [Concepts](https://crabtalk.ai/docs/guides/concepts.md): Every CrabTalk word defined once — account, org, service, tool, call, run, project, plan, credit, request and context.
- [MCP](https://crabtalk.ai/docs/guides/mcp.md): Every CrabTalk service is reachable over one MCP endpoint, https://mcp.crabtalk.ai. An agent searches services, reads one's README and tools, then calls them.
- [Skills](https://crabtalk.ai/docs/guides/skills.md): npx skills add crabtalk/crab teaches a coding agent to write, build and deploy services with the crab CLI, and which page of these docs answers what.

### Services

- [Developing](https://crabtalk.ai/docs/guides/local.md): crab dev runs the local host, and crab deploy puts services on it. It serves their tools to `crab call` and over MCP, and a failed Cloud call replays on it.
- [Self-hosting](https://crabtalk.ai/docs/guides/self-hosting.md): Run Crab services on your own machine or server, connect agents over MCP, and keep their data under your control.
- [Deploying](https://crabtalk.ai/docs/guides/deploy.md): Deploy published images or local source builds to the selected account.
- [Publishing](https://crabtalk.ai/docs/guides/publishing.md): Publish a reusable image without exposing your deployment.
- [Service catalog](https://crabtalk.ai/docs/guides/catalog.md): Make your CrabTalk service discoverable. Classify tools by platform and job, publish services or templates, and contribute catalog categories through GitHub.
- [Calling a tool](https://crabtalk.ai/docs/guides/tools.md): crab call runs a tool of one of the account's services, or of another account's public one. Apps and scripts call it over HTTP, with an API key, as the API reference describes.
- [Access](https://crabtalk.ai/docs/guides/access.md): A service's visibility decides which accounts find it, and each tool's access in crab.toml decides who calls it — internal, public, anonymous, accounts or services.
- [Secrets](https://crabtalk.ai/docs/guides/secrets.md): Secrets are the keys and credentials a service sends to other services. A person sets them; once saved, nobody reads a value again, their agent included.
- [Webhooks](https://crabtalk.ai/docs/guides/webhooks.md): A service takes events from senders that push, at a URL per tool, verified with Standard Webhooks before anything runs.
- [Security](https://crabtalk.ai/docs/guides/security.md): What a service on CrabTalk can reach, where its secrets go, and how every request it sends names it.
- [Vars](https://crabtalk.ai/docs/guides/vars.md): Vars are the settings each deployed copy of a service holds its own value of, such as the keywords a monitor watches. Whoever deploys a copy sets them.
- [Budgets](https://crabtalk.ai/docs/guides/budgets.md): Measure a tool's WebAssembly execution, add headroom, and check the host's ceilings before publishing or deploying its budget.
- [Benchmarking](https://crabtalk.ai/docs/guides/bench.md): Use crab bench to measure local WebAssembly workloads, estimate execution costs and suggest budgets before deployment.
- [Monitoring](https://crabtalk.ai/docs/guides/monitoring.md): crab usage, crab calls, crab logs and crab cost read what a service used, each call of the last 30 days, its logs and what it cost.
- [Replaying](https://crabtalk.ai/docs/guides/replay.md): A call that failed keeps its input and a tape of every answer it got from outside. crab replay runs it again on your machine, failing as it failed.

### Accounts

- [Your account](https://crabtalk.ai/docs/guides/account.md): You sign in to CrabTalk with Google or GitHub, and a handle you pick names your account in URLs.
- [Organizations](https://crabtalk.ai/docs/guides/orgs.md): An org is an account people share. Its owners manage it and its services, its members see and call them, and crab --org acts for it.
- [API keys](https://crabtalk.ai/docs/guides/keys.md): An API key lets an agent, a script or CI deploy to an account and call services as you. Make one in Settings or with crab key create; it is shown once.
- [Contexts](https://crabtalk.ai/docs/guides/contexts.md): A context names the host crab talks to and the session it uses there — the local host, Cloud as you, or Cloud as an API key for an org.

### Billing

- [Plans](https://crabtalk.ai/docs/guides/plans.md): Plans, resources and Credit for personal and organization accounts.
- [Credit](https://crabtalk.ai/docs/guides/credit.md): Credit pays priced calls and paid-plan overages. Trial credit funds eligible execution. Pro and Scale subscriptions also return Credit.
- [Cost of a call](https://crabtalk.ai/docs/guides/cost.md): A call has two costs, its tool's price, paid by the caller, and what its run used, paid by the service's owner. crab call prints what each run cost to run.
- [Earnings](https://crabtalk.ai/docs/guides/earnings.md): A service's owner sets a price a call on a tool, other accounts pay it from credit, and Stripe Connect pays the owner monthly. The Earnings page shows each month and the payouts.

## Development

- [Introduction](https://crabtalk.ai/docs/development/introduction.md): A CrabTalk service is a Rust program compiled to WebAssembly, with its own database, whose tools your agents, apps and other services call over HTTP.
- [A complete service](https://crabtalk.ai/docs/development/complete-service.md): The three files of a working CrabTalk service, a Rust library crate with echo and durable state, and the commands that test, build, deploy and call it.
- [Build from OpenAPI](https://crabtalk.ai/docs/development/openapi.md): Turn selected operations from an OpenAPI document into a CrabTalk service, with generated inputs, HTTP requests and callable tools.

### Reference

- [crab.toml](https://crabtalk.ai/docs/development/crab-toml.md): Declare a service's published image, tools, permissions, credentials, database and defaults.
- [Macros](https://crabtalk.ai/docs/development/macros.md): The six macros of berm-lang: what each is written on, what it accepts, what it generates and what it refuses at compile time.
- [API](https://crabtalk.ai/docs/development/api.md): Every function and type of berm-lang a service calls, with its signature, grouped by what it reaches, and the page that holds its rules.

### Capabilities

- [Callers and users](https://crabtalk.ai/docs/development/callers.md): Who called a tool, the end user it runs for and the outside client, as the host sets them, and how a service vouches for a user of its own.
- [Data](https://crabtalk.ai/docs/development/data.md): A service that declares a database gets its own SQLite file, migrated at deploy, and every call to it runs as one transaction.
- [HTTP](https://crabtalk.ai/docs/development/http.md): berm_lang::http sends requests to the hosts a service declares in crab.toml, one at a time or in a batch, with secrets the host writes in.
- [Other services](https://crabtalk.ai/docs/development/services.md): Call running deployments by owner/service through berm_lang::call or generated typed calls.
- [Crons and wakes](https://crabtalk.ai/docs/development/crons.md): A #[tool(cron)] tool runs on a schedule set in crab.toml, and a call can schedule one later call of a tool, a wake.
- [Webhooks](https://crabtalk.ai/docs/development/webhooks.md): A #[tool(webhook)] tool runs on each signed POST a sender makes, with the body as its arguments.
- [Vars](https://crabtalk.ai/docs/development/vars.md): A var is a setting a service declares in crab.toml with a default, which each deployed copy sets to its own value, read with berm_lang::var.
- [Secrets in code](https://crabtalk.ai/docs/development/secrets.md): A secret is a value the host writes into a service's outgoing requests. The service names it as {secret:NAME} and never reads it; a person sets it.
- [Credentials](https://crabtalk.ai/docs/development/credentials.md): A credential in crab.toml groups the secrets a person gets from one provider, with the guide, copy values, hosts and patterns they are set with.
- [Budgets in code](https://crabtalk.ai/docs/development/budgets.md): berm_lang::limit lowers the running call's CPU, rows and memory budget, for that call alone, so a tool bills only the memory its arguments need.
- [Reusing services](https://crabtalk.ai/docs/development/reuse.md): Call a running service, deploy a private copy, or link its Rust API into your own service.

### Working on it

- [Testing](https://crabtalk.ai/docs/development/testing.md): Unit test a service's tools natively with berm_lang::test, or run its built image on the real host in a test with berm_host::test::TestHost.
- [Changing an interface](https://crabtalk.ai/docs/development/interfaces.md): A redeploy that breaks a public tool, the Stripe tool or an event a caller used in the last 30 days is refused unless forced. What counts as a break.

## Reference

- [API schema](https://crabtalk.ai/docs/reference/api.md): Get Cloud's OpenAPI schema or run its reference locally.
- [Authentication](https://crabtalk.ai/docs/reference/authentication.md): How Cloud identifies callers through sessions, API keys and app user tokens.
- [Permissions](https://crabtalk.ai/docs/reference/permissions.md): Credential requirements, API-key scopes, account roles and tool-access rules for Cloud operations.
- [Request limits](https://crabtalk.ai/docs/reference/request-limits.md): Cloud request rates, bursts, concurrency, shared account quotas and how to handle throttling over HTTP and MCP.
- [Reserved handles](https://crabtalk.ai/docs/reference/reserved-handles.md): Names reserved for CrabTalk products, platform use and third-party brands.

## Errors

- [Introduction](https://crabtalk.ai/docs/errors/introduction.md): What each error code means and what to do about it, as crab explain prints it.

### Codes

- [E0001](https://crabtalk.ai/docs/errors/E0001.md): A deploy was refused because the account is on Hobby and not verified on GitHub.
- [E0002](https://crabtalk.ai/docs/errors/E0002.md): A deploy was refused because the org holds no paid plan.
- [E0003](https://crabtalk.ai/docs/errors/E0003.md): Verifying was refused because no GitHub account is connected to the person's account.
- [E0004](https://crabtalk.ai/docs/errors/E0004.md): Verifying was refused because the GitHub account is less than a year old.
- [E0005](https://crabtalk.ai/docs/errors/E0005.md): Verifying was refused because the GitHub account's own public repositories hold fewer than 10 stars.
- [E0006](https://crabtalk.ai/docs/errors/E0006.md): Verifying was refused because the GitHub account already verified another CrabTalk account.
- [E0007](https://crabtalk.ai/docs/errors/E0007.md): A verify request was refused because the account has nothing to verify.
- [E0008](https://crabtalk.ai/docs/errors/E0008.md): Verifying was refused because this deployment has no GitHub app to verify with.
- [E0009](https://crabtalk.ai/docs/errors/E0009.md): A call was refused because the API key may not call another account's priced service.
- [E0010](https://crabtalk.ai/docs/errors/E0010.md): A call was refused because its price takes the API key past its daily budget.
- [E0011](https://crabtalk.ai/docs/errors/E0011.md): A var was refused because the service does not declare it, or the value is past 4096 bytes.
- [E0012](https://crabtalk.ai/docs/errors/E0012.md): A secret request was refused because every secret the service requires is set.
- [E0013](https://crabtalk.ai/docs/errors/E0013.md): A deploy was refused because a tool's budget in `crab.toml` is past the most the node lets one call use.
- [E0014](https://crabtalk.ai/docs/errors/E0014.md): A webhook was refused because the service does not exist or has no webhook tool of that name.
- [E0015](https://crabtalk.ai/docs/errors/E0015.md): A webhook was refused because the service has no usable `WEBHOOK_SECRET`.
- [E0016](https://crabtalk.ai/docs/errors/E0016.md): A webhook was refused because its signature headers are missing or malformed.
- [E0017](https://crabtalk.ai/docs/errors/E0017.md): A webhook was refused because its signature doesn't match or its timestamp is more than 5 minutes from now.
- [E0018](https://crabtalk.ai/docs/errors/E0018.md): An event was refused because the service is stopped or its account is held.
- [E0019](https://crabtalk.ai/docs/errors/E0019.md): Work was refused because it would exceed the account’s memory allowance.
- [E0020](https://crabtalk.ai/docs/errors/E0020.md): A deploy was refused because the image uses a host call this host does not serve.
- [E0021](https://crabtalk.ai/docs/errors/E0021.md): A deploy was refused because a required secret is unset. The running version stays unchanged. Optional credentials do not block a deploy.
- [E0022](https://crabtalk.ai/docs/errors/E0022.md): Direct deployment from the CLI requires an API key with `deployments:write`.
- [E0023](https://crabtalk.ai/docs/errors/E0023.md): A deploy was refused because its node did not acknowledge the secrets configuration.
- [E0024](https://crabtalk.ai/docs/errors/E0024.md): Trial credit cannot fund the operation.
- [E0025](https://crabtalk.ai/docs/errors/E0025.md): The account would exceed its combined storage allowance.
- [E0026](https://crabtalk.ai/docs/errors/E0026.md): The caller lacks the management scope required for this operation.
- [E0027](https://crabtalk.ai/docs/errors/E0027.md): This operation requires an authenticated person session.
- [E0028](https://crabtalk.ai/docs/errors/E0028.md): The API key is bound to a different account.
- [E0029](https://crabtalk.ai/docs/errors/E0029.md): The person's Hobby organization slot is occupied.
- [E0030](https://crabtalk.ai/docs/errors/E0030.md): An organization checkout is already pending for this person.
- [E0031](https://crabtalk.ai/docs/errors/E0031.md): The Hobby organization has reached its membership allowance.
- [E0032](https://crabtalk.ai/docs/errors/E0032.md): The organization is paused.
- [E0033](https://crabtalk.ai/docs/errors/E0033.md): The organization needs an eligible Hobby sponsor.
- [E0034](https://crabtalk.ai/docs/errors/E0034.md): The organization checkout has expired.
- [E0035](https://crabtalk.ai/docs/errors/E0035.md): The account handle has an invalid format.
- [E0036](https://crabtalk.ai/docs/errors/E0036.md): The account handle is reserved.
- [E0037](https://crabtalk.ai/docs/errors/E0037.md): The secret request's credential destinations have changed.
- [E0038](https://crabtalk.ai/docs/errors/E0038.md): Subscription billing is still synchronizing.
- [E0039](https://crabtalk.ai/docs/errors/E0039.md): The caller does not own the account.
- [E0040](https://crabtalk.ai/docs/errors/E0040.md): This template release's image is no longer retained.
- [E0041](https://crabtalk.ai/docs/errors/E0041.md): This template version already identifies a different image.
- [E0042](https://crabtalk.ai/docs/errors/E0042.md): This automatic patch upgrade needs manual review.
- [E0043](https://crabtalk.ai/docs/errors/E0043.md): This deployment's image is no longer retained for rollback.
- [E0044](https://crabtalk.ai/docs/errors/E0044.md): This template release has been yanked.
- [E0045](https://crabtalk.ai/docs/errors/E0045.md): This object is being deleted.
- [E0046](https://crabtalk.ai/docs/errors/E0046.md): This service has a pending deployment and is not ready to call.
- [E0047](https://crabtalk.ai/docs/errors/E0047.md): The calling service's identity could not be verified.
- [E0048](https://crabtalk.ai/docs/errors/E0048.md): The paying account has insufficient credit for the tool's price.
- [E0049](https://crabtalk.ai/docs/errors/E0049.md): The target tool does not accept service callers.
- [E0050](https://crabtalk.ai/docs/errors/E0050.md): The service cannot use the requested runtime secret grant.
- [E0051](https://crabtalk.ai/docs/errors/E0051.md): The event source refused the subscription's caller.

## Blog

- [Why Durable Objects Charge for Rows, Not Response Bytes](https://crabtalk.ai/blog/durable-objects-row-billing): Why Durable Objects bill rows instead of response bytes, with a reproducible index-cost example that accounts for CrabTalk and Cloudflare plan allowances.
- [Letting services fetch any host without becoming an open relay](https://crabtalk.ai/blog/open-egress-without-an-open-relay): A crawler needs to fetch any host. We kept * in crab.toml, and checked what it opens: not our network, not your secrets, but our IPs. Here is what we did.