# CLRK guides

> Task-focused walkthroughs for CLRK workflows.

The guides cover the patterns most teams hit operating CLRK: running and
packaging agents, keeping credentials and budgets out of the agent process,
locking down what an agent can reach, wiring up telemetry, and the recurring
design patterns that show up around auth and state. Pick the one you need;
each guide stands alone.

## Getting started

<LinkCards
  cards={[
    {
      ix: "A · QUICKSTART",
      title: "Run your first agent",
      sub: "Apply a minimal example under `clrk dev`, watch a sandbox spawn, and confirm the API key never reaches the agent.",
      href: "/docs/clrk/guides/run-your-first-agent.md",
    },
    {
      ix: "B · HTTP",
      title: "Claude Code over HTTP",
      sub: "Stand up Claude Code as an internal HTTP service so callers can prompt it without holding the Anthropic API key.",
      href: "/docs/clrk/guides/claude-code-over-http.md",
    },
    {
      ix: "C · PACKAGE",
      title: "Package a custom agent",
      sub: "Turn a Python, Node, or shell script into a CLRK agent: pick the kind, honor the I/O contract, ship an image.",
      href: "/docs/clrk/guides/package-a-custom-agent.md",
    },
    {
      ix: "D · CRON",
      title: "Schedule recurring agents",
      sub: "Run a TaskAgent on a cron schedule with a fixed payload - same agent, same image, different trigger.",
      href: "/docs/clrk/guides/schedule-recurring-agents.md",
    },
  ]}
/>

## Security and isolation

<LinkCards
  cards={[
    {
      ix: "E · CREDS",
      title: "Hide credentials from agents",
      sub: "Keep API keys out of the agent process entirely. The proxy injects them after the request leaves the sandbox.",
      href: "/docs/clrk/guides/hide-credentials-from-agents.md",
    },
    {
      ix: "F · BUDGET",
      title: "Cap LLM spend per agent",
      sub: "Set token budgets that the egress proxy enforces. The agent sees a 429 when over budget; denials land in OTLP.",
      href: "/docs/clrk/guides/cap-llm-spend-per-agent.md",
    },
    {
      ix: "G · EGRESS",
      title: "Lock down agent egress",
      sub: "Default-deny outbound traffic. Allowlist the upstreams agents actually need by hostname, CIDR, and port.",
      href: "/docs/clrk/guides/lock-down-agent-egress.md",
    },
  ]}
/>

## Observability

<LinkCards
  cards={[
    {
      ix: "H · OTLP",
      title: "Send telemetry to OTLP endpoints",
      sub: "Wire CLRK's request logs and traces to your observability backend - per-EgressGateway, OTLP/HTTP, no extra collector.",
      href: "/docs/clrk/guides/send-telemetry-to-otlp.md",
    },
    {
      ix: "I · TRACING",
      title: "Trace requests through agents",
      sub: "Follow a single inbound request from ingress through the sandbox through every LLM call it produced.",
      href: "/docs/clrk/guides/trace-requests-through-agents.md",
    },
    {
      ix: "J · METRICS",
      title: "Query fleet metrics",
      sub: "Read fleet stats and chart data - a typed catalog plus a time-series query over the spans and logs your agents already emit.",
      href: "/docs/clrk/guides/query-fleet-metrics.md",
    },
  ]}
/>

## Patterns

<LinkCards
  cards={[
    {
      ix: "K · AUTH",
      title: "Authenticate users before agents",
      sub: "Front the CLRK ingress with your own auth layer. CLRK does not authenticate inbound traffic itself.",
      href: "/docs/clrk/guides/authenticate-users-before-agents.md",
    },
    {
      ix: "L · STATE",
      title: "Persist state across runs",
      sub: "Keep agent state in external storage so a multi-turn conversation can resume on the next invocation.",
      href: "/docs/clrk/guides/persist-state-across-runs.md",
    },
  ]}
/>