> ## Documentation Index
> Fetch the complete documentation index at: https://silmaril.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick start

> Get access, install an SDK, classify your first request, and handle the verdict.

export const sdkVersions = {
  "typescript": {
    "label": "TypeScript",
    "version": "0.6.3",
    "packageName": "@silmaril-security/sdk",
    "installTarget": "@silmaril-security/sdk@0.6.3"
  },
  "python": {
    "label": "Python",
    "version": "0.6.1",
    "packageName": "silmaril-security-sdk",
    "installTarget": "silmaril-security-sdk==0.6.1"
  },
  "go": {
    "label": "Go",
    "version": "0.6.1",
    "packageName": "github.com/Silmaril-Security/sdk-go/firewall",
    "installTarget": "github.com/Silmaril-Security/sdk-go/firewall@v0.6.1"
  },
  "java": {
    "label": "Java",
    "version": "0.5.0",
    "packageName": "com.silmaril.security:silmaril-security-sdk",
    "installTarget": "com.silmaril.security:silmaril-security-sdk:0.5.0"
  }
};

## Get access

Explore the [core concepts](/docs/concepts/intent-and-outcomes) to understand how Silmaril approaches protection.

Silmaril provisions the API key and endpoints for your deployment. [Book a call](https://cal.com/silmaril/30min) to arrange access. SDKs use the classify endpoint. LiteLLM uses a separate guardrail endpoint.

## Prerequisites

Choose the service that owns inference, tool execution, or orchestration for the system you want to protect. That service creates one firewall client and reuses it.

## Make your first classification

<Steps>
  <Step title="Install the SDK">
    Choose your runtime. Each guide starts with the install command.

    <div className="docs-original">
      <div className="docs-tech-stack">
        <div className="docs-tech-grid">
          <a className="docs-tech-choice" href="/docs/sdk/typescript#install">
            <div className="docs-tech-logo">
              <span className="docs-tech-logo-mark" style={{ color: "var(--competitor-blue)", borderColor: "color-mix(in srgb, var(--competitor-blue) 33%, transparent)" }} aria-hidden="true">TS</span>
              <span><span className="docs-tech-logo-name">TypeScript</span><span className="docs-tech-logo-detail">SDK {sdkVersions.typescript.version}</span></span>
            </div>
          </a>

          <a className="docs-tech-choice" href="/docs/sdk/python#install">
            <div className="docs-tech-logo">
              <span className="docs-tech-logo-mark" style={{ color: "var(--accent-warm)", borderColor: "color-mix(in srgb, var(--accent-warm) 33%, transparent)" }} aria-hidden="true">PY</span>
              <span><span className="docs-tech-logo-name">Python</span><span className="docs-tech-logo-detail">SDK {sdkVersions.python.version}</span></span>
            </div>
          </a>

          <a className="docs-tech-choice" href="/docs/sdk/go#install">
            <div className="docs-tech-logo">
              <span className="docs-tech-logo-mark" style={{ color: "var(--cyber-teal)", borderColor: "color-mix(in srgb, var(--cyber-teal) 33%, transparent)" }} aria-hidden="true">GO</span>
              <span><span className="docs-tech-logo-name">Go</span><span className="docs-tech-logo-detail">SDK {sdkVersions.go.version}</span></span>
            </div>
          </a>

          <a className="docs-tech-choice" href="/docs/sdk/java#install">
            <div className="docs-tech-logo">
              <span className="docs-tech-logo-mark" style={{ color: "var(--cyber-rose)", borderColor: "color-mix(in srgb, var(--cyber-rose) 33%, transparent)" }} aria-hidden="true">JV</span>
              <span><span className="docs-tech-logo-name">Java</span><span className="docs-tech-logo-detail">SDK {sdkVersions.java.version}</span></span>
            </div>
          </a>
        </div>
      </div>
    </div>
  </Step>

  <Step title="Configure the environment">
    Set `SILMARIL_API_KEY` and `SILMARIL_API_URL` in the service environment to the values from [Get access](#get-access).
  </Step>

  <Step title="Classify a request">
    Run the first example in your SDK guide. It creates the client and classifies one user input with the `USER_INPUT` hook. Label tool output with the tool response hook and the tool name.
  </Step>

  <Step title="Handle the result">
    Continue only when the verdict and any applicable governance policy allow the request. Treat a blocked request and a failed call differently. A block is a verdict, while an API or network error means no verdict was returned.
  </Step>
</Steps>

<a id="expected-result" />

## Handle blocks and errors

| SDK | Blocked request | Failed call |
| - | - | - |
| [TypeScript](/docs/sdk/typescript#expected-result) | Returns a result with `prediction: "MALICIOUS"` or `governance.action: "block"` | Rejects with `SilmarilApiError` or a network error |
| [Python](/docs/sdk/python#expected-result) | Raises `FirewallBlockedException` in block mode | Raises `SilmarilApiError` or a network error |
| [Go](/docs/sdk/go#expected-result) | Returns `*firewall.FirewallBlockedError` in block mode | Returns `*firewall.APIError` or a network or context error |
| [Java](/docs/sdk/java#expected-result) | Throws `FirewallBlockedException` in enforcement mode | Throws another exception |

Shadow mode returns results instead of block errors so you can observe would-block decisions before a surface enforces them. Route malicious results with [firewall outcomes](/docs/sdk/outcomes).

## Event contract

Each call sends one complete event. The SDK keeps your `metadata.conversationId` unchanged and adds a `metadata.silmaril.request_id` per event. The `prediction` field is the authoritative verdict. Outcome fields add detail for malicious results.

<a id="where-to-go-next" />

## Next steps

Use [framework integrations](/docs/integrations/frameworks) when a framework owns model execution, or [AI gateway integrations](/docs/gateways/overview) when LiteLLM or Vercel AI Gateway routes your model traffic. For a deployment in your cloud account, see [self-hosting](/docs/deployment/self-hosting).