> ## Documentation Index
> Fetch the complete documentation index at: https://acachete.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-Service Onboarding

> Wire up your own wallet against the canonical agent-policy with one command -- no cloning, no deploying your own policy contract.

## Why this doesn't need a new policy contract per user

`agent-policy.configure(wallet, allow_list, cap)` is authenticated by the
**wallet**, not by an admin on the policy contract -- see
[Deploying a Policy](/guides/deploying-a-policy). One `agent-policy`
instance already serves any number of wallets, each with its own
allow-list and cap. `stellar agentgate init` points new wallets at the
[canonical testnet deployment](https://github.com/salazarsebas/teji/blob/main/docs/deployments-canonical.md)
by default, so onboarding is a single local command instead of a contract
deployment.

## One command

```bash theme={null}
npm install -g stellar-agentgate
stellar keys generate --network testnet --fund owner   # if you don't have one yet
stellar agentgate init --owner owner
```

This:

<Steps>
  <Step title="Reads your owner key transiently">
    Via `stellar keys secret owner` -- never written to `.env` or anywhere on disk by this command. Only used in-process for the four setup calls below, then discarded.
  </Step>

  <Step title="Generates and funds a fresh agent-signer">
    A brand-new Ed25519 key, funded via friendbot -- it needs its own balance because `stellar agentgate mcp` later uses it to pay fees on every real tool call.
  </Step>

  <Step title="Deploys a smart wallet, if you didn't pass --wallet">
    Using your owner key as the wallet's initial signer.
  </Step>

  <Step title="Wires the policy gate">
    `add_signer(agent-signer)` → `add_signer(agent-policy)` → `agent-policy.configure(...)` → `update_signer(agent-signer, limits=scoped to the target + policy)` -- the exact sequence [Deploying a Policy](/guides/deploying-a-policy) describes by hand.
  </Step>
</Steps>

It prints an `AGENT_SIGNER_SECRET` (and the wallet/policy IDs) to paste into
your own `.env` -- never `OWNER_SECRET`. That key is deliberately low-value:
it's powerless alone, bounded entirely by the policy's allow-list, so it's a
much smaller trust ask than pasting a real account's secret. See
[Why the raw secret has to be local](#why-the-raw-secret-has-to-be-local).

## Flags

| Flag                                                   | Default                   | Meaning                                                          |
| ------------------------------------------------------ | ------------------------- | ---------------------------------------------------------------- |
| `--owner <identity>`                                   | `owner`                   | A `stellar-cli` identity name (must already exist and be funded) |
| `--wallet <contractId>`                                | *(none -- deploys fresh)* | Reuse an existing smart wallet instead of deploying one          |
| `--policy <contractId>`                                | canonical `agent-policy`  | Point at a different policy instance                             |
| `--target <contractId>`                                | canonical `example-vault` | The contract the agent-signer will be scoped to                  |
| `--allow <method[:capArgIndex]>`                       | `deposit`, `withdraw:1`   | Repeatable; one entry per allowed method on `--target`           |
| `--cap <i128>`                                         | `1000`                    | Rolling-window spend cap                                         |
| `--rpc-url`, `--network-passphrase`, `--friendbot-url` | testnet                   | Override for a different network                                 |

<Note>
  `--target` and `--allow` currently scope to **one** contract per wallet -- matching everything this project's `SignerLimits` helper supports today. Gating multiple contracts from one wallet needs a small encoder addition, not yet built.
</Note>

## Why the raw secret has to be local

A `passkey-kit` smart wallet's `__check_auth` expects a custom-encoded
`Signatures` argument that only a process holding the actual private key
can build -- `stellar-cli`'s OS-keychain-backed secure store can't be used
here because it never exposes the raw key material (see the
[Security Model](/concepts/security-model)). That's true for both the human
owner's key and the agent's key alike -- there's no version of this signing
path where a hosted service or a keychain-backed key could sign on the
agent's behalf instead. What `init` controls is *which* secret ends up on
disk: `OWNER_SECRET` (full authority over the wallet) is fetched, used, and
discarded in-memory; only `AGENT_SIGNER_SECRET` (policy-bounded, replaceable,
low blast radius even if it leaked) gets written anywhere.