# Install and connect

Start with an explicitly selected real provider account. Install the current preview, connect a host, then use the tested example for your language. Apps keep their own authentication, data and approval decisions.

## 1. Obtain the packages

For JavaScript and TypeScript:

```sh
npm install @agenticdriver/sdk@rc
```

The `rc` channel tracks the current release candidate; your lockfile records the version. The npm `latest` channel remains the earlier stable release. Python uses the reviewed [wheel download](/downloads/python.whl) while PyPI approval is pending. Go and Rust install commands appear with their examples below.

Check [Compatibility](/docs/compatibility) for runtime requirements. Upgrade an execution host before its management clients and preserve existing accounts and grants; [Upgrading](/docs/migrations) explains the required order.

## 2. Connect your provider account

On the execution machine, use a supported native CLI already signed into the
account you intend to use. The qualified Codex adapter requires CLI 0.157.0;
Claude Code 2.1.282 is also qualified. See [provider setup](/docs/providers) for
other adapters and their actual availability. Keep provider sign-in files on
this execution machine.

In a fresh application directory, install the published npm package:

```sh
npm init -y
npm install @agenticdriver/sdk@rc
npx --no-install agenticdriver init --config ./driver/config.json \
  --provider codex --provider-id my-codex --account-id my-codex-account \
  --binary /absolute/path/to/codex \
  --account-directory /absolute/path/to/your/codex-home --management
npx --no-install agenticdriver serve --config ./driver/config.json
```

Replace the two native paths with your selected installation and signed-in
account profile. `init` creates a private driver token and separate operator
credential, and refuses to replace existing configuration. It does not sign in
to a provider or run a model.

In a second terminal, inspect the actual account catalog:

```sh
npx --no-install agenticdriver status --config ./driver/config.json --refresh
```

Download the [AgenticDriver brand brief](/docs/examples/brand-brief.txt)
as `brand-brief.txt`, choose an inexpensive model reported by your account, and run:

```sh
npx --no-install agenticdriver run --config ./driver/config.json \
  --provider my-codex --model YOUR_REPORTED_MODEL < brand-brief.txt
```

This submits a real model request and consumes that account's usage. Review its
answer; seeing a catalog alone does not prove execution. Stop the foreground
host with Ctrl+C when finished. See the [host guide](/docs/host) for service startup.

