Setup

Set up your own plugin project to run the guides' Foundry code. This shared setup provides the starting point; each guide adds the configuration it needs.

Prerequisites: Foundry (curl -L https://foundry.paradigm.sh | bash, then foundryup) and just (brew install just, cargo install just, or your system package manager). Everything below requires just, the template's task runner. It coordinates network config, per-chain addresses, remappings, and verification so you don't have to manage those steps by hand.

1. Start from the template

Clone the Foundry plugin template and initialize it:

git clone --recurse-submodules https://github.com/aragon/osx-plugin-template.git my-plugin
cd my-plugin
just init   # installs dependencies and wires the remappings; `forge build` then works

(For a real project, use GitHub's Use this template to start your own repo and clone that instead.)

OSx is imported directly under @aragon/osx/…. Its shared primitives (conditions, proposals, proxies, and the rest, once the standalone osx-commons library) now live inside osx at @aragon/osx/common/…; there is no separate package to install.

2. Add the plugin you're integrating

The template ships osx only. A guide that installs or drives a specific governance plugin imports that plugin's package (e.g. @aragon/multisig-plugin/…), so add it as a dependency and a remapping. For the multisig guides:

forge install aragon/multisig-plugin
echo '@aragon/multisig-plugin/=lib/multisig-plugin/packages/contracts/src/' >> remappings.txt

For token voting, swap in:

forge install aragon/token-voting-plugin
echo '@aragon/token-voting-plugin/=lib/token-voting-plugin/src/' >> remappings.txt

Guides that touch only OSx core (the DAO, permissions, the framework) need nothing extra.

3. Point at a deployed protocol

The guides run as fork tests against a chain where OSx is already deployed, so they read the protocol's addresses from the environment. The template uses just-foundry, which supplies these addresses for every supported network. Select a network to export them:

just switch sepolia   # or mainnet, base, arbitrum, … (see lib/just-foundry/networks/)
just env              # confirm the resolved values and where each came from

That defines RPC_URL, CHAIN_ID, and the OSx addresses the guides read by name:

Env var	Used by
DAO_FACTORY_ADDRESS	every guide that creates a DAO
PLUGIN_SETUP_PROCESSOR_ADDRESS	install / update a plugin
PLUGIN_REPO_FACTORY_ADDRESS	publish a plugin
MULTISIG_PLUGIN_REPO_ADDRESS, TOKEN_VOTING_PLUGIN_REPO_ADDRESS, …	installing that plugin

These come from the network config (ultimately OSx's own addresses.json). To use a private endpoint, override RPC_URL via .env or vars; see just-foundry.

Put the guide's test under test/fork-tests/ and run it through just-foundry, which loads the network env before Foundry sees it:

just test-fork                          # run the fork tests in test/fork-tests/
just test-fork --match-contract MyGuide # narrow to one

A couple of guides build on a DAO you deployed in an earlier guide and name its address (e.g. DAO). Set those addresses alongside the values above.

Your project is now configured for the guides' fork tests.