Getting Started

From zero to a running LatchGate with a successful end-to-end action execution.

Prerequisites

Linux or macOS. LatchGate uses Unix domain sockets and SO_PEERCRED for production identity. On Windows, use WSL2 or Docker Desktop.
curl (or wget) for the installer.
Docker with the compose plugin — only if using latchgate up --infra (managed Redis + OPA + Squid). Not required for the default embedded mode.

No Rust toolchain needed for evaluation.

1. Install

curl -fsSL https://raw.githubusercontent.com/latchgate-ai/latchgate/main/install.sh | bash

Or:

brew install latchgate-ai/tap/latchgate                    # Homebrew
# Or download a binary from https://github.com/latchgate-ai/latchgate/releases

2. Start the gate

latchgate up

No Docker, Redis, or OPA required. LatchGate starts in embedded mode: SQLite state, in-process policy engine, in-memory replay cache. Expected output:

  LatchGate v0.1.0

  [1/3] Discovering resources...
  [2/3] Preparing state...
  [3/3] Generating config...

  Operator credentials:
    api_key:   lgk-dev-xxxxxxxx
    dpop_jkt:  base64url-thumbprint
    pem:       /tmp/latchgate-up/operator.pem

  ✓  Pre-flight passed

For the full Docker stack (Redis + OPA + Squid + Prometheus):

latchgate up --infra

Verify in another terminal (requires --expose-http 127.0.0.1:3000):

latchgate up --expose-http 127.0.0.1:3000
# then in another terminal:
curl http://localhost:3000/healthz          # {"status":"ok"}
curl http://localhost:3000/v1/actions       # list of registered actions

Press Ctrl+C to stop the gate. If you used --infra and closed the terminal instead, run latchgate down to clean up Docker containers.

3. Launch the operator TUI

In a second terminal:

latchgate tui

The TUI is the primary interface for operating LatchGate. The Dashboard (screen 1) shows gate health, pending approvals, and recent activity. Press ? for context-sensitive keybindings on any screen.

Leave the TUI running — you will see the next step’s action appear in real time on the Audit screen (4).

4. Run your first action

Install the Python SDK:

pip install latchgate

Then run (the gate must have been started with --expose-http 127.0.0.1:3000 for HTTP access):

import asyncio
from latchgate import LatchGateClient

async def main():
    async with LatchGateClient(
        base_url="http://localhost:3000",
        agent_id="my-agent",
    ) as client:
        result = await client.execute("http_fetch", {
            "url": "https://httpbin.org/get",
        })
        print(f"output:  {result.output}")
        print(f"receipt: {result.receipt_id}")

        receipt = await client.get_receipt(result.receipt_id)
        print(f"verified: {receipt.is_fully_successful}")

asyncio.run(main())

Setting agent_id in the constructor enables lazy-connect — the SDK automatically generates a DPoP key pair, obtains a lease, and renews it on the first execute() call. No explicit connect() needed.

What just happened

The SDK ran the full LatchGate pipeline:

The SDK generated an ephemeral P-256 key pair and requested a lease at POST /v1/leases — a short-lived JWT bound to the key via DPoP.
The SDK called POST /v1/actions/http_fetch/execute with a DPoP proof attached.
The kernel validated identity, checked replay protection, resolved the http_fetch action to its immutable manifest, validated the input against the JSON schema, ran OPA policy, reserved budget, and issued a signed ExecutionGrant.
The kernel wrote a pre-dispatch ExecutionIntent to the ledger (crash-safe evidence marker).
A fresh WASM sandbox loaded the http_api.wasm provider. The provider asked the host I/O layer to make an HTTP GET; the host validated the target against allowed_sinks, injected credentials if needed, pinned DNS, and returned the response.
The kernel verified the result (HTTP status verifier), wrote a signed ExecutionReceipt to the evidence ledger in a single transaction with the final audit event, and returned the result to the SDK.

Every step is deterministic. If any step fails, the action is denied.

If you had the TUI open during the SDK call, you saw the event appear on the Audit screen (4) in real time — including the action ID, principal, decision, and timing.

Next: your first custom action

The built-in actions cover common patterns, but most teams need actions for their own APIs. You don’t need to write any provider code — a YAML manifest is enough. See Custom Actions for the walkthrough.

Quick preview: create manifests/my_api_read.yaml, point it at builtin:http_api, declare the URL template and allowed domain, grant it to your principal with latchgate policy grant, restart the gate.

Dev mode vs production

latchgate up (embedded mode) is the fastest path to first value. It runs the gate as a single binary with SQLite state and an embedded policy engine. In this mode:

Identity provider is none (synthetic dev:anonymous principal — DPoP binding still active, but no real caller identity)
Signing keys are ephemeral (not persisted)
Operator DPoP credentials are auto-generated
No egress proxy (kernel-only domain enforcement)

latchgate up --infra adds Docker-managed Redis, OPA, Squid, and Prometheus for HA replay, external policy, and defense-in-depth egress.

Neither is acceptable for production without hardening. For production use latchgate serve with persistent keys and named principals — see Production Quickstart for a 15-minute walkthrough.

Setting up a persistent project

latchgate up is the fastest path for evaluation. For setting up a persistent project (your own config, selected manifests, operator credentials), use latchgate init — either from the CLI or from the TUI’s Setup screen (6 → i):

mkdir my-gate && cd my-gate
latchgate init                                          # interactive wizard
latchgate init --preset coding                # specific preset, skip wizard
latchgate init --preset coding --dev          # local dev mode

The interactive wizard prompts for install location (project-local or user-global) and a preset (eleven built-in options — quickstart, agent, coding, read-only, ops, devops, data, team, lockdown, blank, and permissive). See Presets for details on each.

The wizard generates latchgate.toml, extracts action manifests for the chosen preset, creates operator credentials (P-256 DPoP keypair), and updates .gitignore. The operator API key is displayed once and never logged — save it immediately.

After init, launch latchgate tui to add principals, configure policy, set up secrets, and manage the gate from there.

For the full production setup, see Production Quickstart.

Alternative: Docker Compose

If you prefer running the entire stack in Docker:

docker compose up

This uses the published ghcr.io/latchgate-ai/latchgate:latest image and is fully self-contained.

Next steps

Operator TUI — the primary interface for managing LatchGate day-to-day
Production Quickstart — from zero to production-ready in 15 minutes
Core Concepts — understand actions, grants, receipts
Presets — built-in security postures for common workflows
Agent Sandbox — Linux namespace containment for agent processes
Custom Actions — YAML-only and Rust/WASM custom actions
Policy & Approvals — OPA rules, budgets, human-in-the-loop
Webhooks — push notifications for approvals, denials, and security events
CLI Reference — complete command-line reference