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

# Running an Agent

> Spin up a fleet, register on chain, swap to LLM mode.

The hosted path is the supported flow as of v0.3. Self-host instructions follow at the bottom.

## Create one in the wizard

1. Open `/agents` to click **Create agent**.
2. Fill the wizard:
   * **Name** (e.g. "Mean-reversion BTC trader")
   * **Mandate** (markdown. risk appetite, market prefs, patience rules)
   * **Model**. pick from the 3 tested-working options. See [LLM Strategy](/agents/llm).
   * **Initial funding** (optional, \$X DUSDC)
3. Click **Create**. Your wallet pops to sign a **personal message** (`DarkPool · Create agent · owner=0x… · ts=…`).
4. Backend verifies the signature, mints an ephemeral keypair, AES-GCM encrypts it, signs two sponsored PTBs (`predict::create_manager`, then `balance_manager::new` + `mint_trade_cap` + `agent::register_agent`), and transfers the `AgentOwnerCap` to your wallet.
5. If you provided initial funding, the wizard signs a separate `predict_manager::deposit<DUSDC>` PTB from your wallet (sponsored), then POSTs `/v1/agents/:id/sweep` so the funds land in the agent's PredictManager.
6. The success panel shows the 4 created object IDs. Within 15 minutes (default fleet tick), the agent ticks for the first time.

That's it. No env vars, no `pnpm dev`, no port to open. The hosted fleet polls `/v1/agents/fleet` and starts ticking your agent automatically.

## Per-owner cap

`MAX_AGENTS_PER_OWNER=3` (default). Returns 429 `per_owner_cap` if exceeded.

## Required wallet signature

The signature check is **non-optional**. Backend verifies via `verifyPersonalMessageSignature(@mysten/sui/verify)` with a 5-minute replay window. Without it anyone could `curl`-spam create on any address.

```text theme={"system"}
DarkPool · Create agent · owner=<lowercase addr> · ts=<unix ms>
```

`buildCreateAgentChallenge(addr, ts)` in both `packages/frontend/src/lib/sign-message.ts` and `packages/server/src/routes/agent-fleet.ts` must agree byte-for-byte.

## Fund / Reclaim later

`/agents/:agentId` Owner Controls exposes:

* **Fund agent**. inline amount + Deposit. Builds `predict_manager::deposit<DUSDC>`, signs from owner wallet (sponsored), then POSTs `/v1/agents/:id/sweep`. Updates `last_funded_ms` so auto-disable doesn't fire.
* **Reclaim \$X**. `POST /v1/agents/:id/reclaim`. Server decrypts the agent key, signs `predict_manager::withdraw_all<DUSDC>` and `transferObjects` to a fixed recipient (`ownerAddress` from DB, never user-supplied).
* **Pause / Resume**. owner signs `agent::pause` / `agent::resume` from their wallet. See [Owner Controls](/agents/owner-controls).

## Signal-only mode

A new agent that hasn't been funded ticks but doesn't mint. Open `/agents/:id`, click **Why?** on any settled tick: the reasoning panel shows the model's full decision (`BUY_YES @ $65,000 conf=78` etc.) even though no transaction landed. Fund the agent, and within one tick the next decision becomes a real mint.

## Self-host (single agent, legacy)

Pre-v0.3 path. Still works for power users who want to run their own runtime against their own key:

```bash theme={"system"}
AGENT_KEY=suiprivkey1…                      # signing key
AGENT_PREDICT_MANAGER_ID=0x…                # manager you control
AGENT_STRATEGY=llm                          # or alternate | yes-only | no-only
AGENT_NAME=btc-brain
AGENT_STATUS_PORT=8083                      # 8083+ (resolver owns 8082)
AGENT_TRADE_DUSDC=2
AGENT_TICK_MS=60000
TRADE_AGENT_ID=0x…                          # so the runtime honors on-chain pause
LLM_PROVIDER=groq                           # groq | anthropic | openai | ollama
LLM_API_KEY=gsk_…
LLM_MODEL=llama-3.1-8b-instant
AGENT_PROMPT_FILE=packages/agent-service/prompts/momentum.md
```

```bash theme={"system"}
# Self-host single agent (legacy)
pnpm --filter @darkpool/agent-service dev
```

Update `.env` so the frontend shows it:

```text theme={"system"}
VITE_AGENT_STATUS_URLS=http://localhost:8083/status
```

The hosted fleet does **not** read `AGENT_KEY` or `AGENT_STATUS_PORT`. It reads encrypted rows out of `agent_runtime`.

## Register on chain (CLI path)

If you want a TradeAgent identity outside the wizard (e.g. for a script that mints with its own key):

```bash theme={"system"}
pnpm agent:register --name "BTC Alpha" --execute
# -> TradeAgent: 0x…   Set TRADE_AGENT_ID=0x… in .env
# -> AgentOwnerCap: 0x… (keep safe)
```

With a real V3 TradeCap:

```bash theme={"system"}
pnpm agent:register \
  --name "Delegated BTC Bot" \
  --balance-manager 0xYOUR_V3_BM \
  --trade-cap 0xYOUR_V3_TRADECAP \
  --execute
```

## Docker

Hosted fleet:

```bash theme={"system"}
docker compose --profile agent-fleet up -d
# -> @darkpool/agent-service running fleet.ts on :8084
```

See [Docker Compose](/deployment/docker).