> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trace-db.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trace-db.com/_mcp/server.

# Quickstarts

Use these examples to configure a client for local runtime development or
invite-only Hosted Alpha access. v0.1.x SDK package names are staged for private
alpha distribution until v1; use install snippets only when your invite or
package credentials include access.

## Environment

For a local runtime:

```bash
export TRACEDB_URL=http://127.0.0.1:8090
export TRACEDB_TOKEN=dev-token
```

For Hosted Alpha, use the hosted API URL and a scoped API key issued by the
control plane:

```bash
export TRACEDB_URL=https://api.trace-db.com
export TRACEDB_TOKEN=<scoped-api-key>
export TRACEDB_DATABASE_ID=<database-id>
export TRACEDB_BRANCH_ID=<branch-id>
```

Do not put hosted API keys in source control, docs, ledgers, issue comments, or
chat output.

These environment variables are a shell convention used by curl examples and any
SDK helper that your private-alpha package documents. Follow the generated SDK's
documented helpers when available, and fall back to explicit constructor or
config fields from the OpenAPI operation shape. Do not assume `fromEnv` /
`from_env` helpers exist unless the owning SDK README for your installed package
shows them for that version.

```ts
import { TraceDBClient } from "@tracedb/sdk";

const client = new TraceDBClient({
  baseUrl: process.env.TRACEDB_URL!,
  token: process.env.TRACEDB_TOKEN,
  maxRetries: 0,
});
```

```python
import os
from tracedb import TraceDB

db = TraceDB(
    base_url=os.environ["TRACEDB_URL"],
    token=os.environ["TRACEDB_TOKEN"],
    max_retries=0,
)
```

```rust
use tracedb_sdk::prelude::*;

let config = ClientConfig {
    base_url: std::env::var("TRACEDB_URL")?,
    token: Some(std::env::var("TRACEDB_TOKEN")?),
    max_retries: 0,
    ..Default::default()
};
let client = ApiClient::new(config)?;
```

## SDK Package Access

If you have private alpha package access, pin the staged v0.1.1 SDKs:

```bash
npm install @tracedb/sdk@0.1.1
pip install tracedb==0.1.1
```

```toml
# Cargo.toml
[dependencies]
tracedb-sdk = "0.1.1"
```

Go SDK support is reserved/candidate and is not a v0.1.1 private alpha install
surface yet.

## HTTP Smoke

The API reference is the source of truth for exact route shapes. A minimal HTTP
readiness check looks like:

```bash
curl -fsS "$TRACEDB_URL/v1/ready" \
  -H "Authorization: Bearer $TRACEDB_TOKEN"
```

For hosted calls, use the SDK or gateway-supported routing metadata so the
request is bound to the authorized tenant, database, and branch. Do not send
`x-tracedb-*` actor headers as a way to impersonate routing state; the hosted
gateway strips client-supplied actor headers and injects trusted metadata from
verified claims.

## Next Steps

* Use [API authentication](/api/authentication) for token and routing rules.
* Use [TraceQL](/query/traceql) and [Native and Bounded GraphQL](/query/native-and-bounded-graphql) for query examples.
* Use [Idempotency and Retries](/operations/idempotency-and-retries) before
  retrying writes or polymorphic operations.