Self-hosting

crab dev hosts services on your machine, including their tools, databases, secrets and schedules. Deploy an existing service from the public Crab repository, or one you have written. Hosting services this way needs no CrabTalk account or login.

Run an existing service

Install crab, then deploy the webpage-to-Markdown service:

git clone --branch main --single-branch https://github.com/crabtalk/crab.git
crab dev -d
crab --context default deploy --build crab/services/web/markdown
crab --context default call markdown read '{"url":"https://example.com"}'

The CLI builds the selected service and installs missing build tools automatically. The host runs in the background at http://127.0.0.1:7777. --context default selects it even if your CLI is signed in to Cloud. Services are addressed by name, such as markdown.

Choose other services from the repository's catalogs. Read the service's README for its credentials, settings and tools. The CLI's --from owner/name template-copy flow currently deploys to Cloud; self-hosted deployment builds a service directory.

For a service requiring credentials, run crab --context default secret fill <service> in your terminal. Values are kept on your host. See Secrets and Vars for provisioning and settings.

Connect an agent

The host serves all deployed services over Streamable HTTP at http://127.0.0.1:7777/mcp. For a client accepting MCP JSON configuration:

{
  "mcpServers": {
    "local-services": {
      "url": "http://127.0.0.1:7777/mcp",
      "headers": {
        "x-berm-caller": "{\"id\":\"local\"}"
      }
    }
  }
}

The caller header lets the agent discover and call public tools as local. It is an unchecked identity, not authentication. Without it, only tools declared with access = "anonymous" are discoverable and callable. See Local MCP for the supported tools and resources.

Run on a server

Install crab on the server and start crab dev -d there as the OS user that will own the service data. Keep its default loopback address. The host has no built-in authentication; its listener also exposes deployment, secret provisioning and host shutdown.

To reach it from your workstation, keep an SSH tunnel open:

ssh -N -L 17777:127.0.0.1:7777 user@your-server

In another terminal, name that endpoint as a context:

crab context add self-hosted http://127.0.0.1:17777
crab --context self-hosted status
crab --context self-hosted deploy --build crab/services/web/markdown
crab --context self-hosted call markdown read '{"url":"https://example.com"}'

The service builds on your workstation and runs on the server. Use http://127.0.0.1:17777/mcp in your agent configuration while the tunnel is open. Anyone with access through the tunnel can manage the whole host.

Keep services running

crab dev -d survives the terminal closing. It does not register the host to start after a machine reboot. For startup at boot, configure your operating system's process supervisor to run crab dev in the foreground as the same OS user, with the same state directory. Stop the detached host before handing it to a supervisor.

The default state directory is ~/.crab/host. --root selects another; keep that path stable across restarts. When the host starts, it restores deployed services and their saved state. Services installed stopped remain stopped.

Use crab --context default stop <service> and start <service> on the hosting machine to pause and resume a service while retaining its data. For host flags, logs, schedules and other commands, see Developing.

Back up and restore

Stop the host before copying its entire state directory. For the default directory, run these commands on the hosting machine as its OS user:

crab dev stop
tar -czf crab-host-backup.tar.gz -C "$HOME/.crab" host
crab dev -d

Use a new archive name for each backup and store it securely: the directory contains service databases, deployed images, host state and secrets.toml. If you set --root, back up that directory instead. A supervised host must be stopped and started through its supervisor.

Restore the archive into an empty state directory with the host stopped, using the same CLI version and root path. For the archive above, extract it under ~/.crab, then start the host and check a known stored value. Starting services also resumes their scheduled work.

Update a service or host

Select the service source revision you want to run and repeat its deploy command. The deployment keeps its state and applies its database migrations. Back up before upgrading a stateful service; redeploying older code does not reverse migrations.

crab upgrade updates the CLI binary. Restart the host to run the new binary, keeping its OS user and root unchanged. See Budgets before increasing a service's workload or resource limits.