Setting Up Fluent Sandbox with Claude Code

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

How-to Guide

Extend

Author:

Jarryd Zankovic

Changed on:

5 Mar 2026

Key Points

This guide helps SI partners and customer developer set up a Fluent OMS sandbox using Claude Code in Terminal mode.
You’ll install the reference modules (Core, Fulfillment, Order, Inventory) and load B2C sample data with Claude Code as an AI development partner.
Claude Code will read local Fluent docs and propose CLI commands. You approve each phase before anything runs.
Total human effort is ~45 minutes, plus a required 10-minute catalogue cache wait during sample data install.

Steps

Prerequisites

Required Fluent Documentation

Claude Code must be able to read Fluent documentation from your local machine. Download the required Markdown docs and place them in a /docs folder inside your project directory.

Document	Purpose	.md File
Getting Started with the Fluent CLI	CLI installation and basic usage	Download
Bootstrap an account using the Fluent CLI	Account setup procedures	Download
Set up a new Account with Reference Modules and B2C Sample Data	Module installation sequence	Download
What is a Module	Understanding Fluent's module architecture	Download
Fluent CLI Reference	Command reference	Download
API Authentication	Authentication flow understanding	Download

Environment Requirements

Requirement	Version/Details
Node.js	>= 20.0.0 and < 23.0.0
npm	>= 10.5.0
Git	Any recent version
OS	Terminal access required (macOS, Linux, or Windows with PowerShell)
Claude Code	Terminal CLI
Claude Model	Opus 4.5 (recommended)

Fluent Sandbox Credentials

You will receive these values when your Fluent sandbox is provisioned (from your Fluent contact or provisioning email)

Account ID (e.g., `YOURACCOUNTID`)
Client ID (typically same as Account ID)
Client Secret (UUID format)
Admin Username (typically `youraccount_admin`, lowercase)
Admin Password

Create Project Directory

Create a dedicated folder for your Fluent sandbox project:macOS/Linux:

1mkdir -p ~/Code/FluentSandbox_YOURNAME
2cd ~/Code/FluentSandbox_YOURNAME

Windows (PowerShell):

1mkdir -Force ~\Code\FluentSandbox_YOURNAME
2cd ~\Code\FluentSandbox_YOURNAME

Expected result: you are inside the new project folder in Terminal.

Initialize Git with Security Protection

Initialize a Git repository and create a `.gitignore` file to protect sensitive credentials:Note: Run all commands from within your project folder root. The `.gitignore` file is created directly in the project root, no additional folder structure is required at this stage.macOS/Linux:

1git init
2echo ".env" > .gitignore
3echo ".env.local" >> .gitignore
4echo "*.key" >> .gitignore
5echo "*.pem" >> .gitignore
6echo "node_modules/" >> .gitignore
7echo ".DS_Store" >> .gitignore
8echo "*.log" >> .gitignore
9git add .gitignore
10git commit -m "Initial commit with gitignore"

Windows (PowerShell):

1git init
2@(".env", ".env.local", "*.key", "*.pem", "node_modules/", "*.log") | Out-File -FilePath .gitignore -Encoding UTF8
3git add .gitignore
4git commit -m "Initial commit with gitignore"

Why this matters: your `.env` contains credentials. If `.env` is ever committed to git, treat it as a credential leak and rotate secrets immediately.

Create Credentials File

Create a `.env` file to store your Fluent sandbox credentials:macOS/Linux:

1cat > .env << 'EOF'
2ACCOUNT_ID=YOUR_ACCOUNT_ID
3CLIENT_ID=YOUR_CLIENT_ID
4PASSWORD=YOUR_PASSWORD
5CLIENT_SECRET=YOUR_CLIENT_SECRET
6FLUENT_USERNAME=your_username_admin
7EOF

Windows (PowerShell):

