Skip to content
AIPDocs
AIP 1.055 pagesGetting started
Release status
DocumentationAIP 1.0Getting startedStart Here

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:

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:

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

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

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:

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:

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.