Skip to main content
Version: v2.0

Creating a sandbox

Sandboxes are fully functional Formance Platform development instances that you can use in the design and test phase of your applications. Sandboxes are free and available to all users.

caution

Sandbox environments are not suitable for production use, and intended testing purposes only. Data persistence is not guaranteed, and data may be lost at any time without prior notice. They also enter a sleep mode after a prolonged period of inactivity, which can result in a longer startup time. If you need a production-ready managed cloud environment, please checkout the Production Cloud section.

Prerequisites​

  • Having installed the Formance CLI on your machine
  • Having authenticated fctl against a Formance Cloud account

Creating a Sandbox​

Let's create a Cloud sandbox:

fctl stack create playground
caution

Sandboxes are available for 15 days after their creation. After this period, they are automatically disabled and then completely deleted after 30 days. If you wish to keep your sandbox after it has been disabled, you can request its restoration.

You'll be prompted to select a region for your stack named playground. While multiple regions are available, you will need to select one ending with -sandbox in order to create a free sandbox type stack.

Make sure to let the command a few seconds to complete: this will create and provision a sandbox deployment in your account, and your local fctl will be automatically authorized against it.

You can now check that your sandbox was created successfully by running the following command:

fctl stack list
fctl stack show --name=playground

Enable/Disable modules to your Sandbox​

By default, a stack is composed of modules:

  • Ledger
  • Gateway
  • Payments
  • Auth
  • Stargate

You can enable/disable any modules with:

fctl stack modules enable "wallets"
fctl stack modules disable "wallets"

Obtain availables modules

Depending on the region you are using, you can obtain the list of available modules under Capabilities > MODULE_LIST with:

fctl cloud regions show c9abcd0df-480b-42c4-b5e7-dfght8e7c852                                                                                                                                      ─╯
# Information
ID        | c9abcd0df-480b-42c4-b5e7-dfght8e7c852
Name      | example
Base URL  | https://example.com
Active    | Yes
Public    | Yes
Version   | latest
Last ping | 2024-05-15T14:09:02Z

# Capabilities
MODULE_LIST | auth, gateway, ledger, orchestration, payments, reconciliation, search, stargate, wallets, webhooks

Using your Sandbox​

Now that you have a sandbox ready to be fiddled with, you can use it freely for test and development. The Formance CLI ships with a number of commands that you can use to interact with your sandbox from your terminal:

# let's commit an example transaction to the quickstart ledger,
# increasing the balance of the @foo account by $1.00
fctl ledger send world foo 100 USD/2 --ledger=quickstart

# list transactions in the quickstart ledger
fctl ledger transactions list --ledger=quickstart