Deploy¶

Strategies only create value when they are running on-chain. Almanak deploys strategy agents into Safe multisig wallets with scoped permissions, so your funds remain under your control while the agent executes autonomously. The Deploy workspace covers the full lifecycle: deploying new agents, monitoring active ones, and managing their state.

Deploy is the third phase of the Almanak Workflow. Strategies from Build arrive here for on-chain execution.

Deployments Overview¶

The Dashboard¶

The deployments dashboard lists all your agents with their current state. Each row shows:

Name: the agent's display name.
Strategy: which strategy it is running.
Chain: the target blockchain.
Status: current execution state.
24h PnL: profit and loss over the last 24 hours.

The top of the page aggregates total wallet value across all active deployments.

Agent Statuses¶

Status	Meaning
Deploying	Wallet and permissions are being set up on-chain
Initializing	Agent is starting up and loading configuration
Running	Agent is actively executing the strategy
Paused	Execution is temporarily halted; can be resumed
Stopped	Agent has been manually stopped
Terminated	Agent has been permanently shut down
Closed	Strategy position has been unwound and finalized
Archived	Agent record is retained for history but no longer active

Agent Details¶

Clicking an agent opens its detail view with several tabs.

Performance¶

The performance tab shows real-time metrics for the running agent: current wallet value, 24-hour PnL, total return since deployment, open positions, and token balances. Charts visualize value over time.

Logs¶

Streaming execution logs show what the agent is doing at each interval. Logs can be filtered by severity and searched by keyword. This is the primary tool for debugging agent behavior.

Transactions¶

A chronological list of on-chain transactions executed by the agent through its Safe wallet. Each transaction links to the relevant block explorer (Etherscan, Arbiscan, Basescan, etc.) for the agent's chain.

Deploy Flow¶

Step-by-Step¶

Deploying a new agent follows a guided wizard:

Select a strategy from the Strategy Library (artifact or GitHub).
Choose or create a Safe wallet on the target chain.
Configure strategy parameters (entry thresholds, risk limits, position sizes).
Grant Zodiac permissions scoping the agent's on-chain access.
Review the full configuration.
Deploy to start the agent.

Wallet Preparation¶

The platform helps the user deploy and configure a Safe wallet for agent execution. When deploying to a new chain, the deployment flow prepares the following user-approved steps:

Computes a predicted wallet address using CREATE2.
Deploys the Safe contract on-chain.
Configures the wallet with the user as the owner and the agent as an authorized module.

Each user gets one Safe wallet per chain. Multiple agents on the same chain share the wallet but operate with independent permission scopes. Ownership and approval authority remain with the user at all times.

Zodiac Permissions¶

Agents do not get blanket access to your wallet. Instead, the platform uses Zodiac Roles to define exactly which smart contracts and functions the agent can call. Permissions are derived from the strategy's configuration and the protocols it interacts with. This means an agent deployed to manage an Aave position can only call Aave-related contracts, not arbitrary addresses.

Prepare Your Strategy for Deployment¶

If you have a strategy built locally (via Almanak Code, your own IDE, or any other tool), follow these steps to make it deployable on Almanak hosting.

Repository Structure¶

Your strategy must live in a GitHub repository with the following structure:

my-strategy/
├── pyproject.toml          # Required: dependencies and run config
├── config.json             # Required: strategy & funding configuration
├── strategy.py             # Required: strategy entry point
└── dashboard/
    └── ui.py               # Optional: custom Streamlit dashboard

config.json¶

config.json declares the strategy's target chain(s) and the tokens it needs to be funded with before it starts running. The platform reads this file during deployment to show funding requirements, validate that your Safe wallet is funded correctly, and guide you through the deploy flow.

Schema:

Field	Type	Required	Description
`chain`	string	Yes (or `chains`)	Target chain for single-chain strategies (e.g. `"arbitrum"`).
`chains`	string[]	Yes (or `chain`)	Target chains for multi-chain strategies. Takes priority over `chain` when both are set.
`trade_size_usd`	number	No	Per-trade sizing hint shown in the deploy UI.
`protocols`	string[]	No	Protocols the strategy interacts with (display only).
`token_funding`	TokenFunding[]	Yes	Tokens the strategy requires at deployment. See below.

Supported chain values¶

Use these exact slugs for the chain and chains fields:

Slug	Chain	Chain ID
`ethereum`	Ethereum	1
`optimism`	Optimism	10
`bnb`	BNB Smart Chain	56
`gnosis`	Gnosis	100
`polygon`	Polygon	137
`sonic`	Sonic	146
`worldchain`	World Chain	480
`mantle`	Mantle	5000
`base`	Base	8453
`arbitrum`	Arbitrum	42161
`avalanche`	Avalanche	43114
`ink`	Ink	57073
`linea`	Linea	59144
`berachain`	Berachain	80094
`scroll`	Scroll	534352
`ethereum-sepolia`	Ethereum Sepolia	11155111
`arbitrum-sepolia`	Arbitrum Sepolia	421614