1@"
2ACCOUNT_ID=YOUR_ACCOUNT_ID
3CLIENT_ID=YOUR_CLIENT_ID
4PASSWORD=YOUR_PASSWORD
5CLIENT_SECRET=YOUR_CLIENT_SECRET
6FLUENT_USERNAME=your_username_admin
7"@ | Out-File -FilePath .env -Encoding UTF8
8```

Important:

Windows users: Ensure the `.env` file uses UTF-8 encoding (without BOM) and Unix-style line endings (LF). Incorrect encoding can cause authentication failures.
Replace placeholder values with your actual Fluent sandbox credentials
Use `FLUENT_USERNAME` instead of `USERNAME` to avoid conflicts with system environment variables on macOS
Username should be lowercase (e.g., `jarrydz_admin` not `JARRYDZ_admin`)

Add Fluent Documentation

Place your Fluent documentation files in the project directory. Recommended structure:

1~/Code/FluentSandbox_YOURNAME/
2├── .env                    # Credentials (gitignored)
3├── .gitignore              # Protection rules
4├── docs/                   # Fluent documentation
5│   ├── Getting Started with the Fluent CLI.md
6│   ├── Bootstrap an account using the Fluent CLI.md
7│   ├── Set up a new Account with Reference Modules.md
8│   ├── What is a Module.md
9│   ├── Fluent CLI Reference.md
10│   └── API Authentication.md

Expected result: your /docs folder contains the required .md files, and you can open them locally.

Verify Security Configuration

Before proceeding, verify that your `.env` file is protected:

1git status

Expected result: The `.env` file should NOT appear in the output. If it does, fix `.gitignore` before continuing.

Launch Claude Code

Open Claude Code in Terminal mode within your project directory:

1cd ~/Code/FluentSandbox_YOURNAME
2claude

Note:

This guide uses Claude Code in Terminal CLI mode with the Opus 4.5 model. Other interfaces (VS Code extension, Cursor) may have limitations for system-level operations like CLI installation.

Execute Setup Prompt

Copy and paste the following prompt into Claude Code:

1CONTEXT:
2Set up Fluent Order Management from scratch in a sandbox environment.
3
4PROJECT DETAILS:
5- Location: [CURRENT DIRECTORY]
6- Environment: Sandbox
7- Credentials: Stored in .env file (never display these)
8- Documentation: [PATH TO YOUR DOCS FOLDER]
9
10CURRENT STATE:
11- Git initialised with .env protected
12- .env file contains: ACCOUNT_ID, CLIENT_ID, PASSWORD, CLIENT_SECRET, FLUENT_USERNAME
13- CLI not yet installed
14- Node may or may not be installed
15
16END GOAL:
17Working Fluent OMS sandbox with:
181. Core module
192. Fulfilment module
203. Order module
214. Inventory module
225. Sample B2C data loaded
236. All users with correct context access
24
25SECURITY REQUIREMENTS:
26- Never display .env file contents
27- Reference environment variables as ${VARIABLE_NAME} (never print values)
28- Explain each command before execution
29- Flag destructive operations
30- Wait for approval before proceeding
31
32SETUP SEQUENCE:
33Execute these phases in order, waiting for approval at each phase:
34
35PHASE 1: Prerequisites Check
36- Verify Node.js >= 20.0.0 < 23.0.0
37- Verify npm >= 10.5.0
38- Install/upgrade if needed
39
40PHASE 2: CLI Installation
41- Install Fluent CLI globally
42- Verify with `fluent --version`
43
44PHASE 3: Authentication
45- Create CLI profile using .env credentials
46- Profile name: cli-b2c
47- Use FLUENT_USERNAME variable (not USERNAME, to avoid system conflict)
48- Username should be lowercase
49- Verify authentication succeeds
50
51PHASE 4: Create Retailer
52- Create retailer named "b2c"
53- Email: b2c@test.com
54- Note the Retailer ID (should be 1)
55
56PHASE 5: Generate Configs
57- Generate Order module config
58- Generate Inventory module config
59- Populate with documentation defaults
60
61PHASE 6: Install Modules (Order Matters)
621. Core module
632. Fulfilment module
643. Order module (with config)
654. Inventory module (with config)
66
67PHASE 7: Load Sample Data
681. Generate and install B2C Sample Data module
692. WAIT 10 MINUTES (required for catalogue cache)
703. Generate and install B2C Sample Inventory module
71
72PHASE 8: Configure User Access
73- Ensure account admin has retailer context roles
74- Add ADMIN and GRAPHQL roles to retailer context
75- This fixes blank screen issue on login
76
77PHASE 9: Verification
78- List installed modules
79- Confirm all 4 modules active
80- Provide login credentials for all created users
81- Provide all application URLs
82
83KNOWN ISSUES TO AVOID:
841. Username case: Use lowercase (e.g., "jarrydz_admin" not "JARRYDZ_admin")
852. USERNAME conflict: Use FLUENT_USERNAME in .env (macOS has system USERNAME variable)
863. Blank screen: Account admin needs retailer context roles added after setup
874. Catalogue cache: Must wait 10 minutes between sample data and inventory install
88
89TEACHING MODE:
90- Explain what each command does before running
91- Define technical terms when first used
92- Show the "why" behind each step
93- Ask if deeper explanation wanted
94
95Begin with Phase 1. Present findings and wait for approval before executing.

Approve Each Phase

Claude Code will execute the setup in phases, requesting approval before each action. For each phase:

Review the proposed commands
Ask questions if anything is unclear
Approve to proceed or request modifications

Expected timeline:

Phases 1–2: ~5 min (prereqs + CLI install)
Phases 3–4: ~3 min (auth + retailer)
Phases 5–6: ~10 min (configs + modules)
Phase 7: ~20 min (sample data, includes required 10-min wait)
Phases 8–9: ~5 min (access + verification)

Known behavior: Claude Code may incorrectly evaluate version numbers (e.g., thinking 22.22.0 is not less than 23). If you are stuck in a loop on environment checks and your Node version is confirmed valid, tell Claude Code explicitly:

`My Node version is [YOUR VERSION] which is within the valid range (>= 20.0.0 < 23.0.0). Skip environment verification and proceed to the next phase.`

When to Stop and Troubleshoot

Stop and seek help if:

Claude Code suggests deleting or overwriting system files outside your project folder
The same phase fails 3+ times with the same error
Claude Code enters a loop (repeating the same action without progress)
Authentication fails repeatedly after verifying credentials are correct
Any command modifies your global Node.js, npm, or other system-level tooling unexpectedly

Normal behavior (don't panic):

Claude Code asks for approval before each action
Some phases take several minutes (especially module installation)
The 10-minute wait during sample data is mandatory and expected
Minor warnings in CLI output (as long as the command succeeds)

If stuck: Describe the issue to Claude Code and ask for an alternative approach, or exit Claude Code and manually run the commands from the Appendix.

Verify Installation

After Phase 9 completes, verify your installation:Check installed modules:

1fluent module list --profile cli-b2c

Expected output:

Module	Version	Status
Core	2.x.x	ACTIVE
Fulfilment	2.x.x	ACTIVE
Order	2.x.x	ACTIVE
Inventory	2.x.x	ACTIVE

Access the OMS web interface:

Application	URL
OMS Console	`https://[ACCOUNT_ID].sandbox.apps.fluentcommerce.com/oms/`
Store App	`https://[ACCOUNT_ID].sandbox.apps.fluentcommerce.com/store/`
Inventory	`https://[ACCOUNT_ID].sandbox.apps.fluentcommerce.com/inventory/`
GraphQL Playground	`https://[ACCOUNT_ID].sandbox.api.fluentretail.com/graphiql`

