# Connect local services

> Bring a local Runtime or model service into Kaitoi through a tunnel, distinguish service health from readiness, and stop the resources you actually started.

Source: https://kaitoi.io/docs/cli/connect/
Section: Kaitoi CLI / Local services and recipes
Written for: Users connecting their own machine's services to Studio.
Prerequisites: Kaitoi CLI installed and the relevant local service available; Relay login for the default Kaitoi tunnel, and a Studio account with local integration access
Last reviewed: 2026-10-24

---

Connect makes supported local services reachable through a tunnel. Runtime
executes recipes; Ollama, ComfyUI, and Blender have their own service adapters.
Connecting a service does not install every model or prove it can perform your
intended job. This guide covers CLI **0.9.0**.

## Start Runtime and a tunnel

```bash
kaitoi connect login
kaitoi connect whoami
kaitoi up
```

`up` starts or reuses Runtime on port 8766, then keeps a tunnel running in the
foreground. The default Kaitoi tunnel uses a stored relay login; setting a
platform API token is a separate mechanism and does not replace that login.
The supported tunnel provider choices are `kaitoi` and `cloudflare`.


Studio reaches a tunnel endpoint, which forwards to the machine's Runtime.
Runtime then executes installed recipe code and returns outputs. Relay account
identity and Runtime's machine token serve different purposes. The tunnel can
stop while a separately started Runtime stays running. A direct local Code
model uses its local endpoint without this tunnel.

The machine cutaway follows the example hello-text recipe through recipe.yaml and run.py to outputs/result.txt. The returned local file and the connection process are separate objects.

*Figure: A tunnel connects Studio to a running service; the service and its installed capabilities still matter.*

In Studio, open **Settings → Integrations → Runtime**. This area is available
when your account has local integration access. Check connection status and
**Installed Recipes**, then inspect or install the capability you need.

## Connect a specific service

```bash
kaitoi connect runtime --host localhost --port 8766 --auto-start
kaitoi connect scan
```

Runtime can be reused or started through `--auto-start`. The service commands
`ollama`, `comfyui`, and `blender` accept host/port, provider, `--check-only`, and
`--target auto` or `--target scan`. ComfyUI also accepts `--wrapper-port`; Blender
accepts `--blender-path`. `connect scan` currently discovers Ollama, ComfyUI,
and Blender, **not Runtime**. Use the specific command's `--help` for its port
defaults and prerequisites.

For a custom service, the two command forms use different health options:

```bash
kaitoi tunnel 3000 --name my-app --health /health
kaitoi connect custom 3000 --health-path /health
```

Use one form for the service you intend to expose. A custom tunnel makes that
service reachable; consider what its endpoints allow before starting it.

## Keep credentials and model routes distinct

Runtime's machine bearer token authenticates its local API and forwarding.
It is separate from your platform account token and relay login. Do not replace
one with another when diagnosing a connection.

Code's `local:ollama` provider talks directly to a local model endpoint and
needs no tunnel. Hosted provider `ollama` means Ollama Cloud. A healthy connection
does not prove a model is downloaded, memory is sufficient, a recipe is installed,
or its outputs have passed a real run.

## Stop and restart intentionally

```bash
kaitoi status
kaitoi stop
```

`stop` stops local tunnels and Runtime processes. `restart` stops them and starts
fresh. Interrupting the foreground tunnel with Ctrl+C does **not** guarantee that
the separately launched Runtime stops. Lower-level connection cleanup stops
resources owned by that invocation and preserves pre-existing services. Check
status when you need to confirm that the machine is no longer serving work.