Documentation

Lockwave consists of two components:

• Control Plane - The Lockwave web application that stores teams, SSH public keys, hosts, and assignments. It computes the desired state for each host and serves it via a REST API.
• Daemon (lockwaved) - A statically compiled Go binary that runs on each managed host. It polls the control plane over outbound HTTPS, computes the delta between current and desired state, and atomically rewrites the authorized_keys file.

The daemon never opens inbound ports. All communication flows from the daemon to the control plane, never the reverse. This means you don't need to modify firewall rules or open SSH tunnels.

The install script downloads the correct binary for your architecture, creates a systemd service, and registers the host with the control plane.

Supported Platforms

• Linux (amd64, arm64)
• macOS / Darwin (amd64, arm64)
• FreeBSD (amd64)

Verifying Installation

systemctl status lockwaved
journalctl -u lockwaved -f

The host should appear in your dashboard with a "healthy" status within 60 seconds.

Lockwave supports two key types:

• ed25519 - Default and recommended. Smaller, faster, and more secure than RSA.
• RSA 4096 - For legacy compatibility with older SSH clients or servers.

Keys can be generated server-side (the private key is shown once and never stored) or imported by pasting your existing public key.

Keys are scoped to teams. Visibility options:

• Personal - Only visible to the key owner
• Shared - Visible to team admins and owners

Assignments map SSH keys to hosts and OS users. They define the desired state of each authorized_keys file.

Create an assignment to grant access. Delete it to revoke. Changes propagate to all affected hosts on the next daemon sync cycle.

Sync intervals depend on your plan: Free (5 min), Standard (2 min), Business (1 min), Enterprise (30 sec).

The Lockwave REST API lets you manage all resources programmatically. All endpoints are versioned under /api/v1/.

Authentication

Create an API token from your profile settings. Include it as a Bearer token in every request:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Accept: application/json" \
     https://lockwave.io/api/v1/ssh-keys

Team Context

All endpoints operate in the context of a team. By default, your current team is used. To target a different team, pass the X-Team-Id header:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "X-Team-Id: YOUR_TEAM_UUID" \
     -H "Accept: application/json" \
     https://lockwave.io/api/v1/hosts

Base URL

https://lockwave.io/api/v1/

Endpoints

User & Teams

SSH Keys

Hosts

Host Users

Enrollment & Credentials

Assignments

Break Glass

Audit Events

Reports

Request Examples

List SSH Keys

curl -s -H "Authorization: Bearer $TOKEN" \
     -H "Accept: application/json" \
     https://lockwave.io/api/v1/ssh-keys

Create a Host

curl -s -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{"display_name":"web-01","hostname":"web-01.example.com","os":"linux","arch":"amd64"}' \
     https://lockwave.io/api/v1/hosts

Create an Assignment

curl -s -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{"host_user_id":"HOST_USER_UUID","ssh_key_id":"SSH_KEY_UUID"}' \
     https://lockwave.io/api/v1/assignments

Cursor Pagination

All list endpoints use cursor-based pagination. Results include next_cursor and prev_cursor in the meta object. Pass ?cursor=VALUE to navigate pages. Default page size is 25 items.

Error Handling

All errors return a consistent JSON format:

{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."]
  }
}

Rate Limiting

The API allows 60 requests per minute per authenticated user. Rate limit status is returned in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57

When the limit is exceeded, a 429 Too Many Requests response is returned with a Retry-After header indicating seconds to wait.

Lockwave exposes a Model Context Protocol (MCP) server so AI assistants and agents can interact with your team's data—hosts, SSH keys, assignments, break-glass, reports, and audit—using tools, resources, and prompts.

Endpoint

POST http://lockwave.io/mcp/lockwave

All MCP JSON-RPC requests (initialize, tools/list, tools/call, resources/read, prompts/get, etc.) are sent as POST to this URL.

Authentication

Use the same API token as the REST API. Send it as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Your user must have a current team set (the same team context as the REST API). All tools and resources are scoped to that team.

Capabilities

The Lockwave MCP server provides:

• Tools — List and get hosts, SSH keys, assignments; create or delete assignments; list/activate/deactivate break-glass events; list or request compliance reports; list audit events.
• Resources — Static docs (overview, team summary) and URI-templated resources for host and key details (lockwave://hosts/{id}, lockwave://keys/{id}).
• Prompts — Reusable prompts to summarize the team or guide adding a key to a host.

Supported MCP clients

Add the Lockwave MCP server in any of these clients using the endpoint and Bearer token above.

Client-specific setup

Protocol reference

Configure your MCP client with the URL above and add the Authorization: Bearer YOUR_TOKEN header. For protocol details, see the Model Context Protocol specification.

Lockwave's security model is built on four principles:

• Outbound-only - The daemon only makes outbound HTTPS requests. No inbound ports, no SSH tunnels.
• No private keys - We only store public keys. Private keys are generated and delivered once, then discarded.
• Atomic writes - POSIX file locking and rename prevent corrupted authorized_keys files.
• Immutable audit - Every action is logged in an append-only log. Break-glass, drift events, and credential rotations are all recorded.

Report security issues to security@lockwave.io.