Result

Upon successful completion, you will have:

Component	Status
Fluent CLI	Installed globally
CLI Profile	Configured and authenticated
Retailer	b2c (ID: 1)
Core Module	Active
Fulfilment Module	Active
Order Module	Active
Inventory Module	Active
Sample Data Loaded	Sample data includes products, locations, networks, and inventory across the B2C reference set.
User Access	Account admin with retailer context

Users created:

User Type	Username	Use For
Account Admin	`[account]_admin`	Full OMS access
Retailer Admin	`b2c_admin`	Retailer operations
Store User (HQ)	`B2C_HQ_1`	Store app
Store User (Sydney)	`B2C_SYD_1`	Store app

Sample data loaded:

Category	Data
Locations	RJT_1, B2C_HQ_1, B2C_SYD_1
Products	AH8050 (1 standard + 6 variants)
Categories	SHOES, MENS_SHOES, WOMENS_SHOES, UNISEX_SHOES
Inventory	150 units per location per SKU
Networks	B2C_GROUP_1, B2C_CC_1, B2C_HD_1, B2C_BASE_1, B2C_ATS_1

Known Behaviors and Troubleshooting

CLI Debug Output on Authentication Failure

If fluent profile create fails authentication, the CLI may print debug output that includes sensitive values.Action: Treat this as a credential exposure. Rotate your password in Fluent, update `.env`, and recreate the CLI profile.

Username Case Sensitivity

Fluent usernames are case-sensitive. Use the exact username provided in your sandbox credentials (typically lowercase).

Environment Variable Conflicts

On macOS, the system `USERNAME` environment variable may conflict with a user-defined `USERNAME` in your `.env` file. Use `FLUENT_USERNAME` to avoid this conflict.

Account Admin Blank Screen

After initial setup, the account admin user may see a blank screen when logging into OMS. This occurs because the user lacks retailer context roles. Phase 8 of the setup prompt addresses this by adding the required roles.

Troubleshooting

Symptom	Cause	Solution
Authentication failed (400 error)	Username case mismatch	Use lowercase username
Wrong username in CLI	Duplicate entries in `.env`	Remove duplicates, keep one correct value
System overrides username	macOS `$USERNAME` variable	Use `FLUENT_USERNAME` in `.env`
Blank OMS screen	Missing retailer context	Add ADMIN/GRAPHQL roles to retailer context
Inventory install fails	Catalogue cache not ready	Wait full 10 minutes after sample data install
`.env` visible in git status	`.gitignore` not configured	Add `.env` to `.gitignore`

Setting Up Fluent Sandbox with Claude Code

Key Points

Steps

Prerequisites

Required Fluent Documentation

Environment Requirements

Fluent Sandbox Credentials

Create Project Directory

Initialize Git with Security Protection

Create Credentials File

Add Fluent Documentation

Verify Security Configuration

Launch Claude Code

Execute Setup Prompt

Approve Each Phase

When to Stop and Troubleshoot

Verify Installation

Result

Known Behaviors and Troubleshooting

CLI Debug Output on Authentication Failure

Username Case Sensitivity

Environment Variable Conflicts

Account Admin Blank Screen

Troubleshooting

Related content

Getting Started with the Fluent CLI

API Authentication

What is a Module

Jarryd Zankovic

Building Blocks

By Type

Helpful Resources

Quick Links