Built for your workflow.
Connect your tools with the REST API, live WebSocket snapshots, metrics and the stdio MCP server.
The management API
The management listener serves the WebUI, versioned REST endpoints and metrics on port 8080 by default. Authenticate using a session bearer token or a scoped API key. Administrative endpoints also require an admin identity.
The product repository’s OpenAPI document is the authoritative operation and schema reference. Check it for request fields, permission scopes, filters, pagination and response formats.
| Method | Path | Purpose |
|---|---|---|
| GET | /health | Liveness and subsystem checks |
| POST | /api/v1/auth/login | Password sign-in |
| GET | /api/v1/users | List users (admin) |
| GET | /api/v1/sessions | Active sessions |
| GET | /api/v1/transfers | Active and recent transfers |
| GET | /api/v1/audit/events | Filtered audit events |
| GET | /metrics | Prometheus-style exposition |
Make an authenticated request
Set KERVAN_TOKEN to your own bearer session token or API key. Only grant the scopes needed by the calling service. Use HTTPS when the management interface is accessible outside a trusted local environment.
# KERVAN_TOKEN is supplied by your environment
curl -H "Authorization: Bearer $KERVAN_TOKEN" \
http://localhost:8080/api/v1/transfers
curl -H "Authorization: Bearer $KERVAN_TOKEN" \
'http://localhost:8080/api/v1/audit/events?type=file.write'
Follow live snapshots
Connect to /api/v1/ws?types=server,sessions,transfers,audit for WebSocket snapshots. Non-browser clients can send the Authorization header. Browser clients offer auth.<token> alongside kervan.v1 in Sec-WebSocket-Protocol; the server only echoes kervan.v1.
Authentication tokens are not accepted in the WebSocket URL. Keep the connection on a trusted local origin or use WSS for remote deployments.
An MCP interface for local tools
Kervan also includes an MCP server over stdio. It lets a compatible MCP client inspect and administer a local installation using the same configuration. Only stdio transport is currently supported.
Treat a locally configured MCP client as an administrative integration and review the operations it can invoke.
./kervan mcp --config ./kervan.yaml
Current boundaries
The server and site document shipped features separately from planned work. S3 multipart uploads and wider desktop-client interoperability testing remain on the project roadmap. A queryable audit store and database-backed metadata are longer-term directions.
Read the current release notes and contributor guide before relying on newly added behavior. This website is a static guide; examples are not executed against a server in your browser.
Found something to improve? Open a website issue