# Quickstart

This guide starts one local AIP daemon, discovers its manifest, invokes a real
capability, and reads the resulting lifecycle state. It uses native HTTP with a
development bearer identity.

## Prerequisites

- Rust 1.88 or newer.
- A checkout of this repository.
- Two terminal windows.

Run every command from the repository root.

## 1. Start `aipd`

In the first terminal:

```sh
cargo run -p aipd -- \
  --bind 127.0.0.1:18080 \
  --service-id agent:aipd:quickstart \
  --native-bearer-token local-development-token \
  --native-principal service:quickstart:client \
  --storage-dir .aipd-quickstart
```

The bearer token establishes the caller identity for native operational routes.
The storage directory preserves action, event, receipt, and replay state across
daemon restarts. This command is appropriate for local development; do not put a
literal token on a production command line.

## 2. Check Readiness

In the second terminal:

```sh
curl --fail http://127.0.0.1:18080/ready
```

Readiness means the daemon can serve its configured runtime. It does not prove
that every external connector is reachable.

## 3. Discover Capabilities

```sh
cargo run -p aipctl -- \
  --native-bearer-token local-development-token \
  manifest fetch http://127.0.0.1:18080
```

The manifest describes the daemon principal, supported profiles, resources, and
callable capabilities. Clients should discover this contract instead of
hard-coding assumptions about a deployment.

## 4. Invoke a Capability

```sh
cargo run -p aipctl -- \
  --native-bearer-token local-development-token \
  action call http://127.0.0.1:18080 \
  cap:aipd:health \
  --input '{}'
```

The response is a native AIP envelope. Its `body.action_result` identifies the
action and reports a terminal status. Generated action and message identifiers
will differ on every new request.

## 5. Inspect Durable State

Copy the returned `action_id`, then run:

```sh
cargo run -p aipctl -- \
  --native-bearer-token local-development-token \
  action status http://127.0.0.1:18080 ACTION_ID \
  --include-result \
  --include-receipts
```

This query reads the runtime's durable operational view. It is independent of
the original HTTP response, which is why operators can diagnose work after a
client disconnects.

## 6. Confirm MCP Compatibility

The same daemon exposes an MCP Streamable HTTP endpoint backed by the same AIP
gateway:

```sh
cargo run -p aipctl -- mcp inspect \
  --url http://127.0.0.1:18080/mcp
```

The output is an AIP manifest projection of the MCP server surface. A real MCP
client can connect to `/mcp`; command-based clients can launch
`aipd --mcp-stdio` instead.

## Stop and Clean Up

Stop the daemon with `Ctrl-C`. Remove `.aipd-quickstart` only when you no longer
need its local action history.

## What to Read Next

- [How AIP Works](how-aip-works.md) explains the complete request path.
- [Installation](installation.md) covers installed binaries and source builds.
- [Capabilities and Contracts](../concepts/capabilities.md) explains discovery
  and safety metadata.
- [Use Native AIP](../guides/use-native-aip.md) covers native envelopes and
  authenticated calls.
- [Use the Rust SDK](../guides/use-rust-sdk.md) covers embedded Rust runtimes.
- [Use AIP through MCP](../guides/use-aip-through-mcp.md) covers MCP clients.
- [Production Deployment](../guides/production-deployment.md) replaces local
  credentials and file storage with production boundaries.