# Setup Devnet

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-cardano-foundation-cardano-dev-skills-setup-devnet`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cardano-foundation](https://agentstack.voostack.com/s/cardano-foundation)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [cardano-foundation](https://github.com/cardano-foundation)
- **Source:** https://github.com/cardano-foundation/cardano-dev-skills/tree/main/skills/setup-devnet
- **Website:** https://cardano-foundation.github.io/cardano-dev-skills/

## Install

```sh
agentstack add skill-cardano-foundation-cardano-dev-skills-setup-devnet
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Set Up a Cardano Development Environment

Help the developer set up a local Cardano development network for building, testing, and deploying smart contracts.

## When to use

- Developer wants to run a local Cardano network for development
- Setting up Yaci DevKit or similar local devnet tooling
- Configuring local chain indexers (Kupo, Ogmios) for development
- Establishing a smart contract development workflow (build, deploy, test)
- Connecting to Preview or Preprod public testnets
- Setting up CI/CD pipelines for Cardano projects

## When NOT to use

- Querying mainnet or production chain data (use `query-chain` skill)
- Choosing between SDKs or tools broadly (use `suggest-tooling` skill)
- Writing smart contract logic in Aiken or Plutus
- Wallet integration in a web frontend (use `connect-wallet` skill)

## Key principles

1. **Start local, then move to testnets.** Local devnets give instant feedback. Use Preview/Preprod for integration testing.
2. **Two fast local-devnet options.** Yaci DevKit (standalone CLI tool with a visual explorer) and Evolution SDK devnet (`@evolution-sdk/devnet`, a TypeScript library) are both Docker-based — pick by workflow, not speed.
3. **Automate from day one.** Scripts for devnet startup, contract deployment, and testing save hours.
4. **Match your devnet to your target network.** Ensure protocol parameters and era match what you will deploy to.
5. **Keep test wallets organized.** Use named wallets with known keys for reproducible testing.

## Workflow

### Step 1: Choose the environment

Ask the developer (if not already clear):

- **Are you developing smart contracts or off-chain code (or both)?**
- **Do you need a fully isolated local network or a shared testnet?**
- **What OS are you on?** (Docker availability matters)
- **Do you need governance features (Conway era)?**

| Environment | Best for | Setup time |
|---|---|---|
| **Yaci DevKit** | Smart contract dev, fast iteration, visual block explorer | 5 minutes |
| **Evolution SDK devnet** | TypeScript projects; code-first devnet inside the test suite | 5 minutes |
| **Preview testnet** | Integration testing, shared state, longer-lived deployments | 10 minutes |
| **Preprod testnet** | Pre-production testing, mirrors mainnet parameters | 10 minutes |
| **Custom local cluster** | Advanced scenarios, custom protocol params | 30+ minutes |

### Step 2: Search Bundled Documentation

Search the bundled documentation for relevant content:
- `${CLAUDE_SKILL_DIR}/../../docs/sources/yaci-devkit/` - Yaci DevKit docs
- `${CLAUDE_SKILL_DIR}/../../docs/sources/yaci-store/` - Yaci Store docs
- `${CLAUDE_SKILL_DIR}/../../docs/sources/evolution-sdk/devnet/` - Evolution SDK devnet docs
- `${CLAUDE_SKILL_DIR}/../../docs/sources/cardano-node-wiki/` - Cardano node wiki

### Step 3: Set up Yaci DevKit (CLI tool, visual explorer)

Reference the quickstart guide for detailed commands:

```
File: skills/setup-devnet/references/yaci-devkit-quickstart.md
```

#### Quick setup

1. **Prerequisites**: Docker and Docker Compose installed
2. **Install + start the devnet** (the DevKit ships as a `devkit` script that
   manages the containers and opens the Yaci CLI):
   ```bash
   devkit start                        # opens yaci-cli
   yaci-cli:> create-node -o --start   # create + start a default devnet
   ```
3. **Fund wallets**: `topup  ` inside the CLI (the `devnet:default>` prompt), or pre-fund via `config/env`
4. **Access points**:
   - Yaci Store API (Blockfrost-compatible): `http://localhost:8080/api/v1/`
   - Yaci Viewer (block explorer): `http://localhost:5173`
   - CLI/Admin, wallet, MCP: `http://localhost:10000`
   - cardano-cli against the node: `devkit cli`

#### Configure for your needs

- Set era (Babbage, Conway) for governance testing
- Adjust protocol parameters (min fee, collateral percentage)
- Configure slot length for faster/slower block production
- Enable/disable Plutus cost model overrides for testing

### Step 3b: Set up Evolution SDK devnet (code-first alternative)

If the project is TypeScript-based, `@evolution-sdk/devnet` runs the same local Cardano network as a library — the devnet's genesis, lifecycle, and UTxO queries live in your code and test suite instead of a separate CLI tool. Reference the quickstart:

```
File: skills/setup-devnet/references/evolution-sdk-devnet.md
```

#### Quick setup

1. **Prerequisites**: Docker running, Node.js 18+
2. **Install**: `pnpm add @evolution-sdk/devnet @evolution-sdk/evolution`
3. **Create and start a cluster** in code:
   ```typescript
   import { Cluster } from "@evolution-sdk/devnet";

   const cluster = await Cluster.make({
     clusterName: "dev",
     ports: { node: 3001, submit: 3002 },
     kupo: { enabled: true, port: 1442 },
     ogmios: { enabled: true, port: 1337 },
   });
   await Cluster.start(cluster);
   ```
