Zodiac SDK

@zodiac-os/sdk lets you programmatically manage Zodiac account constellations: the Safes, Roles modules, and users that make up your onchain setup. You declare the desired state in TypeScript; the SDK diffs it against the chain and ships it through Zodiac’s review-and-sign flow.

New to constellations? Walk through the end-to-end Constellation as Code tutorial first — it builds a real constellation from zero. This reference covers the SDK surface in detail.

Install


npm install @zodiac-os/sdk

The package ships an executable, zodiac, plus the constellation() and push() functions for use in code.

Authorize a project


zodiac init

Opens a browser tab to sign in, pick an org, and approve a new API key. The key and matching ZODIAC_API_URL are written to .env in your project root, labeled after the directory so you can revoke it later from app.zodiac.eco/admin/api-keys .

Add .env to your .gitignore — it holds your ZODIAC_API_KEY. Never commit it.

Configure contracts

Create a zodiac.config.ts listing the contracts you want to permission, keyed by chain prefix:


import { defineConfig } from '@zodiac-os/sdk/cli/config'
 
export default defineConfig({
  contracts: {
    mainnet: {
      dai: '0x6B175474E89094C44Da98b954EedeAC495271d0F',
    },
  },
})

Pull your org data


zodiac pull

This generates typed data in .zodiac/ with your org’s users and accounts, plus the typed allow kit for the contracts in your config. Add .zodiac/ to your .gitignore.

Entry points

Import	What it provides
`@zodiac-os/sdk`	`constellation()`, `push()`, `c`, `forAll`, `buildAllowKit`, `EVERYTHING`
`@zodiac-os/sdk/cli/config`	`defineConfig` for `zodiac.config.ts`
`@zodiac-os/sdk/allow`	`buildAllowKit`, `EVERYTHING`, chain helpers

Continue to the CLI reference or the Constellation API.