Skip to main content

​
serve Command

Start the local fastskill HTTP API server and web UI.

​
Usage

​
Options

​
Examples

​
Basic Server

​
Custom Host and Port

​
Manage skills from the browser (enable writes)

​
Read-only by default

Breaking change: fastskill serve is read-only by default. Read endpoints (list/get skills, project, search, resolve, status, registry browse, the dashboard) are always available; every state-changing endpoint (see the write rows in Core Endpoints) is disabled unless you start the server with --enable-write. When writes are disabled, a request to a write endpoint returns:
Run fastskill serve --enable-write when you want to manage skills (install / update / remove) from the web UI or API on your own machine.

​
Security model

fastskill serve is not a security boundary: it enforces no authentication of its own (no token endpoint; API routes require no Authorization/x-api-key header). It is designed to run local-first on your machine. If you expose the server on a shared or untrusted network, put an authenticating reverse proxy or sidecar in front of it and ensure the app port is not directly reachable — the proxy owns request authentication. Combined with the read-only default, this means an exposed instance without --enable-write cannot be used to mutate state even before the proxy is considered.

​
API Base Path

All application routes are served under the versioned /api/v1/… namespace. Requests to the unversioned /api/… prefix are automatically redirected with HTTP 308 to the corresponding /api/v1/… path, providing a non-breaking migration path for older clients.

​
Health Probes

The server exposes two standard health endpoints immediately after startup:
  • GET /healthz — Liveness probe. Returns HTTP 200 with a JSON body containing the fastskill crate version, e.g. {"status":"ok","version":"0.9.118"}.
  • GET /readyz — Readiness probe. Returns HTTP 200 when the server is ready to accept traffic. Returns HTTP 503 while graceful shutdown is in progress.
These endpoints are suitable for use with container orchestrators (Kubernetes, ECS, Docker).

​
Response Headers

Every /api/v1/… response includes:
  • X-API-Version: v1 — Identifies the API version that served the request.

​
Graceful Shutdown

Sending SIGINT (Ctrl-C) or SIGTERM causes the server to:
  1. Flip /readyz to HTTP 503 so load balancers stop routing new traffic.
  2. Drain in-flight requests to completion.
  3. Exit cleanly with exit code 0.

​
Core Endpoints

Write endpoints (marked write) require --enable-write; without it they return HTTP 403.
Removed: POST /api/v1/skills (create) and PUT /api/v1/skills/{id} (edit) — a skill is a multi-file directory, so it is installed from a source rather than authored via the API. Use the install/update/remove flow (and the CLI fastskill add/update/remove).

​
Redirect Behavior

GET /api/skills → HTTP 308 → GET /api/v1/skills (and similarly for all /api/… paths).

​
See Also