`token_funding`¶

A structured list declaring exactly which tokens must be funded into your Safe wallet before the strategy's first tick. Each entry is an object:

Field	Type	Required	Description
`symbol`	string	Yes	Token symbol (e.g. `"WETH"`).
`address`	string	Yes	0x-prefixed ERC-20 address.
`chain`	string	No	Defaults to the strategy's chain.
`amount`	string	Yes	Decimal string, non-negative.
`amount_type`	`"token"` \| `"usd"` \| `"percentage"`	Yes	How to interpret `amount`.

amount_type controls the meaning of amount:

token — native token units. "1.0" WETH means 1 ether.
usd — USD value. "5000" means $5,000 worth of the token at funding time.
percentage — a runtime hint consumed by the strategy code itself (e.g. "allocate 50% of an existing balance to this token"). The deploy UI does not treat percentage entries as funding requirements and will not prompt for them at deployment time — use token or usd for anything that must be funded before the strategy's first tick.

Example:

{
  "chain": "arbitrum",
  "trade_size_usd": 1000,
  "protocols": ["uniswap_v3"],
  "token_funding": [
    {
      "symbol": "WETH",
      "address": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
      "amount": "1.0",
      "amount_type": "token"
    },
    {
      "symbol": "USDC",
      "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      "amount": "5000",
      "amount_type": "usd"
    }
  ]
}

token_funding is required

Strategies without a valid token_funding field are blocked from deployment. Entries that are missing any required field, or use an amount_type other than token / usd / percentage, are silently dropped.

pyproject.toml¶

The pyproject.toml must include the Almanak SDK as a dependency and a [tool.almanak.run] section. Here is a minimal example:

[project]
name = "my-strategy"
version = "0.1.0"
dependencies = ["almanak>=2.10.0"]

[tool.almanak.run]
interval = 60

[tool.almanak.run] reference:

Key	Type	Required	Description
`interval`	integer	Yes	Execution interval in seconds (5 -- 3600)

Validation rules

almanak must appear in [project.dependencies] with a version specifier (e.g. almanak>=2.10.0).
interval must be an integer between 5 and 3600.
Git sources in [tool.uv.sources] are not allowed for security reasons.

SDK Version Resolution¶

Deployment uses the Almanak SDK version resolved from your strategy repository dependencies.

Almanak detects the SDK version from the almanak entry in your repository's pyproject.toml [project.dependencies]. During deployment, the strategy environment is built from the repository's dependency files, including the lockfile when present. If your repository allows a broad SDK version range, the version shown in the UI may differ from the version ultimately resolved during deployment.

Pin SDK versions intentionally

Use a clear SDK version constraint in pyproject.toml, and review dependency changes before redeploying after an SDK upgrade. Broad constraints such as almanak>=2.4.0 may allow newer SDK releases with API changes.

Upgrading safely

When upgrading the SDK, verify that your strategy code still matches the APIs available in the target version before redeploying.

Push to GitHub¶

Create a repository on GitHub (public or private).
Push your strategy code.
Ensure the default branch contains a valid pyproject.toml and strategy.py at the root.

Connect GitHub on Almanak¶

Go to the Strategy Library in the Build workspace.
Click Connect GitHub and authorize Almanak to access your repositories.
Your strategy repositories will appear in the library. The platform validates the repository structure automatically and shows the detected SDK version.

Deploy¶

Select your GitHub strategy from the library.
Pick the branch, tag, or commit you want to deploy.
Follow the deploy flow below: choose a wallet, configure parameters, grant permissions, and deploy.

The platform clones your code, builds a Docker image, and starts the agent. This typically takes 30 -- 90 seconds.

GitHub Deploy (V2)¶

Overview¶

The V2 deployment flow connects directly to GitHub repositories. Select a GitHub-linked strategy, pick a branch or tag, name your agent, choose a wallet, and deploy. The platform handles building, validation, and containerization.

Active Deployment Guard¶

Only one active deployment is allowed per strategy at any time. If you attempt to deploy a strategy that already has a running agent, the platform will block the deployment and show the existing active agent. Stop or terminate the current deployment before deploying a new version.

Deploy¶

Deployments Overview¶

The Dashboard¶

Agent Statuses¶

Agent Details¶

Performance¶

Logs¶

Transactions¶

Deploy Flow¶

Step-by-Step¶

Wallet Preparation¶

Zodiac Permissions¶

Prepare Your Strategy for Deployment¶

Repository Structure¶

config.json¶

Supported chain values¶

token_funding¶

pyproject.toml¶

SDK Version Resolution¶

Push to GitHub¶

Connect GitHub on Almanak¶

Deploy¶

GitHub Deploy (V2)¶

Overview¶

Active Deployment Guard¶

`token_funding`¶