Applications keep their chosen authentication system. Before connecting real
users or a remote application, configure scoped host access through the
[application-owned auth contract](/docs/remote-access#connect-an-existing-authorization-system)
or the host's [connection flow](/docs/connections). See [Deploy a host](/docs/deployment) for remote setup.
Keep provider API keys and native sign-in on the execution host; clients receive scoped driver
credentials through the chosen connection or application auth flow.
For a host on another computer, follow the [real remote connection guide](/docs/real-connections).

## 3. Connect a language client

The following examples share these application-supplied settings:

| Setting                    | Value                                                                                                       |
| -------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `AGENTICDRIVER_URL`        | The host's HTTPS URL, or loopback HTTP for a local host or SSH tunnel                                       |
| `AGENTICDRIVER_TOKEN_FILE` | A private file containing the scoped driver credential, such as the file created by `agenticdriver connect` |
| `AGENTICDRIVER_PROVIDER`   | An authorized provider instance ID from discovery                                                           |
| `AGENTICDRIVER_MODEL`      | An explicitly selected model reported by that account                                                       |
| `AGENTICDRIVER_INPUT_FILE` | A UTF-8 prompt file, such as the brand brief above or an application-owned example                          |
| `AGENTICDRIVER_CA`         | Optional private-CA PEM certificate; omit for ordinary trusted HTTPS                                        |

Use the application's credential manager to supply and rotate the token file;
never put credentials in URLs, source code or browser storage. Python, Go and
Rust read a current token when constructing this one-shot client. Long-lived
applications must obtain a fresh token before subsequent operations and preserve
the outcome of uncertain requests. JavaScript can resolve credentials for every
request. None of the clients replays model work automatically after expiry.

The [Prometheus validation receipt](/docs/validation/prometheus-real-2026-09-28)
records real requests using installed packages through an SSH connection. The
examples run once with the selected provider/model and do not select an alternate
account or billing route.

### JavaScript and TypeScript

Requires Node 22.13+. Install the package as above. Save the following as
`client.mjs` and run `node client.mjs`. For a private CA, set
`NODE_EXTRA_CA_CERTS` to its certificate path **before starting Node**.
TypeScript imports the same `AgenticClient`; see its [full guide](/docs/javascript).

```javascript
import { readFile } from "node:fs/promises";
import { AgenticClient } from "@agenticdriver/sdk/client";

const client = new AgenticClient({
  url: process.env.AGENTICDRIVER_URL,
  // The application owns this private file and replaces it when tokens rotate.
  token: async () =>
    (await readFile(process.env.AGENTICDRIVER_TOKEN_FILE, "utf8")).trim(),
});
const result = await client.run({
  provider: process.env.AGENTICDRIVER_PROVIDER,
  model: process.env.AGENTICDRIVER_MODEL,
  input: await readFile(process.env.AGENTICDRIVER_INPUT_FILE, "utf8"),
});
console.log(result.text);
```

[Download the example](/docs/examples/client.mjs).

### Python

Requires Python 3.10+. Download the reviewed wheel from the
[0.2.0-rc.2 release](https://github.com/agenticdriver/agenticdriver/releases/tag/v0.2.0-rc.2),
verify its [published checksum](https://github.com/agenticdriver/agenticdriver/releases/download/v0.2.0-rc.2/ASSET-SHA256SUMS), and install it into
the application's own environment:

```sh
python3 -m venv .venv
# Use .venv/Scripts/python.exe on Windows.
.venv/bin/python -m pip install /absolute/path/to/agenticdriver-0.2.0rc2-py3-none-any.whl
.venv/bin/python client.py
```

Save this as `client.py`. The synchronous client has no HTTP-library dependency.
Install the wheel with `[async]` to use `AsyncAgenticClient`.

```python
import os
from pathlib import Path
from agenticdriver import AgenticClient

# Use the private scoped credential issued by the selected AgenticDriver host.
token = Path(os.environ["AGENTICDRIVER_TOKEN_FILE"]).read_text(encoding="utf8").strip()
with AgenticClient(
    os.environ["AGENTICDRIVER_URL"], token,
    ca_file=os.environ.get("AGENTICDRIVER_CA"),
) as client:
    result = client.run(
        provider=os.environ["AGENTICDRIVER_PROVIDER"],
        model=os.environ["AGENTICDRIVER_MODEL"],
        input=Path(os.environ["AGENTICDRIVER_INPUT_FILE"]).read_text(encoding="utf8"),
    )
    print(result["text"])
```

[Download the example](/docs/examples/client.py) ·
[Python streaming, async and cancellation](/docs/python).

### Go

Requires Go 1.22+. Install the published version:

```sh
go mod init example.test/my-driver-client
go get github.com/agenticdriver/agenticdriver/clients/go@v0.2.0-rc.2
go run .
```

This public version installs through the ordinary Go module proxy and checksum
database without GitHub credentials. CI also verifies a locally packed Go module
archive without `replace` directives.
Save the following as `main.go`. Ctrl+C cancels its context without imposing a
run deadline.

```go
package main

import (
	"context"
	"crypto/tls"
	"crypto/x509"
	"fmt"
	"net/http"
	"os"
	"os/signal"
	"strings"

	sdk "github.com/agenticdriver/agenticdriver/clients/go"
)

func must(err error) {
	if err != nil {
		panic(err)
	}
}
func main() {
	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
	defer cancel()
	token, err := os.ReadFile(os.Getenv("AGENTICDRIVER_TOKEN_FILE"))
	must(err)
	prompt, err := os.ReadFile(os.Getenv("AGENTICDRIVER_INPUT_FILE"))
	must(err)
	transport := http.DefaultTransport.(*http.Transport).Clone()
	defer transport.CloseIdleConnections()
	if path := os.Getenv("AGENTICDRIVER_CA"); path != "" {
		cert, err := os.ReadFile(path)
		must(err)
		roots := x509.NewCertPool()
		if !roots.AppendCertsFromPEM(cert) {
			panic("Invalid application CA certificate")
		}
		transport.TLSClientConfig = &tls.Config{RootCAs: roots, MinVersion: tls.VersionTLS12}
	}
	client, err := sdk.NewWithTransport(os.Getenv("AGENTICDRIVER_URL"), strings.TrimSpace(string(token)), transport)
	must(err)
	result, err := client.Run(ctx, sdk.Request{
		Provider: os.Getenv("AGENTICDRIVER_PROVIDER"), Model: os.Getenv("AGENTICDRIVER_MODEL"),
		Input: string(prompt),
	})
	must(err)
	fmt.Println(result.Text)
}
```

[Download the example](/docs/examples/client.go) ·
[Go transport and cancellation](/docs/go).

### Rust

Requires Rust 1.89+. Use the published crate:

```toml
[dependencies]
agenticdriver = "=0.2.0-rc.2"
```

Save the following as `src/main.rs` in a `cargo new` application and run
`cargo run`. This uses the default `blocking` feature. The separate `async`
client supports cancellation by dropping its stream/future; see the full guide
for runtime ownership and feature selection.

```rust
use agenticdriver::{AgenticClient, RunRequest};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let token = std::fs::read_to_string(std::env::var("AGENTICDRIVER_TOKEN_FILE")?)?;
    let ca = std::env::var("AGENTICDRIVER_CA")
        .ok()
        .map(std::fs::read)
        .transpose()?;
    let client = AgenticClient::with_ca_pem(
        &std::env::var("AGENTICDRIVER_URL")?,
        token.trim(),
        ca.as_deref(),
    )?;
    let result = client.run(&RunRequest::new(
        std::env::var("AGENTICDRIVER_PROVIDER")?,
        std::env::var("AGENTICDRIVER_MODEL")?,
        std::fs::read_to_string(std::env::var("AGENTICDRIVER_INPUT_FILE")?)?,
    ))?;
    println!("{}", result.text);
    Ok(())
}
```

[Download the example](/docs/examples/client.rs) ·
[Rust async, features and cancellation](/docs/rust).

## 4. Validate the application workflow

Provider instances belong to the host and have explicit account bindings.
Refresh discovery, inspect the instance's health and capabilities, and select a
model available to that account. A saved native sign-in does not prove model
access or safe SDK integration. The [provider guide](/docs/providers) distinguishes
implemented adapters, recorded real checks and observed native blockers.

There is **no default total run deadline or inactivity timeout**. Add a positive
`idleTimeoutMs` only if your application wants to cancel stalled work; genuine
model/tool progress resets it. Streaming and cancellation are in each language
guide. A cancelled request may already have produced effects, so reconcile its
recorded outcome before retrying. See [inactivity](/docs/timeouts) and
[idempotency](/docs/idempotency).

Next, run the [three installed application recipes](/docs/applications), add
[selected-context retrieval](/docs/retrieval), and connect the existing
[Usagestat backend](/docs/usagestat) for accounting.