How to Set Up a Development Environment for Acton on TON

Install Rust, Bun, and system dependencies, then synchronize TON native artifacts with just sync-artifacts and compile the CLI to begin building TON smart contracts with Acton.

Acton is a Rust-based, all-in-one development toolkit for TON smart contracts that combines a command-line interface, the Tolk language compiler, and a Bun-powered documentation UI into a single Cargo workspace. Setting up a complete Acton development environment requires installing cryptographic libraries, the Rust toolchain, and task runners before syncing pre-built VM artifacts and compiling the project. This guide walks through the official setup process defined in the ton-blockchain/acton repository.

Install System Prerequisites

Acton relies on native cryptography libraries and GitHub CLI tools for artifact management. Install the following system packages before proceeding.

macOS:

brew install libsodium libmicrohttpd pkg-config gh

Linux (Debian/Ubuntu):

sudo apt install libsodium-dev libmicrohttpd-dev pkg-config gh

These dependencies support the underlying TON emulator and artifact download utilities referenced in CONTRIBUTING.md 【/cache/repos/github.com/ton-blockchain/acton/master/CONTRIBUTING.md#L96-L105】.

Install Core Toolchains

Rust and Cargo

Install Rust via rustup and reload your environment:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Task Runner and Test Utilities

Acton uses just as its task runner and cargo-nextest for parallel test execution:

cargo install just --version 1.49.0 --locked
cargo install cargo-nextest --version 0.9.133 --locked

Bun for UI Components

The documentation site and test visualization UI require Bun:

curl -fsSL https://bun.sh/install | bash

Clone and Build the Workspace

1. Clone the Repository

git clone https://github.com/ton-blockchain/acton.git
cd acton

2. Synchronize TON Artifacts

Acton links against static native libraries libemulator.a and libtolk.a shipped in the objs/ directory. Download the latest pre-built binaries from the release-objs GitHub release:

just sync-artifacts

This command populates objs/ with VM emulator libraries required by crates/ton-objs/build.rs during compilation 【/cache/repos/github.com/ton-blockchain/acton/master/CONTRIBUTING.md#L31-L38】.

3. Build the UI

Compile the documentation and test explorer assets:

just build-ui

This executes Bun commands defined in the justfile to bundle the Next.js site located in docs/ 【/cache/repos/github.com/ton-blockchain/acton/master/justfile】.

4. Compile the Development Binary

Build the CLI with development optimizations:

just build-dev

This produces ./target/debug/acton, which bundles the core command logic from src/lib.rs and sub-commands including new, build, test, wallet, and script 【/cache/repos/github.com/ton-blockchain/acton/master/src/lib.rs】.

Configure API Access

For mainnet or testnet interactions, create a .env file in the project root:

echo "TONCENTER_MAINNET_API_KEY=your_mainnet_key" > .env
echo "TONCENTER_TESTNET_API_KEY=your_testnet_key" >> .env

Acton automatically loads these variables at runtime when executing deployment scripts 【/cache/repos/github.com/ton-blockchain/acton/master/CONTRIBUTING.md#L74-L82】.

Verify Installation and Run a Sample Project

Confirm the binary functions correctly:

./target/debug/acton --help

Execute the quick-start workflow to validate the entire toolchain:

acton new first_counter --template counter
cd first_counter
acton build
acton test
acton wallet new --name deployer --local --airdrop --version v5r1
acton script scripts/deploy.tolk --net testnet

This sequence scaffolds a counter contract, compiles the Tolk source, runs unit tests, generates a local wallet with testnet funds, and deploys via the Tolk script runner 【/cache/repos/github.com/ton-blockchain/acton/master/README.md#L78-L95】.

Architecture Overview

Understanding the workspace layout helps troubleshoot build issues.

Cargo Workspace – The root Cargo.toml defines a multi-crate workspace grouping the CLI, the Tolk compiler (crates/tolk-compiler), tree-sitter grammars (crates/tree-sitter-tolk), and the TON emulator bindings (crates/ton-objs) 【/cache/repos/github.com/ton-blockchain/acton/master/Cargo.toml】.

Tolk Compiler – Located in crates/tolk-compiler/src/lib.rs, this crate compiles .tolk files into TON VM bytecode and is invoked by the acton script command 【/cache/repos/github.com/ton-blockchain/acton/master/crates/tolk-compiler/src/lib.rs】.

Native Artifacts – Static libraries in objs/ interface with the TON VM emulator. The crates/ton-objs/build.rs script verifies their integrity during the Rust build process.

Summary

• Install system dependencies (libsodium, libmicrohttpd, pkg-config, gh) before attempting compilation.
• Pin specific versions of just (1.49.0) and cargo-nextest (0.9.133) to match the project's CI expectations.
• Run just sync-artifacts to fetch pre-built libemulator.a and libtolk.a libraries required for VM emulation.
• Execute just build-ui to generate Bun-based documentation assets that the CLI serves during test failures.
• Use just build-dev to produce the debug binary at ./target/debug/acton.
• Configure .env with TonCenter keys to enable mainnet and testnet deployments via acton script.

Frequently Asked Questions

What hardware requirements does Acton have?

Acton compiles successfully on standard macOS and Linux machines with at least 4GB of RAM. The Rust build process is memory-intensive when compiling the Tolk compiler and tree-sitter grammars, so 8GB is recommended for smooth development. No GPU is required.

Why are pre-built artifacts necessary instead of compiling from source?

The libemulator.a and libtolk.a archives contain optimized C++ implementations of the TON Virtual Machine and Tolk compiler maintained by the core TON team. Acton links against these static libraries rather than rebuilding them to reduce initial setup time and ensure ABI compatibility with the reference implementation.

Can I use Acton without installing Bun?

Yes, but you will lack the documentation site and automated test visualization UI. The core CLI functions independently. If you skip just build-ui, commands like acton test will still execute, though they may not launch the browser-based failure explorer.

How do I update Acton when new versions release?

Pull the latest changes from the repository, re-run just sync-artifacts to refresh the native libraries, and rebuild with just build-dev. Check Cargo.toml for any new workspace members or dependency changes that might require cargo update.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}