4. **Fund addresses at genesis** via `shelleyGenesis.initialFunds` — deterministic, no faucet. Genesis UTxOs are not indexed by Kupo; derive them with `Genesis.calculateUtxosFromConfig(...)` and pass via the builder's `availableUtxos`.
5. **Connect a client**: `Client.make(Cluster.getChain(cluster)).withKupmios({ kupoUrl, ogmiosUrl })`.

Choose this over Yaci DevKit when you want the devnet managed from inside integration tests; choose Yaci DevKit for its visual block explorer and Blockfrost-compatible REST API. Both run a standard `cardano-node`, so chain behaviour is identical.

### Step 4: Set up local chain indexers

If your application needs Ogmios/Kupo (e.g. for Evolution SDK's `.withKupmios`),
use the DevKit's built-in services instead of hand-run containers:

```bash
# Inside Yaci CLI
yaci-cli:> enable-kupomios

# Or in the DevKit's config/env
ogmios_enabled=true
kupo_enabled=true
```

Ogmios serves `ws://localhost:1337`, Kupo `http://localhost:1442`. Since DevKit
v0.12.0-beta5, Yaci Store evaluates scripts with `scalus` when Ogmios is not
running — Ogmios is optional for transaction evaluation. For standalone (non-DevKit)
setups, see `docs/sources/ogmios/` and `docs/sources/kupo/`.

### Step 5: Smart contract workflow

#### Aiken build-deploy-test cycle

1. **Build**: `aiken build` compiles validators to UPLC
2. **Generate blueprint**: Produces `plutus.json` with compiled scripts and parameter schemas
3. **Deploy**: Use an off-chain SDK (Mesh, Evolution SDK, PyCardano) to create a transaction referencing the script
4. **Test on-chain**: Submit to local devnet, query results, iterate

```bash
# Typical Aiken workflow
aiken build
aiken check        # Run unit tests
# Then use SDK to deploy to local devnet
```

#### Test structure

- **Unit tests**: Aiken's built-in `test` keyword for validator logic
- **Integration tests**: Off-chain SDK scripts against local devnet
- **Property tests**: Aiken's `fuzz` support for property-based testing
- **End-to-end**: Full workflow tests against Preview testnet

### Step 6: Connect to public testnets

#### Preview testnet

- **Purpose**: Testing new features, faster epoch transitions
- **Faucet**: https://docs.cardano.org/cardano-testnets/tools/faucet/
- **Network magic**: 2
- **Configuration files**: Download from https://book.play.dev.cardano.org/environments.html

#### Preprod testnet

- **Purpose**: Pre-production testing, mirrors mainnet parameters
- **Faucet**: Same faucet site, select Preprod
- **Network magic**: 1
- **Configuration files**: Same source as Preview

#### Getting test ADA

```bash
# Request test ADA from the faucet (web interface or API)
# Provide your testnet address
# Dispenses ~10,000 test ADA per request (same on Preview and Preprod)
# Faucet is rate-limited per address/API key
```

### Step 7: CI integration

#### GitHub Actions example

```yaml
# .github/workflows/cardano-ci.yml
name: Cardano CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Aiken
        uses: aiken-lang/setup-aiken@v1
      - name: Build contracts
        run: aiken build
      - name: Run unit tests
        run: aiken check
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Install Yaci DevKit
        run: npm install -g @bloxbean/yaci-devkit
      - name: Start a devnet
        run: |
          nohup yaci-devkit up --enable-yaci-store &
          # poll http://localhost:8080 until the Yaci Store API answers
      - name: Run integration tests
        run: |
          # Run off-chain integration tests against localhost:8080
```

#### Key CI considerations

- Install the Yaci DevKit npm package and start the devnet in a background step (`yaci-devkit up`)
- Cache Aiken build artifacts
- Run unit tests first (fast), then integration tests (slower)
- Use deterministic wallet keys for reproducible tests
- Clean devnet state between test suites if needed

### Step 8: Troubleshooting common issues

- **Docker not starting**: Check Docker daemon is running, ports not in use
- **Node not syncing**: For local devnet, check logs inside container
- **Transactions failing**: Verify era matches (Babbage vs Conway), check collateral
- **Slow block production**: Adjust slot length in devnet config
- **Out of test ADA**: Re-create devnet (local) or use faucet (testnet)
- **cardano-cli version mismatch**: Match CLI version to node version in the devnet

## References

- `skills/setup-devnet/references/yaci-devkit-quickstart.md` -- Yaci DevKit quickstart guide
- `skills/setup-devnet/references/evolution-sdk-devnet.md` -- Evolution SDK devnet quickstart guide
- Yaci DevKit: https://github.com/bloxbean/yaci-devkit
- Evolution SDK devnet: https://github.com/IntersectMBO/evolution-sdk
- Cardano testnets: https://docs.cardano.org/cardano-testnets/
- Aiken: https://aiken-lang.org
- Ogmios: https://ogmios.dev
- Kupo: https://cardanosolutions.github.io/kupo

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [cardano-foundation](https://github.com/cardano-foundation)
- **Source:** [cardano-foundation/cardano-dev-skills](https://github.com/cardano-foundation/cardano-dev-skills)
- **License:** Apache-2.0
- **Homepage:** https://cardano-foundation.github.io/cardano-dev-skills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-cardano-foundation-cardano-dev-skills-setup-devnet
- Seller: https://agentstack.voostack.com/s/cardano-foundation
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.