Localnet overview
Localnet behavior, prerequisites, node controls, and resource requirements
A localnet runs TON validator-engine nodes and TON Center v2/v3 services in Docker. It includes consensus and validator elections. Use it for tests that depend on validator, full-node, or indexer behavior without relying on testnet availability.
Requirements and startup
Prerequisites
- Acton 1.2 or later installed.
- An Acton project containing
Acton.toml. - For startup accounts, configured project wallets.
- A running Docker engine with Compose v2. Note that Docker Desktop includes both.
Verify Docker availability
Check that the engine and Compose are available:
docker info
docker compose versionStartup and storage
A full node can take about 20 seconds to start with images already available. Image downloads, additional nodes, and indexer initialization can make startup take longer, including several minutes on a first launch. Wait for node, API, and indexer readiness before sending requests.
Insufficient Docker disk space can interrupt localnet operation. Each node can use up to about 9.3 GiB per day.
Allocate space for all nodes, indexers, snapshot archives, and temporary restore data before startup.
Create and connect
Create a localnet and connect clients through Studio or the standalone CLI.
Localnet controls
- Manage nodes and validators to test synchronization and election participation.
- Inspect network health to diagnose node, API, and indexer failures.
- Change blockchain configuration and generate test traffic.
- Import accounts or edit account state.
- Save snapshots and manage lifecycle.
Timing and API conditions
The --block-time-ms option sets an initial block-time target when creating a localnet. Actual timing depends on consensus and resources.
A localnet has no virtual clock, manual mining, or synthetic API rate-limit and response-delay controls. Use simulator time controls or API conditions for those scenarios.
Last updated on
Control API
Acton-only control routes for local state, wallets, address names, compiler ABI metadata, simulated network conditions, and raw local message injection. These routes are intended for local development tooling and should not be exposed publicly. When simulator is started with --require-auth, these routes require the simulator API token. Rate limiting applies only to /api routes, and response delay applies only to TON Center-compatible API routes; control routes remain available when --rate-limit or --response-delay-ms is enabled.
Manage nodes and validators
Add nodes, control validation, and inspect election membership on a localnet