The open-source harness for building and operating money agents on Sail Protocol.
Sailor turns any AI coding agent into a builder and operator of money agents. Say start in an empty folder and it takes you to a running agent: strategy, onchain mandate, local automation.
Funds never leave your own separately managed account (SMA). The agent never holds your private key and acts only through a mandate, deterministic onchain permissions checked on every transaction. This makes Sailor Agents safe to run with real capital.
Autonomous money agents for any use case:
- Trading: spot, DCA, rebalancing
- Yield: lending, borrowing, liquidity providing, staking, looping
- Payments: transfers, scheduled moves, operational flows
These are examples, not a boundary. Permissions are arbitrary Solidity, so anything onchain can be expressed as a permission and operated by an agent.
The full trust model, what the contracts enforce versus what stays off-chain, is in the Sail Protocol repo and the whitepaper.
Use Node.js 22+. Run one of these commands in your terminal (or ask your coding agent to run it). Choose one agent; no repository clone or global Sailor installation is needed.
Portfolio: choose your own assets and weights.
npx @sail.money/sailor@latest harbor create portfolio my-portfolio --no-agentOnchain Finance Portfolio: start with the predefined basket and confirm its weights.
npx @sail.money/sailor@latest harbor create onchain-finance-portfolio my-onchain-portfolio --no-agentAccept the npm installation prompt and review the blueprint import when prompted. Use a new folder name if the destination already exists. Sailor downloads the blueprint, verifies it, installs dependencies, and checks the project. --no-agent stops it from launching a second coding-agent session.
Next: open the generated folder in Claude Code or Codex, then send:
Read AGENTS.md and guide me through setting up this portfolio agent.
The coding agent helps you install Foundry, configure an RPC endpoint for each required chain, connect your owner wallet, confirm the strategy, and sign its permissions. It explains gas and registration costs before you fund or sign. Creating the project does not start trading.
If you want Sailor to launch the coding-agent CLI for you, omit --no-agent. The selected CLI must already be installed and on your PATH. For example:
# Codex
npx @sail.money/sailor@latest harbor create onchain-finance-portfolio my-onchain-portfolio
# Or Claude Code (choose this instead)
npx @sail.money/sailor@latest harbor create onchain-finance-portfolio my-onchain-portfolio --agent claudeOpen the scaffold in Claude Code, Cursor, Codex, or any AI coding agent and say start. The agent walks the journey with you, five stations end to end:
- Arrive — set up your self-custodial SMA
- Strategy — define what your agent does
- Mandate — the onchain bounds it runs inside
- Agent — build the tick loop
- Sail — launch, operate, run locally
| Component | What it does |
|---|---|
SDK (@sail.money/sailor/sdk) |
SailorClient, encrypted keyring, EIP-712 signing, dispatch submission, deployment + chain registries, template encoders |
CLI (sailor) |
Everything from sailor init to sailor run: keys, SMA deployment, mandate lifecycle, agent loop, doctor, session control |
Dashboard (sailor ui) |
Local web UI for onboarding, balances, mandate health, activity, and owner signing |
Shipyard (sailor sandbox) |
A simulation sandbox: forks the chains locally so an agent can go through setup → deploy → mandate → run with real liquidity and fake money. Real market state, frozen at the moment the fork starts, against the real deployed contracts: the place to prove a mandate permits what you think it permits, not to backtest a strategy. Fully isolated from live state. Needs Foundry. See docs/shipyard.md |
| Harbor | A library of ready-to-run money agents, published to its own registry. Create an agent with sailor harbor create <slug> instead of building one from scratch. The catalog lives in the Harbor registry. |
| Skills | Set of skills under .agents/skills/, organized by the five stations. See "How the agent is guided" below. |
About the scaffold. sailor init scaffolds your project from scaffold/, and the agent arrives already equipped. The skills are organized by the five stations: setting up (onboarding, project state, the local servers), defining the strategy, constructing the mandate (shared templates plus the full custom-permission lifecycle), building the agent (a typecheck-verified tick-loop skeleton in sailor-agent-build), and operating it unattended through exit (automation, monitoring, tuning, revoke, withdraw, optional notifications and dashboards). The scaffold also ships contracts/, a Foundry workspace for authoring your own IPermission. There is no separate examples directory: authoring patterns live in the sailor-mandates skill, and the canonical agent loop is the verified skeleton in sailor-agent-build. Shipped, self-contained context in every scaffold, not repo furniture.
# bash / zsh (macOS, Linux)
npx @sail.money/sailor init my-agent && cd my-agent && npm install
# or install the CLI first, then init:
npm i @sail.money/sailor ; npx sailor init# PowerShell (Windows)
npx @sail.money/sailor init my-agent ; cd my-agent ; npm installRequires Node.js >= 18. For a global CLI instead: npm install -g @sail.money/sailor.
Follow Start in Claude Code or Codex above for copy-paste commands for both portfolio agents. Browse the Harbor registry for the catalog.
A portable blueprint can create and begin onboarding a complete strategy-specific project in one command:
npx @sail.money/sailor blueprint start ./dca-blueprint.tar.gz my-dcaSailor creates the project, verifies and imports the artifact, installs dependencies, typechecks the delivered runtime, then opens the selected coding agent (Codex by default) in the finished project. The imported agent surface gathers the blueprint's mandate parameters before starting the appropriate Sandbox or live setup UI. Use --agent <executable> to launch another coding-agent CLI, or --no-agent to stop after preparation and open the project yourself.
This verifies artifact integrity, not publisher identity. Read the import plan before approving it; artifact signing and registry trust are separate concerns.
mkdir my-agent && cd my-agent
docker run -d --name agent -P -v "${PWD}:/workspace" sailmoney/sailor
docker exec agent sailor initProject files live on your host via the volume mount; prefix sailor commands with docker exec agent. Full details: docs/docker.md.
The recommended path is agent-driven: open the scaffolded folder in Claude Code, Cursor, Codex, or any AI coding agent and say "start" — the scaffold's skills walk the agent through everything below. The journey is five stations: ARRIVE → STRATEGY → MANDATE → AGENT → SAIL (the sailor-navigator skill is the map). The direct-CLI version of the same journey:
npx @sail.money/sailor init my-agent && cd my-agent && npm install
# ARRIVE — encrypted signing key, owner wallet, and the SMA (a Safe) on-chain
sailor keys generate --type agent-wallet
sailor owner connect
sailor onboard --new-sma
# STRATEGY — make the strategy concrete (one spec per strategy: .sail/strategies/<name>.md;
# then .sail/strategies/strategies.json via `sailor strategy create`). No CLI step for the spec;
# the skills flow runs it as a guided conversation, then every later station reads it.
# MANDATE — register + configure a shared permission singleton (both required;
# a registered-but-unconfigured singleton denies every call):
sailor mandate register --address <singleton> --sma <yourSMA>
sailor mandate configure --address <singleton> --sma <yourSMA> --template SwapPermission --args-file swap-config.json
# AGENT — adapt the tick loop in src/agent.ts, then run a single tick
sailor run --once
# SAIL — launch unattended, then operate (monitor / tune / pause / revoke / withdraw)
sailor service installSee an action get blocked. The fail-closed guarantee is testable before anything is at risk — probe the mandate off-chain with sailor mandate simulate (an eth_call; spends no gas, signs nothing):
sailor mandate simulate --address <templateAddress> \
--target <someContractOutsideYourMandate> \
--calldata 0xa9059cbb... --expect failEach probed call prints a verdict — PASS, FAIL, or REVERT — which is the permission contract's real evaluate() decision, exactly what the kernel consults on a live dispatch. A call outside your mandate shows FAIL (and --expect fail exits non-zero on a mismatch, so you can wire it into CI). At runtime the same protection reads: sailor run skips any planned call no registered permission accepts — logged to the console (skipped: no registered permission authorizes call to <target>) and to .sail/activity.jsonl as dispatch_denied — and if a transaction ever reaches the kernel outside its bounds, the kernel reverts it. Deny by default, at every layer.
Longer walkthrough, including revocation: docs/getting-started.md.
The scaffold follows the open Agent Skills standard. Skills are plain markdown files under .agents/skills/, each with a name, a one-line description, and a station tag. The agent reads the descriptions every turn and loads a skill on demand.
Skills are organized by the five stations, and split into two groups recorded in .agents/skill-registry.json:
- Core skills — the harness, identical across every agent: onboarding and diagnostics, strategy definition, mandate construction, agent building, and unattended operation. These ship with every scaffold and are protected across
sailor update. - Custom skills — what makes this agent: its strategy intake, its agent code, its quotes. A ready-to-run Harbor agent carries its own strategy-specific skills, updated through the Harbor registry.
The sailor-navigator skill is loaded first and carries the project map and the hard safety invariants; the detailed procedures live in the other on-demand skills. Shared templates are registered and configured through the skills because the safe order of operations (register → configure → simulate → verify) is encoded there once, instead of re-derived by every agent. Agents that don't scan skills read sailor-navigator and follow its links to the same files. AGENTS.md holds the user's own project instructions. See docs/templates-and-skills.md and docs/skill-authoring.md.
| Doc | What's in it |
|---|---|
| docs/getting-started.md | Long-form quickstart: install → first SMA → first mandate → first run → revocation |
| docs/cli-reference.md | The full sailor command surface, grouped by workflow |
| docs/sdk-usage.md | SailorClient basics and every SDK subpath export, with examples |
| docs/docker.md | Image, volumes, key handling, dashboard access, headless operation |
| docs/templates-and-skills.md | The shared-template catalog and how skills drive configuration and use |
| docs/skill-authoring.md | How to write a skill: frontmatter, descriptions, references, the core/custom split |
| docs/architecture.md | The Sailor ↔ Sail Protocol boundary: what's onchain vs what the harness does |
| docs/shipyard.md | Shipyard, the simulation sandbox: local forks of the real chains, with fake money |
- The agent signs dispatches; the kernel evaluates the named permission on every call. A permission returning false, reverting, or exceeding its gas cap is a denial — fail-closed.
- The Owner key controls the Safe and is never read by Sailor. Mandate registration requires a deliberate signature from the permission signer on the browser signing page.
- The manager (agent) key is encrypted on disk (geth keystore v3: scrypt + aes-128-ctr) and never transmitted.
- The session can be paused instantly (
sailor session pauseor the dashboard) — revoking dispatch rights without touching Safe custody. - All addresses are EIP-55 normalized before any on-chain call or state write.
Vulnerability reports: see SECURITY.md (the off-chain harness) — smart-contract issues go to the protocol's policy.
The SDK bundles verified deployments for 12 chains — mainnets: Ethereum (1), Base (8453), Arbitrum (42161), Optimism (10), Unichain (130), BSC (56), World Chain (480), HyperEVM (999), MegaETH (4326), Robinhood (4663); testnets: Base Sepolia (84532), Ethereum Sepolia (11155111). Every core contract sits at the same address on every chain via CREATE2 (SailKernel: 0x38b508756c976e876EFF05a29E731A4d348BA6ED), and the seven shared permission templates (swap, swap-no-oracle, borrow, deposit, withdraw, transfer, approve-and-call-batch) are deployed and registered as knownTemplates on all of them. Query it yourself: sailor chains or getSailDeployment(chainId) from the SDK; the canonical record is the protocol repo's deployments/addresses.md.
The Sail Protocol trusted core and its seven shared permission templates underwent an AI security review by Octane; the final analysis identified no critical- or high-severity findings, and the reports live in the protocol repo's docs/security. That review covers the protocol contracts — not this harness. A security review is not a guarantee of correctness; size your exposure accordingly.
Sailor will be continuously enhanced through community participation and feedback — contributions, issue reports, and design discussions are actively welcomed. Start with CONTRIBUTING.md.
MIT © Agentic Finance Inc.