---
title: Run your first AIP action
description: Start a local AIP daemon and inspect one complete native action
kind: tutorial
audience: developer
appliesTo: "1.x"
writingStandard: "aip-docs/1.0"
lastReviewedRevision: "d7cce13d1d555644d04a4d73c66c95b113737635"
---

# Run your first AIP action

In this tutorial, you will start one product-neutral AIP daemon on loopback,
discover its manifest, invoke the built-in health capability, and inspect the
durable action state. You will also view the same capability surface through
the MCP compatibility profile.

This path is for developers learning the native request lifecycle. It uses a
literal development bearer token and local file-backed state at source revision
`d7cce13d1d555644d04a4d73c66c95b113737635`. Do not expose this configuration
on a shared network or treat its success as connector-fleet or production
qualification.

## What you will observe

By the end of the tutorial, you will have:

- a ready local `getaip-server` process;
- a manifest containing `cap:aip:server:health`;
- an `aip.core.v1.action_result` with status `completed`;
- a durable lifecycle view for action `act_quickstart_health_001`;
- an AIP manifest projection produced through MCP.

No external product, connector host, PostgreSQL database, or NATS server is
required for this path.

## Prerequisites

You need:

- Rust `1.88` or newer;
- a clean checkout at the source revision above;
- `curl`;
- two terminal windows.

Run every command from the repository root. Complete [Install AIP](installation.md)
first if the pinned checkout or Rust toolchain is not ready.

## 1. Start the daemon

In the first terminal, start `getaip-server` on loopback with an explicit development
identity and a dedicated state directory:

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

Leave this process running. The bearer token authenticates native HTTP calls as
`service:quickstart:client`. The storage directory selects the durable local
runtime and preserves action, event, receipt, and replay state across process
restarts.

Expected result: the command remains running and reports no startup error.

## 2. Check daemon readiness

In the second terminal, request the unauthenticated readiness endpoint:

```sh
curl --fail --silent --show-error http://127.0.0.1:18080/ready
```

Expected result: HTTP `200` with a JSON body whose `status` is `ready`. At this
revision, top-level readiness means the gateway is ready, the runtime worker is
running, every required module is ready, and the NATS listener is running if
NATS was configured as required. It does not prove that a connector replica or
external product is reachable.

## 3. Discover the manifest

Fetch the participant manifest with the same development credential:

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

Expected result: a JSON manifest for `agent:getaip:server:quickstart`. Its capabilities
include `cap:aip:server:health`, and its profiles include the bindings enabled by this
daemon. Discover this contract instead of hard-coding assumptions about an
unfamiliar deployment.

## 4. Invoke the health capability

Submit a native action with a stable tutorial identifier:

```sh
cargo run --locked -p getaip-cli -- \
  --native-bearer-token local-development-token \
  action call http://127.0.0.1:18080 \
  cap:aip:server:health \
  --action-id act_quickstart_health_001 \
  --input '{}'
```

Expected result: an AIP envelope with message type
`aip.core.v1.action_result`. Its `body.action_result` contains
`"action_id": "act_quickstart_health_001"`, `"status": "completed"`, and a
health payload in `output`.

The explicit action ID makes the next query copyable and gives an interrupted
client a stable logical action to resume. For a replay-sensitive mutation, the
caller must also preserve its original idempotency and transaction identities;
the health capability is a low-risk read and requires no approval.

## 5. Read the durable lifecycle view

Query the action independently of the original HTTP response:

```sh
cargo run --locked -p getaip-cli -- \
  --native-bearer-token local-development-token \
  action status http://127.0.0.1:18080 \
  act_quickstart_health_001 \
  --include-result \
  --include-receipts
```

Expected result: the lifecycle view identifies the same action and capability,
reports a terminal lifecycle state and `result_status` of `completed`, and
includes the final result. This read model remains available after the client
that submitted the action disconnects.

## 6. Inspect the MCP projection

The same daemon exposes a Streamable HTTP MCP endpoint backed by the AIP
gateway. Initialize an MCP client and print its AIP manifest projection:

```sh
cargo run --locked -p getaip-cli -- \
  mcp inspect --url http://127.0.0.1:18080/mcp
```

Expected result: JSON describing the MCP peer as an AIP manifest. This confirms
the MCP mapping implemented by the local daemon; it is not an MCP conformance
or independent-client qualification result.

## 7. Verify the complete path

Repeat the two read-only checks that prove the daemon is still ready and the
action remains queryable:

```sh
curl --fail --silent --show-error http://127.0.0.1:18080/ready >/dev/null
cargo run --locked -p getaip-cli -- \
  --native-bearer-token local-development-token \
  action status http://127.0.0.1:18080 \
  act_quickstart_health_001 \
  --include-result >/dev/null
```

Both commands must exit with status `0`. You have now completed discovery,
authenticated submission, execution, durable lookup, and compatibility-profile
inspection for one native AIP action.

## Stop and clean up

Return to the first terminal and stop `getaip-server` with `Control-C`. Keep
`.getaip-server-quickstart` if you want to restart the daemon and inspect the same action.
When that local history is no longer needed, inspect and remove only this
tutorial directory:

```sh
du -sh .getaip-server-quickstart
rm -rf -- .getaip-server-quickstart
```

This deletion removes the tutorial's local action and replay history. It does
not affect Cargo build artifacts or external services.

## What happened internally

`getaip` wrapped the typed health `Action` in an AIP `Envelope` and sent it to
`/aip/v1/messages` with the bearer credential. The daemon bound the request to
the configured principal, validated and executed the built-in handler, stored
the lifecycle records, and returned an `ActionResult`. The later status query
read the stored operational view rather than replaying the action.

The MCP step initialized a compatibility client and projected the daemon's AIP
manifest into MCP concepts. It did not create a second runtime or change the
native action semantics.

## Next steps

- [Run the connector fleet quickstart](connector-fleet-quickstart.md)
- [Understand how AIP works](how-aip-works.md)
- [Learn capabilities and contracts](../concepts/capabilities.md)
- [Use native AIP](../guides/use-native-aip.md)
- [Prepare a production deployment](../guides/production-deployment.md)