# Starting a Project

Beta status

The Agoric platform is at the beta stage. It has not yet been formally tested or hardened. Do not use for production purposes.

This document shows how to start a new Agoric project. Our demos are called Dapps (decentralized applications), which typically have a browser-based user interface, a public API server, and a contract running on the Agoric blockchain.

Before doing the steps given in this document, be sure you have done the necessary prerequisites specified in Before Using Agoric.

For complete documentation on the Agoric CLI commands (those starting with agoric) used here, see the Agoric CLI Guide.

For starting a local chain with multiple users, making it possible to develop and test multiuser Dapps, also see the Agoric CLI Guide.

Also, for what needs to be done after you modify a project's code, see Development Cycle

Step Action Explanation
1 Go to or open a shell and cd <directory-where-you-want-to-install-Dapp-code> When you initialize your project/Dapp in the next step, its initial code is copied into your current directory (permissions allowing).
2 Run agoric init demoInitializes a Dapp (Decentralized application) project.

init creates a sub-directory with the specified name (demo in this case) in your current directory and copies an existing project's files into it. You can give the project any name you like. This documentation assumes you used demo.

There are optional arguments that let you specify which project you want copied into the specified directory. By default, their values are set to use the Fungible Faucet Dapp we wrote to provide a simple skeleton for a smart contract. To specify a different project, use the optional arguments:
--dapp-template <name> Use the project specified by this <name> as the template copied into your current directory.
--dapp-base <base-url> Look under this directory for the Dapp template.

Learn more about the available dapp templates.

If this doesn't work, use echo $PATH to check that your Agoric CLI install directory is in your $PATH If not, add it to $PATH
3 cd demo Move to the directory where your project (the demo) is located.
4 agoric install Install JavaScript dependencies, which may take a while.
Note: When on a Mac, you must first install Xcode.
5 agoric start --reset
(leave this shell up with the process running)
Start the Agoric VM. --reset discards any prior Agoric state. This creates the vats in which smart contract code runs. The VM continues to run in this shell, making it unusable for running commands.
6 Open another shell, go to your demo directory For the remainder of this table, we call this the deploy shell.

Use the same project directory name and location as you used in Step 2. In this example, we used demo but you may have used a different name in Step 2.
7 In the deploy shell, agoric deploy ./contract/deploy.js ./api/deploy.js Deploy the Dapp on an Agoric VM, install the Dapp's smart contract and web API, as well as JavaScript code that implements the Agoric APIs for writing and implementing contracts.
8 In the deploy shell, (cd ui && yarn start) This starts the demo project's UI development server.
9 Go to a browser and open http://localhost:3000 to see the Dapp. If you used the default values for agoric init in Step 2, you'll see the Fungible Faucet demo Dapp, described in the next cell. If you used the agoric init defaults in Step 2, you'll see our Fungible Faucet Dapp, which lets you get 1000 fungible tokens at a time for free. Receiving the tokens requires interaction with your wallet where your assets are stored (which was started with the Agoric VM).
10 To open your Wallet UI in a browser tab, agoric open Running agoric open --repl in a shell opens a browser tab that shows both the Wallet UI and REPL (Read-Eval-Print Loop).