Skip to main content

Quick Start

Deploy your first AgentVault agent in under 10 minutes.

Prerequisites
  • Node.js 18+
  • dfx installed and reachable in PATH

No install step is required — npx agentvault@latest fetches the CLI on demand. If you prefer a global install, run npm install -g agentvault and use agentvault in place of npx agentvault@latest below.

1. Initialize your project​

npx agentvault@latest init my-first-agent --template default
cd my-first-agent

This scaffolds a new project directory containing:

  • agent.json — agent metadata (name, version, entry point)
  • index.js — your agent's entry point, with a working task handler
  • .agentvault/ — local project state used by the CLI
  • README.md and .gitignore

Use --template minimal if you only want agent.json and index.js.

2. Start the local ICP runtime​

dfx start --background
dfx ping

3. Package the agent​

npx agentvault@latest package ./

This compiles the agent and prepares deterministic deployment output.

4. Deploy to Local Network​

npx agentvault@latest deploy --network local

Copy the canister ID printed in the command output — you'll need it in the next steps.

5. Verify it's running​

npx agentvault@latest status
npx agentvault@latest info
npx agentvault@latest health

6. Run a task​

npx agentvault@latest exec --canister-id <YOUR_CANISTER_ID> "hello world"

7. Read and back up state​

npx agentvault@latest show --canister-id <YOUR_CANISTER_ID>
npx agentvault@latest backup --canister-id <YOUR_CANISTER_ID>
Pro tip

Automate status, health, and backup checks in your local CI before promoting deployments.

Next Steps​

GoalGuide
Full walkthroughTutorial
Deploy to mainnetDeployment Guide
Manage wallets across chainsWallet Guide
All CLI commandsCLI Reference

Common Commands​

# List all local agents
agentvault list

# View runtime logs
agentvault logs <canister-id>

# Fetch state to restore locally
agentvault fetch --canister-id <canister-id>

# Inspect cycle balance
agentvault cycles balance <canister-id>

Help​

agentvault --help
agentvault <command> --help

See Troubleshooting if a command fails or the output doesn't match what you expect.