Deploy any folder to Arweave and point an ArNS name at it. One command, permanent hosting.
ario-deploy uploads a build folder (or a single file), writes an Arweave path manifest, and optionally updates an ArNS (Ar.io Name System) record via its ANT (Ar.io Name Token) so the name resolves to the new upload. Available as a CLI and as a GitHub Action.
Deploy your app to Arweave in under a minute:
# Install
npm install -g @ar.io/deploy
# Deploy (interactive — prompts for everything)
ario-deploy deploy
# Or one-liner with a Solana wallet + ArNS name
DEPLOY_KEY=<solana-base58-key> ario-deploy deploy --deploy-folder ./dist --arns-name myapp --sig-type solanaYour app is now permanently live at https://myapp.ar.io.
- Quick Start
- Table of Contents
- Features
- Installation
- Prerequisites
- Commands
- On-Demand Payment
- Bundler service
- Command Options
- Deduplication
- Package.json Scripts
- GitHub Action
- CLI in GitHub Actions
- Claude Code Integration
- Development
- Security & Best Practices
- Troubleshooting
- Contributing
- Dependencies
- License
- Resources
- Turbo SDK Integration: Uses Turbo SDK for fast, reliable file uploads to Arweave
- On-Demand Payment: Pay with ARIO or Base-ETH tokens on-demand during upload
- Arweave Manifest v0.2.0: Creates manifests with fallback support for SPAs
- Optional ArNS Updates: Updates ArNS records via ANT with new transaction IDs
- Automated Workflow: Integrates with GitHub Actions for continuous deployment
- Git Hash Tagging: In CI (GitHub Actions), tags uploaded data items with the deploying commit SHA
- 404 Fallback Detection: Automatically sets
404.htmlas the manifest fallback when present, so deep links into a single-page app resolve instead of 404ing. Override with--fallback-file <path>— an SPA that only buildsindex.htmlcan point at that instead. - Network Support: ArNS updates run against the Solana ARIO programs on
mainnetordevnet, with an optional custom RPC URL - Flexible Deployment: Supports deploying a folder or a single file
- Modern CLI: Built with oclif for a robust command-line experience
- TypeScript: Fully typed for better developer experience
Install the package using pnpm (recommended):
pnpm add -D @ar.io/deployOr with npm:
npm install --save-dev @ar.io/deployOr with yarn:
yarn add --dev @ar.io/deployA deployment uses up to two independent keys:
- Upload key — pays for the upload. Any supported chain (
--wallet/--private-key, or theDEPLOY_KEYenv var; chain selected with--sig-type). - ArNS authority key — only needed when updating ArNS. Always a Solana key that controls the ArNS name and signs the ANT record update (
--arns-wallet/--arns-private-key, or theARNS_KEYenv var).
They can be the same Solana wallet or two different wallets — provide each explicitly.
-
Arweave signer (default): Encode your Arweave wallet key in base64 and set it as
DEPLOY_KEY:base64 -i wallet.json | pbcopy -
Ethereum/Polygon/KYVE signers: Use your raw private key (no encoding needed) as
DEPLOY_KEY. -
Solana signer: Use a base58-encoded secret key as
DEPLOY_KEY, or asolana-keygenid.jsonbyte-array wallet file via--wallet.
Set a base58-encoded Solana secret key as ARNS_KEY, or pass a solana-keygen id.json file via --arns-wallet (or a base58 string via --arns-private-key). This key must control the ArNS name being updated.
Run the deploy command without arguments to be guided through all deployment options:
ario-deploy deployWhen ArNS details aren't supplied via flags, deploy asks whether you want to
update an ArNS name (defaulting to yes) and, if so, prompts for the details. It
will guide you through:
- Whether to update an ArNS name (and which one)
- Wallet method (file, string, or environment variable)
- What to deploy (folder or file)
- Advanced options (optional: undername, TTL, Solana cluster)
Pass --arns-name (or --use-arns) to skip the ArNS confirmation, or use the
upload command for an upload-only run. In a non-interactive environment (CI,
or no TTY) deploy does not prompt — supply everything via flags or
DEPLOY_KEY.
Use flags for faster, scriptable deployments:
# Basic deployment with wallet file
ario-deploy deploy --wallet ./wallet.json
# Deployment with ArNS update (separate upload key + Solana ArNS authority key)
ario-deploy deploy --use-arns --arns-name my-app --wallet ./wallet.json --arns-wallet ./arns-id.jsonDeploy using private key directly:
ario-deploy deploy --private-key "$(cat wallet.json)"Deploy using environment variable:
DEPLOY_KEY=$(base64 -i wallet.json) ario-deploy deploy --deploy-folder ./distDeploy a specific folder:
ario-deploy deploy --wallet ./wallet.json --deploy-folder ./buildDeploy a single file:
ario-deploy deploy --wallet ./wallet.json --deploy-file ./path/to/file.txt--deploy-file overrides --deploy-folder, and the file is uploaded as one
transaction with no manifest — an ArNS name pointed at it resolves straight
to that file, served with its own content type. Useful for a PDF, a dataset, or
a single page. Manifest-only options such as --fallback-file do not apply.
An Arweave path manifest maps each path to a transaction, and a gateway returns
404 for any path the manifest does not list. That is correct for static files
but wrong for a single-page app, whose routes are not files — /settings is
invented by the router and exists nowhere on disk. Without a fallback the root
loads and every deep link 404s.
Manifests have a fallback for exactly this, and ario-deploy sets it
automatically when the build emits a 404.html:
ario-deploy deploy --deploy-folder ./distMost SPA builds do not emit one. Either copy your entry point before deploying:
cp dist/index.html dist/404.html…or name the fallback directly:
ario-deploy deploy --deploy-folder ./dist --fallback-file index.htmlThe file must exist in the deploy folder; a path that is not there fails before anything is uploaded, so a typo costs nothing.
Deep links can appear broken for up to a minute after a redeploy while gateways serve cached 404s from the previous manifest. Confirm with a cache-busting query string (
/settings?x=1) before assuming the deploy failed.
deploy uploads without updating ArNS by default. You can also use the upload command explicitly for the same Turbo upload, dedupe cache, and payment options as deploy, minus ArNS flags:
ario-deploy deploy --wallet ./wallet.json --deploy-folder ./dist
ario-deploy upload --wallet ./wallet.json --deploy-folder ./dist
ario-deploy upload --wallet ./wallet.json --deploy-file ./dist/index.html
DEPLOY_KEY=$(base64 -i wallet.json) ario-deploy upload --deploy-folder ./distDeploy to an undername (subdomain) — the ArNS authority key is a Solana wallet:
ario-deploy deploy --use-arns --arns-name my-app --wallet ./wallet.json --arns-wallet ./arns-id.json --undername stagingDeploy with a custom TTL:
ario-deploy deploy --use-arns --arns-name my-app --wallet ./wallet.json --arns-wallet ./arns-id.json --ttl-seconds 7200Update ArNS on devnet (or against a custom RPC):
ario-deploy deploy --use-arns --arns-name my-app --wallet ./wallet.json --arns-wallet ./arns-id.json --cluster devnet
ario-deploy deploy --use-arns --arns-name my-app --wallet ./wallet.json --arns-wallet ./arns-id.json --rpc-url https://my-rpc.example.comUpload using an Ethereum wallet (file):
ario-deploy deploy --sig-type ethereum --wallet ./private-key.txtUpload using a Solana wallet (base58 private key):
ario-deploy deploy --sig-type solana --private-key "<base58-secret-key>"Use on-demand payment to automatically fund uploads with ARIO or Base-ETH tokens when your Turbo balance is insufficient:
Deploy with ARIO on-demand payment:
ario-deploy deploy --wallet ./wallet.json --deploy-folder ./dist --on-demand ario --max-token-amount 1.5Deploy with Base-ETH on-demand payment (using Ethereum signer):
ario-deploy deploy --sig-type ethereum --private-key "0x..." --on-demand base-eth --max-token-amount 0.1On-Demand Payment Options:
--on-demand: Token to use for on-demand payment (arioorbase-eth)--max-token-amount: Maximum token amount to spend (in native token units, e.g.,1.5for 1.5 ARIO or0.1for 0.1 ETH)
How it works:
- Checks your Turbo balance before upload
- If balance is insufficient, converts tokens to Turbo credits on-demand
- Automatically adds a 10% buffer (
topUpBufferMultiplier: 1.1) for reliability - Proceeds with upload once funded
Token compatibility:
- ARIO: Works with Arweave signer
- Base-ETH: Works with Ethereum signer (Base Network)
Uploads go through a bundler service that accepts signed data items and posts them to Arweave. By default, ario-deploy uses the Turbo API and ArDrive’s production bundler (https://upload.ardrive.io). --uploader sets the base URL of the bundler service to use (scheme + host; typically no path).
| When to use | Example value |
|---|---|
| Default (omit flag) | ArDrive production bundler — same as Turbo CLI defaults |
| Arweave bundler | https://turbo.ardrive.io |
| Development / staging | https://upload.services.ar-io.dev |
| Custom or self-hosted | Your own base URL if it implements the Turbo API |
Examples:
# Deploy using Arweave’s bundler service
ario-deploy deploy --wallet ./wallet.json --deploy-folder ./dist --uploader https://turbo.ardrive.io
ario-deploy upload --wallet ./wallet.json --deploy-folder ./dist --uploader https://turbo.ardrive.ioNotes:
- Turbo billing and signer behavior follow Turbo.
- Use a base URL only (e.g.
https://turbo.ardrive.io), not a path to a specific file or route.
deploy (upload by default, optional ArNS update):
--use-arns: Update an ArNS/ANT record after upload. When ArNS details aren't supplied and you're in a TTY,deployasks by default.--arns-name, -n: The ArNS name to update. Required when using--use-arns; also implies ArNS mode.--cluster, -p: Solana cluster for ArNS updates. Choices:mainnet,devnet. Default:mainnet--rpc-url: Optional Solana RPC URL override for ArNS updates--deploy-folder, -d: Folder to deploy. Default:./dist--deploy-file, -f: Deploy a single file instead of a folder (no manifest is created)--fallback-file: Path, relative to the deploy folder, served for routes the manifest does not list. Defaults to404.htmlwhen the build emits one. See Single-page apps.--undername, -u: ANT undername to update. Default:@--ttl-seconds, -t: TTL in seconds for the ANT record (60-86400). Default:60
Upload key (pays for the upload):
--sig-type, -s: Signer type for the upload key. Choices:arweave,ethereum,polygon,kyve,solana. Default:arweave--wallet, -w: Path to the upload wallet file (JWK for Arweave, private key for Ethereum/Polygon/KYVE,solana-keygenid.jsonfor Solana). Falls back toDEPLOY_KEY.--private-key, -k: Upload private-key string (alternative to--wallet). JWK JSON for Arweave, hex for EVM chains, base58 secret key for Solana.
ArNS authority key (controls the name, signs the update — always Solana):
--arns-wallet: Path to the Solanasolana-keygenid.jsonwallet that controls the ArNS name. Falls back toARNS_KEY.--arns-private-key: Base58 Solana secret key for the ArNS authority (alternative to--arns-wallet). Falls back toARNS_KEY.--on-demand: Enable on-demand payment with specified token. Choices:ario,base-eth--max-token-amount: Maximum token amount for on-demand payment (used with--on-demand)--no-dedupe: Disable deduplication (do not cache or reuse previous uploads)--dedupe-cache-max-entries: Maximum number of entries to keep in the dedupe cache (LRU). Default:10000--uploader: Custom Turbo upload service base URL. See the Bundler service section.
upload (explicit upload without ArNS): accepts --deploy-folder, --deploy-file, wallet/signer flags, --uploader, --on-demand / --max-token-amount, and dedupe flags only.
By default, ario-deploy caches your deployment log to prevent uploading duplicate (unchanged) files. This saves both time and upload costs by reusing existing data on Arweave.
How it works:
- When you deploy, ario-deploy hashes each file in your build
- It checks the local cache for matching hashes from previous uploads
- Files that haven't changed are skipped - the existing transaction ID is reused
- Only new or modified files are uploaded to Arweave
- The cache is stored locally in
.ario-deploy/transaction-cache.json
Disable deduplication:
If you need to force a fresh upload of all files (e.g., for debugging or to ensure a completely new deployment):
ario-deploy deploy --wallet ./wallet.json --no-dedupeLimit cache size:
The dedupe cache uses an LRU (Least Recently Used) eviction strategy. By default, it keeps up to 10,000 entries. You can adjust this limit:
# Keep only the last 1000 file entries
ario-deploy deploy --wallet ./wallet.json --dedupe-cache-max-entries 1000Cache location:
The cache file is stored at .ario-deploy/transaction-cache.json in your project root. You can:
- Add it to
.gitignoreif you don't want to share cache across team members - Commit it to share cached transaction IDs with your team (reduces duplicate uploads)
- Delete it to start fresh:
rm -rf .ario-deploy/
Add deployment scripts to your package.json:
{
"scripts": {
"build": "vite build",
"deploy": "pnpm build && ario-deploy deploy --arns-name <ARNS_NAME>",
"deploy:staging": "pnpm build && ario-deploy deploy --arns-name <ARNS_NAME> --undername staging",
"deploy:devnet": "pnpm build && ario-deploy deploy --arns-name <ARNS_NAME> --cluster devnet",
"deploy:on-demand": "pnpm build && ario-deploy deploy --arns-name <ARNS_NAME> --on-demand ario --max-token-amount 1.5"
}
}These read the upload key from DEPLOY_KEY and the Solana ArNS authority key from ARNS_KEY. Deploy with:
DEPLOY_KEY=$(base64 -i wallet.json) ARNS_KEY=<base58-solana-secret-key> pnpm deployOr with on-demand payment:
DEPLOY_KEY=$(base64 -i wallet.json) ARNS_KEY=<base58-solana-secret-key> pnpm deploy:on-demandThe easiest way to integrate ario-deploy into your CI/CD pipeline is using our official GitHub Action.
- uses: ar-io/ar-io-deploy@v1.0.0
with:
deploy-key: ${{ secrets.DEPLOY_KEY }} # upload key (pays for the upload)
arns-key: ${{ secrets.ARNS_KEY }} # Solana ArNS authority key
arns-name: myapp
deploy-folder: ./distAutomatically deploy preview builds for each pull request. The preview mode auto-generates an undername from the PR number and posts a comment with the preview URL:
name: Deploy PR Preview
on:
pull_request:
types: [opened, synchronize]
jobs:
deploy-preview:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build
- name: Deploy Preview
uses: ar-io/ar-io-deploy@v1.0.0
with:
deploy-key: ${{ secrets.DEPLOY_KEY }}
arns-key: ${{ secrets.ARNS_KEY }}
arns-name: myapp
preview: 'true'
github-token: ${{ secrets.GITHUB_TOKEN }}
deploy-folder: ./distWhen preview is enabled, the action will:
- Auto-generate an undername like
pr-123from the PR number - Post a comment on the PR with the preview URL
- Update the comment on subsequent pushes instead of creating new ones
Deploy to your base ArNS name when pushing to main:
name: Deploy to Production
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build
- name: Deploy to Permaweb
uses: ar-io/ar-io-deploy@v1.0.0
with:
deploy-key: ${{ secrets.DEPLOY_KEY }}
arns-key: ${{ secrets.ARNS_KEY }}
arns-name: myapp
deploy-folder: ./dist- name: Deploy with ARIO on-demand
uses: ar-io/ar-io-deploy@v1.0.0
with:
deploy-key: ${{ secrets.DEPLOY_KEY }}
arns-key: ${{ secrets.ARNS_KEY }}
arns-name: myapp
deploy-folder: ./dist
on-demand: ario
max-token-amount: '2.0'ArNS updates run against the Solana ARIO programs. Provide the Solana ArNS authority key via arns-key (a base58 Solana secret key); the upload is still paid for by deploy-key. Use cluster to target mainnet (default) or devnet, and rpc-url for a custom RPC endpoint.
- name: Deploy and update ArNS
uses: ar-io/ar-io-deploy@v1.0.0
with:
deploy-key: ${{ secrets.DEPLOY_KEY }} # upload key
arns-key: ${{ secrets.ARNS_KEY }} # Solana ArNS authority key
arns-name: myapp
deploy-folder: ./dist
cluster: mainnetBy default, the action caches transaction IDs to avoid re-uploading unchanged files. To disable this:
- name: Deploy without dedupe
uses: ar-io/ar-io-deploy@v1.0.0
with:
deploy-key: ${{ secrets.DEPLOY_KEY }}
deploy-folder: ./dist
no-dedupe: 'true'You can also limit the cache size:
- name: Deploy with limited cache
uses: ar-io/ar-io-deploy@v1.0.0
with:
deploy-key: ${{ secrets.DEPLOY_KEY }}
deploy-folder: ./dist
dedupe-cache-max-entries: '1000'You can also use the CLI directly in your workflows:
Basic Workflow:
name: Deploy to Permaweb
on:
push:
branches:
- main
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v3
with:
version: 9
- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'pnpm'
- run: pnpm install
- run: pnpm deploy
env:
DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}With On-Demand Payment:
name: Deploy to Permaweb with On-Demand Payment
on:
push:
branches:
- main
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v3
with:
version: 9
- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'pnpm'
- run: pnpm install
- run: pnpm build
- name: Deploy with ARIO on-demand
run: ario-deploy deploy --arns-name my-app --on-demand ario --max-token-amount 2.0
env:
DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }} # upload key (pays for the upload)
ARNS_KEY: ${{ secrets.ARNS_KEY }} # Solana ArNS authority key
# Or upload with Ethereum and Base-ETH on-demand payment (upload only; ArNS requires Solana):
# - name: Upload with Base-ETH on-demand
# run: |
# ario-deploy upload \
# --sig-type ethereum \
# --on-demand base-eth \
# --max-token-amount 0.2
# env:
# DEPLOY_KEY: ${{ secrets.ETH_PRIVATE_KEY }}Use Claude Code to deploy your app with natural language. Just say "deploy to ar.io" and Claude handles the rest.
mkdir -p .claude/skills
curl -o .claude/skills/deploy.md https://raw.githubusercontent.com/ar-io/ar-io-deploy/main/examples/claude-skill/deploy.mdThen in Claude Code, say:
- "deploy to ar.io"
- "deploy my app to arweave"
- "set up CI/CD for ar.io deployment"
Claude will build your project, detect the output folder, and run the deploy with the right flags.
- Detects your build folder (
./dist,./build,./out) - Checks for credentials (
DEPLOY_KEYenv var or wallet file) - Installs
@ar.io/deployif not already available - Runs the deployment with appropriate flags
- Reports results — transaction ID, Arweave URL, ArNS URL
See examples/claude-skill/ for the full skill file and customization options.
# Install dependencies
pnpm install
# Build the project
pnpm build
# Run in development mode
pnpm dev
# Run tests
pnpm test
# Run linter
pnpm lint
# Format code
pnpm formatar-io-deploy/
├── src/
│ ├── commands/ # oclif commands
│ │ ├── deploy.ts
│ │ └── upload.ts
│ ├── types/ # TypeScript type definitions
│ │ └── index.ts
│ ├── utils/ # Utility functions
│ │ ├── constants.ts
│ │ ├── signer.ts
│ │ ├── uploader.ts
│ │ └── __tests__/ # Unit tests
│ └── index.ts # Main entry point
├── bin/ # Executable scripts
│ ├── run.js
│ └── dev.js
├── .husky/ # Git hooks
└── dist/ # Build output
- Dedicated Wallet: Always use a dedicated wallet for deployments to minimize security risks
- Wallet Encoding: Arweave wallets must be base64 encoded to be used in the deployment script
- ArNS Name: Required only when updating an ANT/ArNS target undername or root record
- Turbo Credits: Ensure your wallet has sufficient Turbo Credits, or use on-demand payment for automatic funding
- On-Demand Limits: Set reasonable
--max-token-amountlimits to prevent unexpected costs - Secret Management: Keep your
DEPLOY_KEYsecret secure and never commit it to your repository - Build Security: Always check your build for exposed environmental secrets before deployment, as data on Arweave is permanent
- Error: "DEPLOY_KEY environment variable not set": Verify your base64 encoded wallet is set as the
DEPLOY_KEYenvironment variable - Error: "deploy-folder does not exist": Check that your build folder exists and the path is correct
- Error: "deploy-file does not exist": Check that your build file exists and the path is correct
- Error: "ArNS name does not exist": Verify the ArNS name is correct and exists in the specified network
- Upload timeouts: Files have a timeout for upload. Large files may fail and require optimization
- Insufficient Turbo Credits: Use
--on-demandwith--max-token-amountto automatically fund uploads when balance is low - On-demand payment fails: Ensure your wallet has sufficient tokens (ARIO or Base-ETH) and the token type matches your signer (
ariowith Arweave,base-ethwith Ethereum) - Deep links 404 but the homepage loads: The manifest has no
fallback. Emit a404.htmlor pass--fallback-file index.html— see Single-page apps - Deep links still 404 right after a redeploy: Gateways cache the previous manifest's 404s for around a minute. Retry with a cache-busting query string before assuming the deploy failed
- Error: "Fallback file not found in folder":
--fallback-filetakes a path relative to the deploy folder, e.g.index.html, not./dist/index.html
Contributions are welcome! Please follow these guidelines:
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests and linter:
pnpm test && pnpm lint - Commit your changes using conventional commits — the commit type determines the next release, so
fix:for a bug andfeat:for a feature - Push and create a pull request
This project uses Conventional Commits. Commit messages should follow this format:
type(scope): subject
body (optional)
Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
Releases are automated. Merging to main runs
semantic-release, which derives the next
version from the Conventional Commits since the last tag, publishes to npm, and
creates the GitHub Release whose notes serve as the changelog. fix: yields a
patch, feat: a minor, BREAKING CHANGE: a major; chore:, docs:, ci: and
style: release nothing.
Publishing uses npm trusted publishing over GitHub OIDC, so no npm token is stored and every release carries a provenance attestation. There are no credentials to rotate.
- @ar.io/sdk - For ANT operations and ArNS management on Solana
- @ardrive/turbo-sdk - For fast file uploads to Arweave (and signer types)
- @solana/kit - Solana RPC clients and transaction signers for ArNS updates
- bs58 - Base58 encoding/decoding for Solana keys
- @oclif/core - CLI framework
- mime-types - MIME type detection
MIT — © Permanent Data Solutions, Inc.