Docs
siDiscord

Developing

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.

The local host runs on your machine at http://127.0.0.1:7777, one per machine, with its state in ~/.crab/host. Other commands reach it with --context default. It checks no authorization.

For running existing services on your own machine or server, see Self-hosting.

crab dev

crab dev -d
crab --context default deploy

crab dev runs the local host in the foreground until Ctrl-C; -d starts it in the background, writing to ~/.crab/host/host.log. On start it loads every service deployed before, and logs any that fails to load.

Flag
-d Run in the background and return once it answers.
--addr Where it listens. 127.0.0.1:7777 by default.
--root Where its images, databases, code cache and secrets.toml live. ~/.crab/host by default.
--max-call-depth How deep a chain of services calling services nests. 4 by default; 0 refuses the first nested call.
--max-cpu-millis The CPU one call may spend, in milliseconds, nested calls excluded. 100 by default, and the ceiling of every tool's budget.
--max-call-seconds How long one call runs before it is stopped. 60 by default.
--proxy The proxy berm.http.proxy goes through, as http://user:[email protected]:3120. Without one it goes direct.
  • crab dev status prints its pid, root and when it started. crab dev stop stops it.
  • crab --context default status checks whether the local host answers at /meta/health. Local development needs no account or login.
  • crab deploy starts it with its defaults when nothing answers on 127.0.0.1:7777.

Deploying

crab deploy [dir] on the default context builds and deploys, and is run again after a change. It selects the service in that directory, or Cargo workspace services beneath it whose crab.toml does not say deploy = false. The directory defaults to .; -p <name>, repeatable, selects services by name anywhere in the workspace instead.

If crab.toml declares image, use crab deploy --build to build local source. The local instance takes the service component of that address, or the Cargo package name when no image is declared. Published-image deployment requires a Cloud context.

  • A deploy is refused when it breaks what a caller used in the last 30 days. --force deploys past that check. See Deploying.
  • More than one service deploys together: all switch or none do. See Projects.
  • Static schedules come from [crons] embedded in the image. Change the manifest and redeploy to change them.
  • A deploy prints the service's tools, what it breaks and each secret it declares that is not set.
  • A deploy to the local host is refused for a service whose crab.toml names a seed.
  • crab rm removes services and their data: those named, or with no name, the same set as crab deploy.

Starting and stopping

crab push deploys as crab deploy does and installs each service stopped. crab stop and crab start stop and serve services, named or the same set; crab ls shows which run.

  • A stopped service takes no calls, from outside or from other services, and fires no wakes. Calls in flight finish.
  • Its data and secrets stay, and wakes that come due fire once it starts.

Benchmarking before deployment

crab bench <directory> <tool> --cases cases.jsonl --runs 10 builds and runs an explicit workload in temporary host state. See Benchmarking for HTTP fixtures, cost estimates and budget suggestions.

Calling a tool

crab --context default call app search '{"query": "hi"}'

crab call prints the result and what the run cost to run at crabtalk.ai's rates (Cost of a call), and exits 2 when the tool ran and failed. The arguments are read from stdin when omitted. On the local host, the caller defaults to local; --caller alice overrides it, and --anonymous calls without a caller. --issuer with --user sets the end user it is called for. These identities are unchecked, and the flags are local-only; Cloud uses your credential.

Changing --caller does not switch storage. Every caller shares the service's database and keyspace; the service implements per-user storage when needed.

  • A call with --anonymous reaches only tools with access = "anonymous" in crab.toml. It cannot be combined with --caller, --issuer or --user.
  • A call to a stopped service, or one with no call slot free, is refused.

For CPU, row and memory units, headroom and host ceiling checks, see Sizing a budget.

Reading a service

On the default context these read the local host:

Command Prints
crab ls Every deployed service, and whether it runs.
crab inspect <service> Its tools, their arguments and what it declares.
crab logs <service> Its logs, oldest first, kept 30 days.
crab usage <service> What it used each day.
crab cron ls <service> Each cron tool, its schedule and next run. See Crons and wakes.
crab wakes <service> Its wakes that have not run.

crab calls, crab cost and crab visibility reach Cloud only.

MCP

crab dev serves every deployed service on one MCP endpoint, http://127.0.0.1:7777/mcp, over Streamable HTTP. For the hosted endpoint, see MCP.

  • Use search → inspect → call. search matches words in a service's name, description and tools. inspect(service) returns definition, the service's README and tool definitions with input schemas, and prices, a map of USD micros per call (empty locally).
  • inspect, call and crab://{service} name a service by its name alone. Resource reads expose the same caller-filtered definition as inspection.
  • Send x-berm-caller: {"id":"alice"} on MCP requests to discover and call public tools as that caller. The identity is unverified.
  • Without the header, only tools with access = "anonymous" in crab.toml are discoverable and callable. Stopped services expose no callable tools.

Secrets

The local host keeps its own secrets, apart from Cloud's, set with crab --context default secret fill: see Secrets.

Replaying a failed call

A call that failed on Cloud runs again on your machine with crab replay: see Replaying.